=====
Usage
=====

Initialisation
--------------

To use whispyr in a project you need to have valid whispir.io credentials (username, password and API key)::

  from whispyr import Whispir

  TEST_USERNAME = 'U53RN4M3'
  TEST_PASSWORD = 'P4ZZW0RD'
  TEST_API_KEY = 'V4L1D4P1K3Y'

  whispir = Whispir(TEST_USERNAME, TEST_PASSWORD, TEST_API_KEY)


Available resources
-------------------

Instance of class ``Whispir`` contains all available resources (workspaces, messages, templates, response rules and etc, you can find more on official whispir API documentaion page https://whispir.github.io/api) as its members::

  >>> whispir.workspaces
  <whispyr.whispyr.Workspaces object at 0x10f1c2eb8>
  >>> whispir.messages
  <whispyr.whispyr.Messages object at 0x10f1c2e80>
  ...

Resources in plural form are collections which provide an access to containers. For example ``workspaces`` is a workspace resource and it provides CRUD functionality for workspaces.


Collections actions
-------------------

Each collection has ``create``, ``show``, ``list``, ``update`` and ``delete`` functions to work with objects.
All passed arguments passed as is to json encoder. Library doesn't perform any checks or validations, which means that you need to know required parameters and their format before you can call any of mentioned actions.

create
~~~~~~

``create`` makes a ``POST`` request for a given resource::

  name = 'whispyr tests'
  new_workspace = whispir.workspaces.create(projectName=name, status='A')

returned object is a container for a created resource. For this example it's an instance of ``whispyr.Workspace``::

  from whispyr import Workspace
  assert isinstance(workspace, Workspace)


All containers are dictionary like objects which wraps response from whispir.io API and provides an access to other resources available under some particular instance of an entity.

show
~~~~

``show`` makes a ``GET`` request for a given resource with a provided ID::

  workspace = whispir.workspaces.show(new_workspace['id'])
  assert isinstance(workspace, Workspace)
  assert 'id' in workspace
  assert 'projectName' in workspace


list
~~~~

``list`` makes a ``GET`` request for a given resource to return all available objects (library takes care about pagination)::

  for workspace in whispir.workspaces.list():
      assert isinstance(workspace, Workspace)
      assert 'id' in workspace
      assert 'projectName' in workspace


update
~~~~~~
``update`` makes a ``PUT`` request for a given resource with a provided ID to update/edit a resource with specified parameters::

  whispir.contacts.update(
      contact_id,
      firstName='John',
      lastName='Wick',
      timezone='Australia/Melbourne',
      workCountry='Australia'
  )


delete
~~~~~~

``delete`` makes a ``DELETE`` request for a given resource with a provided ID::

  whispir.contacts.delete(contact['id'])


Container resources
-------------------

Some containers (such as ``whispyr.Workspace`` and ``whispyr.Message``) might provide an access to some collections.

Workspace
~~~~~~~~~

You might find it useful to limit the work to some workspace (sandbox in test env for instance) and do not put all objects in a global space::

  project_name = 'whispyr tests'
  workspace = next(ws for ws in whispir.workspaces.list()
                   if ws['projectName'] == 'sandbox')
  for contact in workspace.contacts.list():
      print(contact['firstName'])

Alternatively, if you know workspace ID::

  workspace = whispir.workspaces.Workspace(id='C3A1B60DEED39BB3')


Message
~~~~~~~~

Message container provides an access to all message's resources such as message statuses and responses::

  message = workspace.messages.send(to=contact['mri'],
                                    subject='whispyr test',
                                    body='test message, please disregard')
  for status in message.statuses.list():
      for category in status['categories']:
          print('{}: {}'.format(category['name'], category['recipientCount']))