Merge pull request #137 from jkeyes/pydoc-api-operations

jkeyes · web-flow · commit 74e211c0bd9e · 2016-11-18T23:38:55.000Z
Add pydocs to the _operations packages.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,6 +1,8 @@
 Changelog
 =========
 
+* 3.0b4
+   * Added conversation.mark_read method. (`#136 <https://github.com/jkeyes/python-intercom/pull/136>`_)
 * 3.0b3
    * Added TokenUnauthorizedError. (`#134 <https://github.com/jkeyes/python-intercom/pull/134>`_)
    * Added UTC datetime everywhere. (`#130 <https://github.com/jkeyes/python-intercom/pull/130>`_)
diff --git a/intercom/api_operations/__init__.py b/intercom/api_operations/__init__.py
@@ -1 +1,2 @@
 # -*- coding: utf-8 -*-
+"""Package for operations that can be performed on a resource."""
diff --git a/intercom/api_operations/all.py b/intercom/api_operations/all.py
@@ -1,12 +1,15 @@
 # -*- coding: utf-8 -*-
+"""Operation to retrieve all instances of a particular resource."""
 
 from intercom import utils
 from intercom.collection_proxy import CollectionProxy
 
 
 class All(object):
+    """A mixin that provides `all` functionality."""
 
     def all(self):
+        """Return a CollectionProxy for the resource."""
         collection = utils.resource_class_to_collection_name(
             self.collection_class)
         finder_url = "/%s" % (collection)
diff --git a/intercom/api_operations/convert.py b/intercom/api_operations/convert.py
@@ -1,9 +1,12 @@
 # -*- coding: utf-8 -*-
+"""Operation to convert a contact into a user."""
 
 
 class Convert(object):
+    """A mixin that provides `convert` functionality."""
 
     def convert(self, contact, user):
