Merge branch 'python-2-3' into development

Author: cmlccie

README.md

@@ -2,28 +2,46 @@
 Simple, lightweight and scalable Python API wrapper for the Cisco Spark APIs
 
 ## Overview
-A single Pythonic wrapper class representing the Cisco Spark API interfaces and returned JSON objects as method calls that return native Python objects.
+Provides single Pythonic wrapper class that represents the Cisco Spark API interfaces and returned JSON objects as native Python objects.
 
+ * Supports Python versions 2 and 3.
+ 
  * Leverages generator containers and RFC5988 web linking to provide simple and efficient 'paging' of Cisco Spark data objects returned by the Cisco Spark clout.
 
  * All Cisco Spark JSON objects and attributes are represented as native python objects.
    * As new Cisco Spark attributes are added and returned by the Spark cloud service, they will be automatically available in the respective Python objects - no library update required.
    * New object types can be quickly created and modeled by via the generic SparkData class, or you can easily subclass SparkData to provide additional functionality.
 
- * The CiscoSparkAPI class facilitates the creation of simple 'connection objects' that are associated with the access_token used to create the object.  All API calls are wrapped by this single class, and are available via a simple hierarchical structure - like api.rooms.list().
-   * API defaults are provided to make getting connected simple, and can be easily overridden if needed.
-   * The only setting required to get connected is your Cisco Spark Access Token (see [developer.ciscospark.com](https://developer.ciscospark.com/getting-started.html)).
+ * The CiscoSparkAPI class facilitates the creation of simple 'connection objects.'  All API calls are wrapped by this single class, and are available via a simple hierarchical structure - like CiscoSparkAPI.rooms.list().
+   * Argument defaults are provided to make getting connected simple, and can be easily overridden if needed.
+   * The only setting required to get connected is your Cisco Spark Access Token (see [developer.ciscospark.com](https://developer.ciscospark.com/getting-started.html)).  When creating a new CiscoSparkAPI object, you may provide your access token one of two ways:
+     1. By setting a SPARK_ACCESS_TOKEN environment variable.
+     2. Via the ```CiscoSparkAPI(access_token="")``` argument.
    * All API calls are provided as simple method calls on the API connection objects.
 
-### Examples
+
+## Installation
+ciscosparkapi is available on PyPI.  Install it via PIP, or alternatively you can download the package from GitHub and install it via setuptools.
+
+**PIP Installation**
+```
+$ pip install ciscosparkapi
+```
+
+**git / setuptools Installation**
+```
+$ git clone https://github.com/CiscoDevNet/ciscosparkapi.git
+$ python setup.py install
+```
+
+## Examples
 
 ```python
-import os
 from ciscosparkapi import CiscoSparkAPI
 
 
-access_token = os.environ['SPARK_ACCESS_TOKEN']
-api = CiscoSparkAPI(access_token, timeout=60)
+# By default retrieves your access token from the SPARK_ACCESS_TOKEN environement variable
+api = CiscoSparkAPI()
 
 
 rooms = api.rooms.list()    # Returns an generator container providing support for RFC5988 paging
@@ -32,22 +50,24 @@ for room in rooms:          # Efficiently iterates through returned objects
 
 
 # Creating a list from the returned generator containers is easy
-team_list = list(api.teams.list())
-print team_list
+teams = api.teams.list()
+team_list = list(teams)
+print teams_list
 ```
 
 
-## Community Development Project Information
-This is a collaborative community development project to create two packages to be published to the Python Package Index:
+## Current Status
+**Beta(s) Released!**
 
-  1. [**ciscosparkapi**](https://github.com/CiscoDevNet/ciscosparkapi) - A simple, scalable and lightweight API wrapper for the Cisco Spark services APIs
-  2. [**ciscosparksdk**](https://github.com/CiscoDevNet/ciscosparksdk) - Additional features and functionality useful to Cisco Spark API developers
+Please check the [releases page](https://github.com/CiscoDevNet/ciscosparkapi/releases) for details on the latest releases.
 
-All are welcome to contribute to this project.  Information on contributing this project can be found [here in the project Charter](https://github.com/CiscoDevNet/spark-python-packages-team/blob/master/Charter.md).
+We have released the first beta distributions for this package!  Please test out the package for your use cases, and raise [issues](https://github.com/CiscoDevNet/ciscosparkapi/issues) for any problems you encounter.  Also, **PLEASE** create new [issues](https://github.com/CiscoDevNet/ciscosparkapi/issues) to provide any feedback on the package API structure (names, method calls and etc.).  The package APIs are still subject to change, and we would like to get these nailed down before we release v1 for the package.
 
-## Current Status
-**Wrappers for all Cisco API endpoints and data objects have now been completed!**
 
+## Community Development Project Information
+This is a collaborative community development project working to create two packages to be published to the Python Package Index:
+
+  1. [**ciscosparkapi**](https://github.com/CiscoDevNet/ciscosparkapi) - Simple, lightweight and scalable Python API wrapper for the Cisco Spark APIs
+  2. [**ciscosparksdk**](https://github.com/CiscoDevNet/ciscosparksdk) - Additional features and functionality useful to developers building on Cisco Spark API
 
-_Beta release imminent._
-We are preparing to release the first _beta_ for this package.  Please test out the package for your use cases, and raise issues for any problems you encounter.  Also, **PLEASE** create new issues to provide feedback and foster discussion on the package API structure (names, method calls and etc.).  The package APIs are still subject to change, and I would like to get these nailed down before we release v1 for the package.
+Contributions and feedback are welcome.  Information on contributing this project can be found [here in the project Charter](https://github.com/CiscoDevNet/spark-python-packages-team/blob/master/Charter.md).

ciscosparkapi/__init__.py

@@ -1,26 +1,31 @@
+# -*- coding: utf-8 -*-
 """Python API wrapper for the Cisco Spark APIs."""
 
 
+from __future__ import absolute_import
+from builtins import object
+from six import string_types
+
+import os
+
+from .exceptions import ciscosparkapiException, SparkApiError
+from .restsession import RestSession
+from .api.accesstokens import AccessToken, AccessTokensAPI
+from .api.people import Person, PeopleAPI
+from .api.rooms import Room, RoomsAPI
+from .api.memberships import Membership, MembershipsAPI
+from .api.messages import Message, MessagesAPI
+from .api.teams import Team, TeamsAPI
+from .api.teammemberships import TeamMembership, TeamMembershipsAPI
+from .api.webhooks import Webhook, WebhooksAPI
+
+
 # Versioneer version control
 from ._version import get_versions
 __version__ = get_versions()['version']
 del get_versions
 
 
-import os
-
-from exceptions import ciscosparkapiException, SparkApiError
-from restsession import RestSession
-from api.accesstokens import AccessToken, AccessTokensAPI
-from api.people import Person, PeopleAPI
-from api.rooms import Room, RoomsAPI
-from api.memberships import Membership, MembershipsAPI
-from api.messages import Message, MessagesAPI
-from api.teams import Team, TeamsAPI
-from api.teammemberships import TeamMembership, TeamMembershipsAPI
-from api.webhooks import Webhook, WebhooksAPI
-
-
 DEFAULT_BASE_URL = 'https://api.ciscospark.com/v1/'
 
 
@@ -46,10 +51,10 @@ def __init__(self, access_token=None, base_url=DEFAULT_BASE_URL,
         via one of these two methods.
 
         Args:
-            access_token(unicode, str): The access token to be used for API
+            access_token(string_types): The access token to be used for API
                 calls to the Cisco Spark service.  Defaults to checking for a
                 SPARK_ACCESS_TOKEN environment variable.
-            base_url(unicode, str): The base URL to be prefixed to the
+            base_url(string_types): The base URL to be prefixed to the
                 individual API endpoint suffixes.
                 Defaults to ciscosparkapi.DEFAULT_BASE_URL.
             timeout(int): Timeout (in seconds) for RESTful HTTP requests.
@@ -61,21 +66,21 @@ def __init__(self, access_token=None, base_url=DEFAULT_BASE_URL,
         Raises:
             AssertionError: If the parameter types are incorrect.
             ciscosparkapiException: If an access token is not provided via the
-                access_token argument or SPARK_ACCESS_TOKEN environement
+                access_token argument or SPARK_ACCESS_TOKEN environment
                 variable.
 
         """
         # Process args
-        assert access_token is None or isinstance(access_token, basestring)
-        assert isinstance(base_url, basestring)
+        assert access_token is None or isinstance(access_token, string_types)
+        assert isinstance(base_url, string_types)
         assert isinstance(timeout, int)
         spark_access_token = os.environ.get('SPARK_ACCESS_TOKEN', None)
         access_token = access_token if access_token else spark_access_token
         if not access_token:
             error_message = "You must provide an access token to interact " \
                             "with the Cisco Spark APIs, either via the " \
                             "access_token argument or via a " \
-                            "SPARK_ACCESS_TOKEN environement variable.  " \
+                            "SPARK_ACCESS_TOKEN environment variable.  " \
                             "None provided."
             raise ciscosparkapiException(error_message)
         session_args = {u'timeout': timeout}

ciscosparkapi/_version.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 
 # This file helps to compute a version number in source trees obtained from
 # git-archive tarball (such as those provided by githubs download-from-tag
@@ -9,6 +10,9 @@
 # versioneer-0.16 (https://github.com/warner/python-versioneer)
 
 """Git implementation of _version.py."""
+from __future__ import print_function
+from builtins import str
+from builtins import object
 
 import errno
 import os
@@ -29,7 +33,7 @@ def get_keywords():
     return keywords
 
 
-class VersioneerConfig:
+class VersioneerConfig(object):
     """Container for Versioneer configuration parameters."""
 
 

ciscosparkapi/api/accesstokens.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """Cisco Spark Access-Tokens-API wrapper classes.
 
 Classes:
@@ -9,16 +10,21 @@
 """
 
 
-import urlparse
+from future import standard_library
+standard_library.install_aliases()
+from builtins import object
+from six import string_types
+
+import urllib.parse
 
 import requests
 
-from ciscosparkapi.helper import utf8, ERC, validate_base_url, \
+from ciscosparkapi.helper import ERC, validate_base_url, \
     check_response_code, extract_and_parse_json
 from ciscosparkapi.sparkdata import SparkData
 
 
-API_ENDPOINT = u"access_token"
+API_ENDPOINT = "access_token"
 
 
 class AccessToken(SparkData):
@@ -28,7 +34,7 @@ def __init__(self, json):
         """Init a new AccessToken data object from a JSON dictionary or string.
 
         Args:
-            json(dict, unicode, str): Input JSON object.
+            json(dict, string_types): Input JSON object.
 
         Raises:
             TypeError: If the input object is not a dictionary or string.
@@ -39,22 +45,22 @@ def __init__(self, json):
     @property
     def access_token(self):
         """Cisco Spark access_token."""
-        return self._json.get(u'access_token')
+        return self._json.get('access_token')
 
     @property
     def expires_in(self):
         """Access token expires_in number of seconds."""
-        return self._json.get(u'expires_in')
+        return self._json.get('expires_in')
 
     @property
     def refresh_token(self):
         """refresh_token used to request a new/refreshed access_token."""
-        return self._json.get(u'refresh_token')
+        return self._json.get('refresh_token')
 
     @property
     def refresh_token_expires_in(self):
         """refresh_token_expires_in number of seconds."""
-        return self._json.get(u'refresh_token_expires_in')
+        return self._json.get('refresh_token_expires_in')
 
 
 class AccessTokensAPI(object):
@@ -69,21 +75,21 @@ def __init__(self, base_url, timeout=None):
         """Init a new AccessTokensAPI object with the provided RestSession.
 
         Args:
-            base_url(unicode, str): The base URL the API endpoints.
+            base_url(string_types): The base URL the API endpoints.
             timeout(int): Timeout in seconds for the API requests.
 
         Raises:
             AssertionError: If the parameter types are incorrect.
 
         """
-        assert isinstance(base_url, basestring)
+        assert isinstance(base_url, string_types)
         assert timeout is None or isinstance(timeout, int)
         super(AccessTokensAPI, self).__init__()
-        self._base_url = validate_base_url(base_url)
+        self._base_url = str(validate_base_url(base_url))
         self._timeout = timeout
-        self._endpoint_url = urlparse.urljoin(self.base_url, API_ENDPOINT)
+        self._endpoint_url = urllib.parse.urljoin(self.base_url, API_ENDPOINT)
         self._request_kwargs = {}
-        self._request_kwargs[u"timeout"] = timeout
+        self._request_kwargs["timeout"] = timeout
 
     @property
     def base_url(self):
@@ -100,13 +106,13 @@ def get(self, client_id, client_secret, code, redirect_uri):
         invoke the APIs.
 
         Args:
-            client_id(unicode, str): Provided when you created your
+            client_id(string_types): Provided when you created your
                 integration.
-            client_secret(unicode, str): Provided when you created your
+            client_secret(string_types): Provided when you created your
                 integration.
-            code(unicode, str): The Authorization Code provided by the user
+            code(string_types): The Authorization Code provided by the user
                 OAuth process.
-            redirect_uri(unicode, str): The redirect URI used in the user OAuth
+            redirect_uri(string_types): The redirect URI used in the user OAuth
                 process.
 
         Returns:
@@ -119,17 +125,17 @@ def get(self, client_id, client_secret, code, redirect_uri):
 
         """
         # Process args
-        assert isinstance(client_id, basestring)
-        assert isinstance(client_secret, basestring)
-        assert isinstance(code, basestring)
-        assert isinstance(redirect_uri, basestring)
+        assert isinstance(client_id, string_types)
+        assert isinstance(client_secret, string_types)
+        assert isinstance(code, string_types)
+        assert isinstance(redirect_uri, string_types)
         # Build request parameters
         data = {}
-        data[u"grant_type"] = u"authorization_code"
-        data[u"client_id"] = utf8(client_id)
-        data[u"client_secret"] = utf8(client_secret)
-        data[u"code"] = utf8(code)
-        data[u"redirect_uri"] = utf8(redirect_uri)
+        data["grant_type"] = "authorization_code"
+        data["client_id"] = client_id
+        data["client_secret"] = client_secret
+        data["code"] = code
+        data["redirect_uri"] = redirect_uri
         # API request
         response = requests.post(self._endpoint_url, data=data,
                                  **self._request_kwargs)
@@ -142,11 +148,11 @@ def refresh(self, client_id, client_secret, refresh_token):
         """Return a refreshed Access Token via the provided refresh_token.
 
         Args:
-            client_id(unicode, str): Provided when you created your
+            client_id(string_types): Provided when you created your
                 integration.
-            client_secret(unicode, str): Provided when you created your
+            client_secret(string_types): Provided when you created your
                 integration.
-            refresh_token(unicode, str): Provided when you requested the Access
+            refresh_token(string_types): Provided when you requested the Access
                 Token.
 
         Returns:
@@ -159,15 +165,15 @@ def refresh(self, client_id, client_secret, refresh_token):
 
         """
         # Process args
-        assert isinstance(client_id, basestring)
-        assert isinstance(client_secret, basestring)
-        assert isinstance(refresh_token, basestring)
+        assert isinstance(client_id, string_types)
+        assert isinstance(client_secret, string_types)
+        assert isinstance(refresh_token, string_types)
         # Build request parameters
         data = {}
-        data[u"grant_type"] = u"refresh_token"
-        data[u"client_id"] = utf8(client_id)
-        data[u"client_secret"] = utf8(client_secret)
-        data[u"refresh_token"] = utf8(refresh_token)
+        data["grant_type"] = "refresh_token"
+        data["client_id"] = client_id
+        data["client_secret"] = client_secret
+        data["refresh_token"] = refresh_token
         # API request
         response = requests.post(self._endpoint_url, data=data,
                                  **self._request_kwargs)