Document TaskRouter and move DependentPhoneNumbers down one level

twilio · skimbrel · Mar 10, 2015 · Feb 24, 2015 · Feb 25, 2015 · Feb 25, 2015
commit 11e2226a7239341b9f9b2c35ca515fe2ee385a1b
diff --git a/docs/api.rst b/docs/api.rst
@@ -9,6 +9,7 @@ A complete API reference to the :data:`twilio` module.
 
    api/rest/index
    api/rest/resources
+   api/rest/resources/task_router
    api/twiml
    api/util
 
diff --git a/docs/api/rest/index.rst b/docs/api/rest/index.rst
@@ -18,3 +18,6 @@
    :members:
    :inherited-members:
 
+.. autoclass:: TwilioTaskRouterClient
+   :members:
+   :inherited-members:
diff --git a/docs/api/rest/resources/task_router.rst b/docs/api/rest/resources/task_router.rst
@@ -0,0 +1,103 @@
+.. module:: twilio.rest.resources.task_router
+
+========================================
+:mod:`twilio.rest.resources.task_router`
+========================================
+
+
+Workspaces
+>>>>>>>>>>
+
+.. autoclass:: Workspaces
+   :members:
+   :exclude-members: instance
+
+
+Workflows
+>>>>>>>>>
+
+.. autoclass:: Workflows
+   :members:
+   :exclude-members: instance
+
+.. autoclass:: Workflow
+
+Activities
+>>>>>>>>>>
+
+.. autoclass:: Activities
+   :members:
+   :exclude-members: instance
+
+.. autoclass:: Activity
+    .. attribute:: sid
+
+        The unique ID for this Activity.
+
+    .. attribute:: account_sid
+
+        The unique ID of the Account that owns this Activity.
+
+    .. attribute:: workspace_sid
+
+        The unique ID of the :class:`Workspace` that owns this Activity.
+
+    .. attribute:: friendly_name
+
+        A human-readable name for the Activity, such as 'on-call', 'break',
+        'email', etc. These names will be used to calculate and expose
+        statistics about workers, and give you visibility into the state of
+        each of your workers.
+
+    .. attribute:: available
+
+        Boolean value indicating whether the worker should be eligible to
+        receive a Task when they occupy this Activity. For example, in an
+        activity called 'On Call', the worker would be unavailable to receive
+        additional Task assignments.
+
+    .. attribute:: date_created
+
+        The date this Activity was created, given as UTC in ISO 8601 format.
+
+    .. attribute:: date_updated
+
+        The date this Activity was last updated, given as UTC in ISO 8601
+        format.
+
+Workers
+>>>>>>>>>>
+
+.. autoclass:: Workers
+   :members:
+   :exclude-members: instance
+
+.. autoclass:: Worker
+
+TaskQueues
+>>>>>>>>>>
+
+.. autoclass:: TaskQueues
+   :members:
+   :exclude-members: instance
+
+.. autoclass:: TaskQueue
+
+Tasks
+>>>>>>>>>>
+
+.. autoclass:: Tasks
+   :members:
+   :exclude-members: instance
+
+.. autoclass:: Task
+
+Events
+>>>>>>>>>>
+
+.. autoclass:: Events
+   :members:
+   :exclude-members: instance
+
+.. autoclass:: Event
diff --git a/twilio/rest/__init__.py b/twilio/rest/__init__.py
@@ -88,23 +88,12 @@ def __init__(self, account=None, token=None, base="https://api.twilio.com",
 and be sure to replace the values for the Account SID and auth token with the
 values from your Twilio Account at https://www.twilio.com/user/account.
 """)
-
         self.base = base
         self.auth = (account, token)
         self.timeout = timeout
         self.account_uri = "{0}/{1}/Accounts/{2}".format(base,
                                                          version, account)
 
-    def dependent_phone_numbers(self, address_sid):
-        """
-        Return a :class:`DependentPhoneNumbers
-        <twilio.rest.resources.DependentPhoneNumbers>` instance for the
-        :class:`Address <twilio.rest.resources.Address>` with the given
-        address_sid
-        """
-        base_uri = "%s/Addresses/%s" % (self.account_uri, address_sid)
-        return DependentPhoneNumbers(base_uri, self.auth, self.timeout)
-
     def request(self, path, method=None, vars=None):
         """sends a request and gets a response from the Twilio REST API
 
@@ -237,6 +226,16 @@ def feedback(self, call_sid):
         )
         return CallFeedback(call_feedback_list)
 
