Add flexible models and factory functions

Add examples for flexible data models:

* `simple_data_factory` (`SimpleDataModel`) - A simple data model that assigns all of the top-level JSON attributes to Python object attributes.
* `dict_data_factory` - An object factory that returns the Spark data objects as parsed ordered dictionaries.

Author: cmlccie

ciscosparkapi/__init__.py

@@ -33,7 +33,8 @@
 )
 from .models import (
     AccessToken, Event, License, Membership, Message, Organization, Person,
-    Role, Room, Team, TeamMembership, Webhook, WebhookEvent, sparkdata_factory,
+    Role, Room, Team, TeamMembership, Webhook, WebhookEvent, dict_data_factory,
+    simple_data_factory, spark_data_factory,
 )
 from .restsession import (
     DEFAULT_SINGLE_REQUEST_TIMEOUT,
@@ -106,7 +107,7 @@ def __init__(self, access_token=None, base_url=DEFAULT_BASE_URL,
                  timeout=None,
                  single_request_timeout=DEFAULT_SINGLE_REQUEST_TIMEOUT,
                  wait_on_rate_limit=DEFAULT_WAIT_ON_RATE_LIMIT,
-                 object_factory=sparkdata_factory):
+                 object_factory=spark_data_factory):
         """Create a new CiscoSparkAPI object.
 
         An access token must be used when interacting with the Cisco Spark API.

ciscosparkapi/models/__init__.py

@@ -20,11 +20,13 @@
 from .person import PersonBasicPropertiesMixin
 from .role import RoleBasicPropertiesMixin
 from .room import RoomBasicPropertiesMixin
+from .simple import SimpleDataModel
 from .sparkdata import SparkData
 from .team import TeamBasicPropertiesMixin
 from .team_membership import TeamMembershipBasicPropertiesMixin
 from .webhook import WebhookBasicPropertiesMixin
 from .webhook_event import WebhookEventBasicPropertiesMixin
+from ..utils import json_dict
 
 
 __author__ = "Chris Lunsford"
@@ -85,7 +87,7 @@ class WebhookEvent(SparkData, WebhookEventBasicPropertiesMixin):
     """Cisco Spark Webhook-Events data model."""
 
 
-sparkdata_models = defaultdict(
+spark_data_models = defaultdict(
     lambda: SparkData,
     access_token=AccessToken,
     event=Event,
@@ -103,7 +105,7 @@ class WebhookEvent(SparkData, WebhookEventBasicPropertiesMixin):
 )
 
 
-def sparkdata_factory(model, json_data):
+def spark_data_factory(model, json_data):
     """Factory function for creating SparkData objects.
 
     Args:
