Refactor Memberships

Apply structural changes to the RoomsAPI and ensure all parameters are up-to-date.

Author: cmlccie

ciscosparkapi/api/memberships.py

@@ -4,8 +4,8 @@
 Classes:
     Membership: Models a Spark 'membership' JSON object as a native Python
         object.
-    MembershipsAPI: Wrappers the Cisco Spark Memberships-API and exposes the
-        API calls as Python method calls that return native Python objects.
+    MembershipsAPI: Wraps the Cisco Spark Memberships-API and exposes the
+        APIs as native Python methods that return native Python objects.
 
 """
 
@@ -20,10 +20,13 @@
 from builtins import *
 from past.builtins import basestring
 
-from ciscosparkapi.exceptions import ciscosparkapiException
-from ciscosparkapi.utils import generator_container
 from ciscosparkapi.restsession import RestSession
 from ciscosparkapi.sparkdata import SparkData
+from ciscosparkapi.utils import (
+    check_type,
+    dict_from_items_with_values,
+    generator_container,
+)
 
 
 __author__ = "Chris Lunsford"
@@ -36,10 +39,10 @@ class Membership(SparkData):
     """Model a Spark 'membership' JSON object as a native Python object."""
 
     def __init__(self, json):
-        """Init a new Membership data object from a JSON dictionary or string.
+        """Initialize a Membership object from a dictionary or JSON string.
 
         Args:
-            json(dict, basestring): Input JSON object.
+            json(dict, basestring): Input dictionary or JSON string.
 
         Raises:
             TypeError: If the input object is not a dictionary or string.
@@ -49,42 +52,55 @@ def __init__(self, json):
 
     @property
     def id(self):
-        return self._json['id']
+        """The membership's unique ID."""
+        return self._json.get('id')
 
     @property
     def roomId(self):
-        return self._json['roomId']
+        """The ID of the room."""
+        return self._json.get('roomId')
 
     @property
     def personId(self):
-        return self._json['personId']
+        """The ID of the person."""
+        return self._json.get('personId')
 
     @property
     def personEmail(self):
-        return self._json['personEmail']
+        """The email address of the person."""
+        return self._json.get('personEmail')
 
     @property
     def personDisplayName(self):
-        return self._json['personDisplayName']
+        """The display name of the person."""
+        return self._json.get('personDisplayName')
+
+    @property
+    def personOrgId(self):
+        """The ID of the organization that the person is associated with."""
+        return self._json.get('personOrgId')
 
     @property
     def isModerator(self):
-        return self._json['isModerator']
+        """Person is a moderator for the room."""
+        return self._json.get('isModerator')
 
     @property
     def isMonitor(self):
-        return self._json['isMonitor']
+        """Person is a monitor for the room."""
+        return self._json.get('isMonitor')
 
     @property
     def created(self):
-        return self._json['created']
+        """The date and time the membership was created."""
+        return self._json.get('created')
 
 
 class MembershipsAPI(object):
     """Cisco Spark Memberships-API wrapper class.
 
-    Wrappers the Cisco Spark Memberships-API and exposes the API calls as
-    Python method calls that return native Python objects.
+    Wraps the Cisco Spark Memberships-API and exposes the APIs as native Python
+    methods that return native Python objects.
 
     """
 
@@ -96,25 +112,28 @@ def __init__(self, session):
                 API calls to the Cisco Spark service.
 
         Raises:
-            AssertionError: If the parameter types are incorrect.
+            TypeError: If the parameter types are incorrect.
 
         """
-        assert isinstance(session, RestSession)
+        check_type(session, RestSession)
+
         super(MembershipsAPI, self).__init__()
+
         self._session = session
 
     @generator_container
-    def list(self, roomId=None, personId=None, personEmail=None, max=None):
+    def list(self, roomId=None, personId=None, personEmail=None, max=None,
+             **request_parameters):
         """List room memberships.
 
-        By default, lists memberships for rooms to which the authenticated
-        user belongs.
+        By default, lists memberships for rooms to which the authenticated user
+        belongs.
 
         Use query parameters to filter the response.
 
-        Use roomId to list memberships for a room, by ID.
+        Use `roomId` to list memberships for a room, by ID.
 
