Merge branch 'master' into packaging-and-distribution

Author: cmlccie

README.md

@@ -2,48 +2,72 @@
 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.
 
- * Leverages generator containers and RFC5988 web linking to provide simple and efficient 'paging' of Cisco Spark data objects returned by the Cisco Spark clout.
+ * 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 cloud.
 
  * 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
 from ciscosparkapi import CiscoSparkAPI
 
-access_token = "abcdefg..."
-api = CiscoSparkAPI(access_token)
+
+# 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
 for room in rooms:          # Efficiently iterates through returned objects
     print room.title        # JSON objects are represented as native Python 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,36 +1,91 @@
+# -*- 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
 
-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
 DEFAULT_BASE_URL = 'https://api.ciscospark.com/v1/'
 
 
 class CiscoSparkAPI(object):
     """Cisco Spark API wrapper class."""
 
-    def __init__(self, access_token, base_url=DEFAULT_BASE_URL, timeout=None):
+    def __init__(self, access_token=None, base_url=DEFAULT_BASE_URL,
+                 timeout=60):
+        """Init a new CiscoSparkAPI object.
+
+        An access token must be used when interacting with the Cisco Spark API.
+        This package supports two methods for you to provide that access token:
+
+          1. You may manually specify the access token via the access_token
+             argument, when creating a new CiscoSparkAPI object.
+
+          2. If an access_token argument is not supplied, the package checks
+             for a SPARK_ACCESS_TOKEN environment variable, and if available,
+             it uses the value of this environment variable as the access_token
+             when new CiscoSparkAPI objects are created.
+
+        A ciscosparkapiException is raised if an access token is not provided
+        via one of these two methods.
+
+        Args:
+            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(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.
+                Defaults to 60 seconds.
+
+        Returns:
+            CiscoSparkAPI: A new CiscoSparkAPI connection object.
+
+        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 environment
+                variable.
+
+        """
         # Process args
-        assert isinstance(access_token, basestring)
-        # Process kwargs
-        session_args = {}
-        if timeout:
-            session_args['timeout'] = timeout
+        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 environment variable.  " \
+                            "None provided."
+            raise ciscosparkapiException(error_message)
+        session_args = {u'timeout': timeout}
 
-        # Create API session
+        # Create the API session
         # All of the API calls associated with a CiscoSparkAPI object will
         # leverage a single RESTful 'session' connecting to the Cisco Spark
         # cloud.

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."""