+        """Convert the specified contact into the specified user."""
         self.client.post(
             '/contacts/convert',
             {
diff --git a/intercom/api_operations/count.py b/intercom/api_operations/count.py
@@ -1,12 +1,15 @@
 # -*- coding: utf-8 -*-
+"""Operation to retrieve count for a particular resource."""
 
 from intercom import utils
 
 
 class Count(object):
+    """A mixin that provides `count` functionality."""
 
     @classmethod
     def count(cls):
+        """Return the count for the resource."""
         from intercom import Intercom
         response = Intercom.get("/counts/")
         return response[utils.resource_class_to_name(cls)]['count']
diff --git a/intercom/api_operations/delete.py b/intercom/api_operations/delete.py
@@ -1,11 +1,14 @@
 # -*- coding: utf-8 -*-
+"""Operation to delete an instance of a particular resource."""
 
 from intercom import utils
 
 
 class Delete(object):
+    """A mixin that provides `delete` functionality."""
 
     def delete(self, obj):
+        """Delete the specified instance of this resource."""
         collection = utils.resource_class_to_collection_name(
             self.collection_class)
         self.client.delete("/%s/%s" % (collection, obj.id), {})
diff --git a/intercom/api_operations/find.py b/intercom/api_operations/find.py
@@ -1,12 +1,15 @@
 # -*- coding: utf-8 -*-
+"""Operation to find an instance of a particular resource."""
 
 from intercom import HttpError
 from intercom import utils
 
 
 class Find(object):
+    """A mixin that provides `find` functionality."""
 
     def find(self, **params):
+        """Find the instance of the resource based on the supplied parameters."""
         collection = utils.resource_class_to_collection_name(
             self.collection_class)
         if 'id' in params:
diff --git a/intercom/api_operations/find_all.py b/intercom/api_operations/find_all.py
@@ -1,12 +1,15 @@
 # -*- coding: utf-8 -*-
+"""Operation to find all instances of a particular resource."""
 
 from intercom import utils
 from intercom.collection_proxy import CollectionProxy
 
 
 class FindAll(object):
+    """A mixin that provides `find_all` functionality."""
 
     def find_all(self, **params):
+        """Find all instances of the resource based on the supplied parameters."""
         collection = utils.resource_class_to_collection_name(
             self.collection_class)
         if 'id' in params and 'type' not in params:
diff --git a/intercom/api_operations/load.py b/intercom/api_operations/load.py
@@ -1,12 +1,15 @@
 # -*- coding: utf-8 -*-
+"""Operation to load an instance of a particular resource."""
 
 from intercom import HttpError
 from intercom import utils
 
 
 class Load(object):
+    """A mixin that provides `load` functionality."""
 
     def load(self, resource):
+        """Load the resource from the latest data in Intercom."""
         collection = utils.resource_class_to_collection_name(
             self.collection_class)
         if hasattr(resource, 'id'):
diff --git a/intercom/api_operations/save.py b/intercom/api_operations/save.py
@@ -1,41 +1,22 @@
 # -*- coding: utf-8 -*-
+"""Operation to create or save an instance of a particular resource."""
 
 from intercom import utils
 
 
 class Save(object):
+    """A mixin that provides `create` and `save` functionality."""
 
     def create(self, **params):
+        """Create an instance of the resource from the supplied parameters."""
         collection = utils.resource_class_to_collection_name(
             self.collection_class)
         response = self.client.post("/%s/" % (collection), params)
         if response:  # may be empty if we received a 202
             return self.collection_class(**response)
 
-    # def from_dict(self, pdict):
-    #     for key, value in list(pdict.items()):
-    #         setattr(self, key, value)
-
-    # @property
-    # def to_dict(self):
-    #     a_dict = {}
-    #     for name in list(self.__dict__.keys()):
-    #         if name == "changed_attributes":
-    #             continue
-    #         a_dict[name] = self.__dict__[name]  # direct access
-    #     return a_dict
-
-    # @classmethod
-    # def from_api(cls, response):
-    #     obj = cls()
-    #     obj.from_response(response)
-    #     return obj
-
-    # def from_response(self, response):
-    #     self.from_dict(response)
-    #     return self
-
     def save(self, obj):
+        """Save the instance of the resource."""
         collection = utils.resource_class_to_collection_name(
             obj.__class__)
         params = obj.attributes
@@ -50,12 +31,15 @@ def save(self, obj):
             return obj.from_response(response)
 
     def id_present(self, obj):
+        """Return whether the obj has an `id` attribute with a value."""
         return getattr(obj, 'id', None) and obj.id != ""
 
     def posted_updates(self, obj):
+        """Return whether the updates to this object have been posted to Intercom."""
         return getattr(obj, 'update_verb', None) == 'post'
 
     def identity_hash(self, obj):
+        """Return the identity_hash for this object."""
         identity_vars = getattr(obj, 'identity_vars', [])
         parts = {}
         for var in identity_vars:
diff --git a/intercom/extended_api_operations/reply.py b/intercom/extended_api_operations/reply.py
@@ -1,29 +1,40 @@
 # -*- coding: utf-8 -*-
+"""Operations to manage conversations."""
 
 from intercom import utils
 
 
 class Reply(object):
+    """A mixin that provides methods to manage a conversation.
+
+    This includes opening and closing them, assigning them to users, and
+    replying them.
+    """
 
     def reply(self, **reply_data):
+        """Add a reply, created from the supplied paramters, to the conversation."""
         return self.__reply(reply_data)
 
     def close_conversation(self, **reply_data):
+        """Close the conversation."""
         reply_data['type'] = 'admin'
         reply_data['message_type'] = 'close'
         return self.__reply(reply_data)
 
     def open_conversation(self, **reply_data):
+        """Open the conversation."""
         reply_data['type'] = 'admin'
         reply_data['message_type'] = 'open'
         return self.__reply(reply_data)
 
     def assign(self, **reply_data):
+        """Assign the conversation to an admin user."""
         reply_data['type'] = 'admin'
         reply_data['message_type'] = 'assignment'
         return self.__reply(reply_data)
 
     def __reply(self, reply_data):
+        """Send the Conversation requests to Intercom and handl the responses."""
         from intercom import Intercom
         collection = utils.resource_class_to_collection_name(self.__class__)
         url = "/%s/%s/reply" % (collection, self.id)
diff --git a/intercom/extended_api_operations/users.py b/intercom/extended_api_operations/users.py
@@ -1,12 +1,15 @@
 # -*- coding: utf-8 -*-
+"""Operation to return all users for a particular Company."""
 
 from intercom import utils
 from intercom.collection_proxy import CollectionProxy
 
 
 class Users(object):
+    """A mixin that provides `users` functionality to Company."""
 
     def users(self, id):
+        """Return a CollectionProxy to all the users for the specified Company."""
         collection = utils.resource_class_to_collection_name(
             self.collection_class)
         finder_url = "/%s/%s/users" % (collection, id)

Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
`1`	`1`	`# -- coding: utf-8 --`
	`2`	`+"""Package for operations that can be performed on a resource."""`