From f9860dc68900493ad0e22887ef35997e26e50158 Mon Sep 17 00:00:00 2001 From: John Keyes Date: Fri, 18 Nov 2016 23:07:37 +0000 Subject: [PATCH] Add pydocs to the _operations packages. --- CHANGES.rst | 2 ++ intercom/api_operations/__init__.py | 1 + intercom/api_operations/all.py | 3 +++ intercom/api_operations/convert.py | 3 +++ intercom/api_operations/count.py | 3 +++ intercom/api_operations/delete.py | 3 +++ intercom/api_operations/find.py | 3 +++ intercom/api_operations/find_all.py | 3 +++ intercom/api_operations/load.py | 3 +++ intercom/api_operations/save.py | 30 ++++++----------------- intercom/extended_api_operations/reply.py | 11 +++++++++ intercom/extended_api_operations/users.py | 3 +++ 12 files changed, 45 insertions(+), 23 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index c70db8f4..879ed9e2 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,6 +1,8 @@ Changelog ========= +* 3.0b4 + * Added conversation.mark_read method. (`#136 `_) * 3.0b3 * Added TokenUnauthorizedError. (`#134 `_) * Added UTC datetime everywhere. (`#130 `_) diff --git a/intercom/api_operations/__init__.py b/intercom/api_operations/__init__.py index 40a96afc..66c2a467 100644 --- 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 index 04a5ab73..ec571385 100644 --- 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 index 43e2ac98..f1115f7f 100644 --- 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 index 70a22e18..d87f6e33 100644 --- 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 index 68a9501d..f9ea71dc 100644 --- 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 index 986d692a..013665b9 100644 --- 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 index d0933724..cd8b251e 100644 --- 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 index 266113ca..82aca451 100644 --- 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 index b90a0ea3..ada32fbd 100644 --- 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 index 30ff089c..18f47087 100644 --- 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 index 33a2a44f..b4406b42 100644 --- 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)