@@ -120,4 +122,45 @@ def sparkdata_factory(model, json_data):
             dictionary.
 
     """
-    return sparkdata_models[model](json_data)
+    return spark_data_models[model](json_data)
+
+
+def simple_data_factory(model, json_data):
+    """Factory function for creating SimpleDataModel objects.
+
+    Args:
+        model(basestring): The data model to use when creating the SparkData
+            object (message, room, membership, etc.).
+        json_data(basestring, dict): The JSON string or dictionary data with
+            which to initialize the object.
+
+    Returns:
+        SimpleDataModel: The created SimpleDataModel object.
+
+    Raises:
+        TypeError: If the json_data parameter is not a JSON string or
+            dictionary.
+
+    """
+    return SimpleDataModel(json_data)
+
+
+def dict_data_factory(model, json_data):
+    """Factory function for creating SimpleDataModel objects.
+
+    Args:
+        model(basestring): The data model to use when creating the SparkData
+            object (message, room, membership, etc.).
+        json_data(basestring, dict): The JSON string or dictionary data with
+            which to initialize the object.
+
+    Returns:
+        OrderedDict: An ordered dictionary with the contents of the Spark JSON
+            object.
+
+    Raises:
+        TypeError: If the json_data parameter is not a JSON string or
+            dictionary.
+
+    """
+    return json_dict(json_data)

ciscosparkapi/models/simple.py

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+"""Simple data model; models Spark JSON objects as simple Python objects.
+
+Classes:
+    SimpleDataModel: Models Spark JSON objects as simple Python objects.
+
+The SimpleDataModel class models any JSON object passed to it as a string or
+Python dictionary as a native Python object; providing attribute access using
+native dot-syntax.
+
+"""
+
+
+from __future__ import (
+    absolute_import,
+    division,
+    print_function,
+    unicode_literals,
+)
+
+from builtins import *
+import json
+
+from ..utils import json_dict
+
+
+__author__ = "Chris Lunsford"
+__author_email__ = "[email protected]"
+__copyright__ = "Copyright (c) 2016-2018 Cisco and/or its affiliates."
+__license__ = "MIT"
+
+
+class SimpleDataModel(object):
+    """Model a Spark JSON object as a simple Python object."""
+
+    def __init__(self, json_data):
+        """Init a new SparkData object from a dictionary or JSON string.
+
+        Args:
+            json_data(dict, basestring): Input JSON string or dictionary.
+
+        Raises:
+            TypeError: If the input object is not a dictionary or string.
+
+        """
+        super(SimpleDataModel, self).__init__()
+        for attribute, value in json_dict(json_data).items():
+            setattr(self, attribute, value)
+
+    def __str__(self):
+        """A human-readable string representation of this object."""
+        return json.dumps(self.__dict__, ensure_ascii=False, indent=4)
+
+    def __repr__(self):
+        """A string representing this object as valid Python expression."""
+        class_str = self.__class__.__name__
+        json_str = json.dumps(self.__dict__, ensure_ascii=False)
+        return "{}({})".format(class_str, repr(json_str))

ciscosparkapi/models/sparkdata.py

@@ -19,10 +19,9 @@
 )
 
 from builtins import *
-from collections import OrderedDict
 import json
 
-from past.builtins import basestring
+from ..utils import json_dict
 
 
 __author__ = "Chris Lunsford"
@@ -31,30 +30,6 @@
 __license__ = "MIT"
 
 
-def _json_dict(json_data):
-    """Given a dictionary or JSON string; return a dictionary.
-
-    Args:
-        json_data(dict, str): Input JSON object.
-
-    Returns:
-        A Python dictionary with the contents of the JSON object.
-
-    Raises:
-        TypeError: If the input object is not a dictionary or string.
-
-    """
-    if isinstance(json_data, dict):
-        return json_data
-    elif isinstance(json_data, basestring):
-        return json.loads(json_data, object_hook=OrderedDict)
-    else:
-        raise TypeError(
-            "'json_data' must be a dictionary or valid JSON string; "
-            "received: {!r}".format(json_data)
-        )
-
-
 class SparkData(object):
     """Model a Spark JSON object as a native Python object."""
 
@@ -69,7 +44,7 @@ def __init__(self, json_data):
 
         """
         super(SparkData, self).__init__()
-        self._json_data = _json_dict(json_data)
+        self._json_data = json_dict(json_data)
 
     def __getattr__(self, item):
         """Provide native attribute access to the JSON object attributes.
@@ -113,7 +88,7 @@ def __repr__(self):
         """A string representing this object as valid Python expression."""
         class_str = self.__class__.__name__
         json_str = json.dumps(self._json_data, ensure_ascii=False)
-        return "{}({})".format(class_str, json_str)
+        return "{}({})".format(class_str, repr(json_str))
 
     @property
     def json_data(self):

ciscosparkapi/utils.py

@@ -204,3 +204,27 @@ def extract_and_parse_json(response):
 
     """
     return json.loads(response.text, object_hook=OrderedDict)
+
+
+def json_dict(json_data):
+    """Given a dictionary or JSON string; return a dictionary.
+
+    Args:
+        json_data(dict, str): Input JSON object.
+
+    Returns:
+        A Python dictionary with the contents of the JSON object.
+
+    Raises:
+        TypeError: If the input object is not a dictionary or string.
+
+    """
+    if isinstance(json_data, dict):
+        return json_data
+    elif isinstance(json_data, basestring):
+        return json.loads(json_data, object_hook=OrderedDict)
+    else:
+        raise TypeError(
+            "'json_data' must be a dictionary or valid JSON string; "
+            "received: {!r}".format(json_data)
+        )