+    def dependent_phone_numbers(self, address_sid):
+        """
+        Return a :class:`DependentPhoneNumbers
+        <twilio.rest.resources.DependentPhoneNumbers>` instance for the
+        :class:`Address <twilio.rest.resources.Address>` with the given
+        address_sid
+        """
+        base_uri = "%s/Addresses/%s" % (self.account_uri, address_sid)
+        return DependentPhoneNumbers(base_uri, self.auth, self.timeout)
+
 
 class TwilioTaskRouterClient(TwilioClient):
     """

diff --git a/twilio/rest/resources/task_router/activities.py b/twilio/rest/resources/task_router/activities.py
@@ -3,7 +3,45 @@
 
 class Activity(NextGenInstanceResource):
     """
-    An Activity resource
+    An Activity resource.
+    See the `TaskRouter API reference
+    <https://www.twilio.com/docs/taskrouter/activities>_`
+    for more information.
+
+    .. attribute:: sid
+
+        The unique ID for this Activity.
+
+    .. attribute:: account_sid
+
+        The unique ID of the Account that owns this Activity.
+
+    .. attribute:: workspace_sid
+
+        The unique ID of the :class:`Workspace` that owns this Activity.
+
+    .. attribute:: friendly_name
+
+        A human-readable name for the Activity, such as 'on-call', 'break',
+        'email', etc. These names will be used to calculate and expose
+        statistics about workers, and give you visibility into the state of
+        each of your workers.
+
+    .. attribute:: available
+2364
+        Boolean value indicating whether the worker should be eligible to
+        receive a Task when they occupy this Activity. For example, in an
+        activity called 'On Call', the worker would be unavailable to receive
+        additional Task assignments.
+
+    .. attribute:: date_created
+
+        The date this Activity was created, given as UTC in ISO 8601 format.
+
+    .. attribute:: date_updated
+
+        The date this Activity was last updated, given as UTC in ISO 8601
+        format.
     """
 
     def delete(self):

diff --git a/twilio/rest/resources/task_router/events.py b/twilio/rest/resources/task_router/events.py
@@ -5,7 +5,42 @@
 
 
 class Event(NextGenInstanceResource):
-    """ A taskrouter event resource """
+    """An Event resource representing a state change in a TaskRouter
+    Workspace.
+
+    See the `TaskRouter API reference
+    <https://www.twilio.com/docs/taskrouter/events>_`
+    for more information.
+
+    .. attribute:: event_type
+
+        An identifier for this event.
+
+    .. attribute:: account_sid
+
+        The unique ID of the Account that owns this Event.
+
+    .. attribute:: description
+
+        A description of the event.
+
+    .. attribute:: resource_type
+
+        The type of object this event is most relevant to (:class:`Task`,
+        :class:`Reservation`, :class:`Worker`).
+
+    .. attribute:: resource_sid
+
+        The unique ID of the object this event is most relevant to.
+
+    .. attribute:: event_date
+
+        The time this event was sent, in UTC ISO 8601 format.
+
+    .. attribute:: event_data
+
+        Data about this specific Event.
+    """
     pass
 
 
@@ -16,11 +51,12 @@ class Events(NextGenListResource):
     def list(self, **kwargs):
         """
         Returns a page of :class:`Event` resources as a list. For paging
-        information see :class:`NextGenListResource`
+            information see :class:`NextGenListResource`
+
         :param minutes: (Optional, Default=15) Definition of the interval in
