Initial PeopleAPI wrapper

Add wrapper classes for the Cisco Spark People-API.

Author: cmlccie

ciscosparkapi/__init__.py

@@ -1,6 +1,7 @@
 from exceptions import ciscosparkapiException, SparkApiError
 from restsession import RestSession
 from api.rooms import Room, RoomsAPI
+from api.people import Person, PeopleAPI
 
 
 class CiscoSparkAPI(object):
@@ -13,12 +14,16 @@ def __init__(self, access_token, base_url=None, timeout=None):
         session_args = {}
         if base_url:  session_args['base_url'] = base_url
         if timeout:  session_args['timeout'] = timeout
-        # Create API session - All of the API calls associated with a
-        # CiscoSparkAPI object will leverage a single RESTful 'session'
-        # connecting to the Cisco Spark cloud.
+
+        # Create API session
+        # All of the API calls associated with a CiscoSparkAPI object will
+        # leverage a single RESTful 'session' connecting to the Cisco Spark
+        # cloud.
         self.session = RestSession(access_token, **session_args)
-        # Setup Spark API wrappers
+
+        # Spark API wrappers
         self.rooms = RoomsAPI(self.session)
+        self.people = PeopleAPI(self.session)
 
     @property
     def access_token(self):

ciscosparkapi/api/people.py

@@ -0,0 +1,170 @@
+"""Cisco Spark People-API wrapper classes.
+
+Classes:
+    Person: Models a Spark 'person' JSON object as a native Python object.
+    PeopleAPI: Wrappers the Cisco Spark People-API and exposes the API calls as
+        Python method calls that return native Python objects.
+
+"""
+
+
+from ciscosparkapi.exceptions import ciscosparkapiException
+from ciscosparkapi.helper import utf8, generator_container
+from ciscosparkapi.restsession import RestSession
+from ciscosparkapi.sparkdata import SparkData
+
+
+class Person(SparkData):
+    """Model a Spark 'person' JSON object as a native Python object."""
+
+    def __init__(self, json):
+        """Init a new Person data object from a JSON dictionary or string.
+
+        Args:
+            json(dict, unicode, str): Input JSON object.
+
+        Raises:
+            TypeError: If the input object is not a dictionary or string.
+
+        """
+        super(Person, self).__init__(json)
+
+    @property
+    def id(self):
+        return self._json[u'id']
+
+    @property
+    def emails(self):
+        return self._json[u'emails']
+
+    @property
+    def displayName(self):
+        return self._json[u'displayName']
+
+    @property
+    def avatar(self):
+        return self._json[u'avatar']
+
+    @property
+    def created(self):
+        return self._json[u'created']
+
+    @property
+    def lastActivity(self):
+        return self._json[u'lastActivity']
+
+    @property
+    def status(self):
+        return self._json[u'status']
+
+
+class PeopleAPI(object):
+    """Cisco Spark People-API wrapper class.
+
+    Wrappers the Cisco Spark People-API and exposes the API calls as Python
+    method calls that return native Python objects.
+
+    Attributes:
+        session(RestSession): The RESTful session object to be used for API
+            calls to the Cisco Spark service.
+
+    """
+
+    def __init__(self, session):
+        """Init a new PeopleAPI object with the provided RestSession.
+
+        Args:
+            session(RestSession): The RESTful session object to be used for
+                API calls to the Cisco Spark service.
+
+        Raises:
+            AssertionError: If the parameter types are incorrect.
+
+        """
+        assert isinstance(session, RestSession)
+        super(PeopleAPI, self).__init__()
+        self.session = session
+
+    @generator_container
+    def list(self, email=None, displayName=None, max=None):
+        """List people by email or displayName.
+
+        An email address or displayName must be provided.
+
+        This method supports Cisco Spark's implmentation of RFC5988 Web Linking
+        to provide pagination support.  It returns a generator container that
+        incrementally yield all people returned by the query.  The generator
+        will automatically request additional 'pages' of responses from Spark
+        as needed until all responses have been returned.  The container makes
+        the generator safe for reuse.  A new API call will be made, using the
+        same parameters that were specified when the generator was created,
+        every time a new iterator is requested from the container.
+
+        Args:
+            email(unicode, str): The e-mail address of the person to be found.
+            displayName(unicode, str): The complete or beginning portion of
+                the displayName to be searched.
+            max(int): Limits the maximum number of people returned from the
+                Spark service per request.
+
+        Yields:
+            Person: The the next person from the Cisco Spark query.
+
+        Raises:
+            AssertionError: If the parameter types are incorrect.
+            ciscosparkapiException: If neither an email or displayName argument
+                is specified.
+            SparkApiError: If the Cisco Spark cloud returns an error.
+
+        """
+        # Process args
+        assert email is None or isinstance(email, basestring)
+        assert displayName is None or isinstance(displayName, basestring)
+        assert max is None or isinstance(max, int)
+        params = {}
+        if email:
+            params[u'email'] = email
+        elif displayName:
+            params[u'displayName'] = displayName
+        else:
+            error_message = "An email or displayName argument must be " \
+                            "specified."
+            raise ciscosparkapiException(error_message)
+        if max:
+            params[u'max'] = max
+        # API request - get items
+        items = self.session.get_items('people', params=params)
+        # Yield Person objects created from the returned items JSON objects
+        for item in items:
+            yield Person(item)
+
+    def get(self, personId):
+        """Get person details, by personId.
+
+        Args:
+            personId(unicode, str): The personID of the person.
+
+        Raises:
+            AssertionError: If the parameter types are incorrect.
+            SparkApiError: If the Cisco Spark cloud returns an error.
+
+        """
+        # Process args
+        assert isinstance(personId, basestring)
+        # API request
+        json_obj = self.session.get('people/'+personId)
+        # Return a Person object created from the response JSON data
+        return Person(json_obj)
+
+
+    def me(self):
+        """Get the person details of the account accessing the API 'me'.
+
+        Raises:
+            SparkApiError: If the Cisco Spark cloud returns an error.
+
+        """
+        # API request
+        json_obj = self.session.get('people/me')
+        # Return a Person object created from the response JSON data
+        return Person(json_obj)