-        Use either personId or personEmail to filter the results.
+        Use either `personId` or `personEmail` to filter the results.
 
         This method supports Cisco Spark's implementation of RFC5988 Web
         Linking to provide pagination support.  It returns a generator
@@ -127,164 +146,153 @@ def list(self, roomId=None, personId=None, personEmail=None, max=None):
         container.
 
         Args:
-            roomId(basestring): List memberships for the room with roomId.
-            personId(basestring): Filter results to include only those with
-                personId.
-            personEmail(basestring): Filter results to include only those
-                with personEmail.
-            max(int): Limits the maximum number of memberships returned from
-                the Spark service per request.
-
+            roomId(basestring): Limit results to a specific room, by ID.
+            personId(basestring): Limit results to a specific person, by ID.
+            personEmail(basestring): Limit results to a specific person, by
+                email address.
+            max(int): Limit the maximum number of items returned from the Spark
+                service per request.
+            **request_parameters: Additional request parameters (provides
+                support for parameters that may be added in the future).
 
         Returns:
-            GeneratorContainer: When iterated, the GeneratorContainer, yields
-                the memberships returned from the Cisco Spark query.
+            GeneratorContainer: A GeneratorContainer which, when iterated,
+                yields the memberships returned by the Cisco Spark query.
 
         Raises:
-            AssertionError: If the parameter types are incorrect.
-            ciscosparkapiException: If a personId or personEmail argument is
-                specified without providing a roomId argument.
+            TypeError: If the parameter types are incorrect.
             SparkApiError: If the Cisco Spark cloud returns an error.
 
         """
-        # Process args
-        assert roomId is None or isinstance(roomId, basestring)
-        assert personId is None or isinstance(personId, basestring)
-        assert personEmail is None or isinstance(personEmail, basestring)
-        assert max is None or isinstance(max, int)
-        params = {}
-        if roomId:
-            params['roomId'] = roomId
-            if personId:
-                params['personId'] = personId
-            elif personEmail:
-                params['personEmail'] = personEmail
-        elif personId or personEmail:
-            error_message = "A roomId must be specified. A personId or " \
-                            "personEmail filter may only be specified when " \
-                            "requesting the memberships for a room with the " \
-                            "roomId argument."
-            raise ciscosparkapiException(error_message)
-        if max:
-            params['max'] = max
+        check_type(roomId, basestring)
+        check_type(personId, basestring)
+        check_type(personEmail, basestring)
+        check_type(max, int)
+
+        params = dict_from_items_with_values(
+                request_parameters,
+                roomId=roomId,
+                personId=personId,
+                personEmail=personEmail,
+                max=max,
+        )
+
         # API request - get items
         items = self._session.get_items('memberships', params=params)
+
         # Yield Person objects created from the returned items JSON objects
         for item in items:
             yield Membership(item)
 
     def create(self, roomId, personId=None, personEmail=None,
-               isModerator=False):
+               isModerator=False, **request_parameters):
         """Add someone to a room by Person ID or email address.
 
         Add someone to a room by Person ID or email address; optionally
         making them a moderator.
 
         Args:
-            roomId(basestring): ID of the room to which the person will be
-                added.
-            personId(basestring): ID of the person to be added to the room.
-            personEmail(basestring): Email address of the person to be added
-                to the room.
-            isModerator(bool): If True, adds the person as a moderator for the
-                room. If False, adds the person as normal member of the room.
+            roomId(basestring): The room ID.
+            personId(basestring): The ID of the person.
+            personEmail(basestring): The email address of the person.
+            isModerator(bool): Set to True to make the person a room moderator.
+            **request_parameters: Additional request parameters (provides
+                support for parameters that may be added in the future).
 
         Returns:
-            Membership: With the details of the created membership.
+            Membership: A Membership object with the details of the created
+                membership.
 
         Raises:
-            AssertionError: If the parameter types are incorrect.
-            ciscosparkapiException: If neither a personId or personEmail are
-                provided.
+            TypeError: If the parameter types are incorrect.
             SparkApiError: If the Cisco Spark cloud returns an error.
 
         """
-        # Process args
-        assert isinstance(roomId, basestring)
-        assert personId is None or isinstance(personId, basestring)
-        assert personEmail is None or isinstance(personEmail, basestring)
-        assert isModerator is None or isinstance(isModerator, bool)
-        post_data = {}
-        post_data['roomId'] = roomId
-        if personId:
-            post_data['personId'] = personId
-        elif personEmail:
-            post_data['personEmail'] = personEmail
-        else:
-            error_message = "personId or personEmail must be provided to " \
-                            "add a person to a room.  Neither were provided."
-            raise ciscosparkapiException(error_message)
-        post_data['isModerator'] = isModerator
+        check_type(roomId, basestring, may_be_none=False)
+        check_type(personId, basestring)
+        check_type(personEmail, basestring)
+        check_type(isModerator, bool)
+
+        post_data = dict_from_items_with_values(
+            request_parameters,
+            roomId=roomId,
+            personId=personId,
+            personEmail=personEmail,
+            isModerator=isModerator,
+        )
+
         # API request
-        json_obj = self._session.post('memberships', json=post_data)
+        json_data = self._session.post('memberships', json=post_data)
+
         # Return a Membership object created from the response JSON data
-        return Membership(json_obj)
+        return Membership(json_data)
 
     def get(self, membershipId):
-        """Get details for a membership by ID.
+        """Get details for a membership, by ID.
 
         Args:
-            membershipId(basestring): The membershipId of the membership.
+            membershipId(basestring): The membership ID.
 
         Returns:
-            Membership: With the details of the requested membership.
+            Membership: A Membership object with the details of the requested
+                membership.
 
         Raises:
-            AssertionError: If the parameter types are incorrect.
+            TypeError: If the parameter types are incorrect.
             SparkApiError: If the Cisco Spark cloud returns an error.
 
         """
-        # Process args
-        assert isinstance(membershipId, basestring)
+        check_type(membershipId, basestring, may_be_none=False)
+
         # API request
-        json_obj = self._session.get('memberships/' + membershipId)
+        json_data = self._session.get('memberships/' + membershipId)
+
         # Return a Membership object created from the response JSON data
-        return Membership(json_obj)
+        return Membership(json_data)
 
-    def update(self, membershipId, **update_attributes):
-        """Update details for a membership.
+    def update(self, membershipId, isModerator=None, **request_parameters):
+        """Updates properties for a membership, by ID.
 
         Args:
-            membershipId(basestring): The membershipId of the membership to
-                be updated.
-            isModerator(bool): If True, sets the person as a moderator for the
-                room. If False, removes the person as a moderator for the room.
+            membershipId(basestring): The membership ID.
+            isModerator(bool): Set to True to make the person a room moderator.
 
         Returns:
-            Membership: With the updated Spark membership details.
+            Membership: A Membership object with the updated Spark membership
+                details.
 
         Raises:
-            AssertionError: If the parameter types are incorrect.
-            ciscosparkapiException: If an update attribute is not provided.
+            TypeError: If the parameter types are incorrect.
             SparkApiError: If the Cisco Spark cloud returns an error.
 
         """
-        # Process args
-        assert isinstance(membershipId, basestring)
-        # Process update_attributes keyword arguments
-        if not update_attributes:
-            error_message = "At least one **update_attributes keyword " \
-                            "argument must be specified."
-            raise ciscosparkapiException(error_message)
+        check_type(membershipId, basestring, may_be_none=False)
+        check_type(isModerator, bool)
+
+        put_data = dict_from_items_with_values(
+            request_parameters,
+            isModerator=isModerator,
+        )
+
         # API request
-        json_obj = self._session.put('memberships/' + membershipId,
-                                     json=update_attributes)
+        json_data = self._session.put('memberships/' + membershipId,
+                                     json=put_data)
+
         # Return a Membership object created from the response JSON data
-        return Membership(json_obj)
+        return Membership(json_data)
 
     def delete(self, membershipId):
         """Delete a membership, by ID.
 
         Args:
-            membershipId(basestring): The membershipId of the membership to
-                be deleted.
+            membershipId(basestring): The membership ID.
 
         Raises:
-            AssertionError: If the parameter types are incorrect.
+            TypeError: If the parameter types are incorrect.
             SparkApiError: If the Cisco Spark cloud returns an error.
 
         """
-        # Process args
-        assert isinstance(membershipId, basestring)
+        check_type(membershipId, basestring)
+
         # API request
         self._session.delete('memberships/' + membershipId)