-                        minutes prior to now.
+            minutes prior to now.
         :param start_date: (Optional, Default=15 minutes prior) Filter events
-                            by a start date.
+            by a start date.
         :param end_date: (Optional, Default=Now) Filter events by an end date.
         :param resource_sid: (Optional) Sid of the event resource.
         :param event_type: (Optional) The type of event to filter by.
@@ -32,6 +68,7 @@ def get_instances(self, params):
         Query the list resource for a list of InstanceResources.
         Raises a :exc:`~twilio.TwilioRestException` if requesting a page of
         results that does not exist.
+
         :param dict params: List of URL parameters to be included in request
         :param str page_token: Token of the page of results to retrieve
         :param int page_size: The number of results to be returned.

diff --git a/twilio/rest/resources/task_router/reservations.py b/twilio/rest/resources/task_router/reservations.py
@@ -3,7 +3,41 @@
 
 class Reservation(NextGenInstanceResource):
     """
-    A Reservation resource
+    A Reservation resource.
+
+    See the `TaskRouter API reference
+    <https://www.twilio.com/docs/taskrouter/tasks#reservation>_`
+    for more information.
+
+    .. attribute:: sid
+
+        The unique ID of this Reservation.
+
+    .. attribute:: account_Sid
+
+        The unique ID of the Account that owns this :class:`Task`.
+
+    .. attribute:: workspace_sid
+
+        The unique ID of the :class:`Workspace` that contains this
+        :class:`Task`.
+
+    .. attribute:: task_sid
+
+        The unique ID of the reserved :class:`Task`.
+
+    .. attribute:: worker_sid
+
+        The unique ID of the reserved :class:`Worker`.
+
+    .. attribute:: worker_name
+
+        Human-readable description of the reserved Worker.
+
+    .. attribute:: reservation_status
+
+        The current status of the reservation. One of 'pending',
+        'accepted', 'rejected', or 'timeout'.
     """
 
     def update(self, **kwargs):

diff --git a/twilio/rest/resources/task_router/statistics.py b/twilio/rest/resources/task_router/statistics.py
@@ -2,6 +2,14 @@
 
 
 class StatisticsInstance(NextGenInstanceResource):
+    """
+    A resource representing collected statistics about TaskRouter
+    resources.
+
+    See the `TaskRouter API reference
+    <https://www.twilio.com/docs/taskrouter/statistics>_`
+    for more information.
+    """
     def __init__(self, parent):
         self.parent = parent
         super(StatisticsInstance, self).__init__(

diff --git a/twilio/rest/resources/task_router/task_queues.py b/twilio/rest/resources/task_router/task_queues.py
@@ -4,7 +4,43 @@
 
 class TaskQueue(NextGenInstanceResource):
     """
-    A TaskQueue resource
+    A TaskQueue resource.
+
+    See the `TaskRouter API reference
+    <https://www.twilio.com/docs/taskrouter/taskqueues>_`
+    for more information.
+
+    .. attribute:: sid
+
+        The unique ID of this TaskQueue.
+
+    .. attribute:: account_sid
+
+        The unique ID of the account that owns this TaskQueue.
+
+    .. attribute:: workspace_sid
+
+        The unique ID of the :class:`Workspace` that contains this TaskQueue.
+
+    .. attribute:: friendly_name
+
+        Human-readable description of this TaskQueue (e.g. "Customer Support"
+        or "Sales").
+
+    .. attribute:: target_workers
+
+        The worker selection expressions associated with this TaskQueue.
+
+    .. attribute:: reservation_activity_sid
+
+        The :class:`Activity` to assign a :class:`Worker` when they are
+        reserved for a :class:`Task` from this TaskQueue. Defaults to
+        'Reserved for Task'.
+
+    .. attribute:: assignment_activity_sid
+
+        The Activity to assign a Worker when they accept a Task from this
+        Taskqueue. Defaults to 'Unavailable for Assignment'.
     """
     subresources = [
         Statistics,