Initial Project Documentation (#27)

* Convert README to reStructuredText and Revise #15

Initial README.rst

* Update README.rst #15

Correct formatting issues and simplify text.

* Update README.rst #15

Add examples and documentation sections and misc edits.

* Switch package to use new README.rst #15

Delete old README.md and point setup.py to new README.rst

* README.rst Update Sub-Title

* Update README.rst

* Update README.rst

* Update README

* Initial Sphinx setup

Create new ‘docs’ directory.  Run sphinx-quickstart in ‘docs’

* Update .gitignore

Begin organizing .gitignore to identify used and unused entries.

* Add README.rst to MANIFEST.in

* Initial User-API documentation

Create initial index.rst and the the User-API documentation.

* Add copyright references to docs

* Rename helper.py to utils.py

Rename and refactor helper.py to utils.py to make naming more
consistent with established practices.

* Make xxxAPI.session private; Update docstrings for auto-documentation

The session attribute in an API object should not be ‘public’, and
therefore should be prefixed by an ‘_’.

Update API classes’ method docstrings to eliminate warnings and enable
proper auto-documentation by Sphinx autodoc extension.

* Change Versioneer version numbering style

The ‘pep440-post’ style better reflects post-release commits, and
enables building of installable dev-builds with sortable version
numbers.

Additionally, going forward, the package release tags will incorporate
a release status flag (a - alpha, b - beta, rc - release candidate) in
the format:  major.minor[flag]micro

* Document __init__.py

Update docstrings and User API Doc for the main package __init__.py
module.

* Update copyright in docs/conf.py

This copyright reference shows up in the footers of the HTML docs
generated by Sphinx.

* Docs - Update index.rst

* Initial Quickstart

The Quickstart guide / tutorial is now finished!!!

* Fix Documentation Bug #22

Report and needed corrections provided by @DJF3

-Thank you!

* Finalize the Docs for Initial Release

Author: cmlccie

.gitignore

@@ -1,6 +1,15 @@
+# TODO:  Remove all unused entries
+
+# ciscosparkapi Project
+dist/
+docs/_build/
+*.egg-info/
+
+
 # Unversioned files
 basic-tests.py
 
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -14,7 +23,6 @@ __pycache__/
 env/
 build/
 develop-eggs/
-dist/
 downloads/
 eggs/
 .eggs/
@@ -23,7 +31,6 @@ lib64/
 parts/
 sdist/
 var/
-*.egg-info/
 .installed.cfg
 *.egg
 
@@ -63,9 +70,6 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/_build/
-
 # PyBuilder
 target/
 

MANIFEST.in

@@ -1,4 +1,4 @@
 include LICENSE.txt
-include README.md
+include README.rst
 include versioneer.py
 include ciscosparkapi/_version.py

README.rst

@@ -8,8 +8,21 @@ Simple, lightweight, scalable Python API wrapper for the Cisco Spark APIs
 
 .. image:: https://img.shields.io/pypi/v/ciscosparkapi.svg
     :target: https://pypi.python.org/pypi/ciscosparkapi
+.. image:: https://readthedocs.org/projects/ciscosparkapi/badge/?version=latest
+    :target: http://ciscosparkapi.readthedocs.io/en/latest/?badge=latest
 
-Sure, working with the Cisco Spark APIs is easy (see `developer.ciscospark.com`_).  They are *RESTful*,  *naturally structured*, require only a *simple Access Token for authentication*, and *the data is elegantly represented in intuitive JSON*.  What could be easier?
+**Important update!**
+Complete user documentation is now available on
+`ciscosparkapi.readthedocs.io`_ !
+
+Please use the issues_ page to report any issues or feedback regarding the
+documentation.
+
+
+Introduction
+------------
+
+Sure, working with the Cisco Spark APIs is easy (see `developer.ciscospark.com`_).  They are RESTful,  naturally structured, require only a simple Access Token for authentication, and the data is elegantly represented in intuitive JSON.  What could be easier?
 
 .. code-block:: python
 
@@ -28,14 +41,14 @@ Sure, working with the Cisco Spark APIs is easy (see `developer.ciscospark.com`_
     if response.status_code == 200:
         # Great your message was posted!
         message_id = response.json['id']
-        message_text = response.json['id']
+        message_text = response.json['text']
         print("New message created, with ID:", message_id)
         print(message_text)
     else:
         # Oops something went wrong...  Better do something about it.
         print(response.status_code, response.text)
 
-Like I said, *EASY*.  However, in use, the code can be rather repetitive...
+Like I said, EASY.  However, in use, the code can become rather repetitive...
 
 - You have to setup the environment every time
 - You have to remember URLs and request arguments (or reference the docs)
@@ -93,7 +106,8 @@ All of this, combined, lets you do powerful things simply:
         api.memberships.create(demo_room.id, personEmail=email)
 
     # Post a message to the new room, and upload a file
-    api.message.create(demo_room.id, text="Welcome to the room!", files=["welcome.jpg"])
+    api.messages.create(demo_room.id, text="Welcome to the room!",
+                        files=["https://developer.ciscospark.com/images/logo_spark_lg@256.png"])
 
 That's more than six Spark API calls in less than 23 lines of script code (with comments)!
 ...and likely more than that depending on how many rooms are returned by Spark (remember pagination is handled for you automatically)
@@ -138,6 +152,10 @@ Have a good example script you would like to share?  Please feel free to contrib
 Documentation
 -------------
 
+**Complete user documentation is now available!**
+
+Read the Docs at `ciscosparkapi.readthedocs.io`_ !!
+
 All of the user-facing methods have complete docstrings.  You can view the docstrings for any method either from the `source files`_, or by using the Python ``help()`` function.
 
 .. code-block:: python
@@ -160,8 +178,6 @@ All of the user-facing methods have complete docstrings.  You can view the docst
                 private 1:1 message.
      ...
 
-Full standalone online documentation is coming soon (it's on the backlog!).
-
 
 Contribution
 ------------
@@ -193,6 +209,7 @@ Interested in contributing code?
 .. _PyCharm: https://www.jetbrains.com/pycharm/
 .. _examples: https://github.com/CiscoDevNet/ciscosparkapi/tree/master/examples
 .. _source files: https://github.com/CiscoDevNet/ciscosparkapi/tree/master/ciscosparkapi
+.. _ciscosparkapi.readthedocs.io: https://ciscosparkapi.readthedocs.io
 .. _ciscosparkapi: https://github.com/CiscoDevNet/ciscosparkapi
 .. _ciscosparksdk: https://github.com/CiscoDevNet/ciscosparksdk
 .. _issues: https://github.com/CiscoDevNet/ciscosparkapi/issues

ciscosparkapi/__init__.py

@@ -33,14 +33,40 @@
 
 
 DEFAULT_BASE_URL = 'https://api.ciscospark.com/v1/'
+DEFAULT_TIMEOUT = 60
 
 
 class CiscoSparkAPI(object):
-    """Cisco Spark API wrapper class."""
+    """Cisco Spark API wrapper.
+
+    Creates a 'session' for all API calls through a created CiscoSparkAPI
+    object.  The 'session' handles authentication, provides the needed headers,
+    and checks all responses for error conditions.
+
+    CiscoSparkAPI wraps all of the individual Cisco Spark APIs and represents
+    them in a simple hierarchical structure.
+
+    :CiscoSparkAPI: :class:`people <PeopleAPI>`
+
+                    :class:`rooms <RoomsAPI>`
+
+                    :class:`memberships <MembershipsAPI>`
+
+                    :class:`messages <MessagesAPI>`
+
+                    :class:`teams <TeamsAPI>`
+
+                    :class:`team_memberships <TeamMembershipsAPI>`
+
+                    :class:`webhooks <WebhooksAPI>`
+
+                    :class:`access_tokens <AccessTokensAPI>`
+
+    """
 
     def __init__(self, access_token=None, base_url=DEFAULT_BASE_URL,
-                 timeout=60):
-        """Init a new CiscoSparkAPI object.
+                 timeout=DEFAULT_TIMEOUT):
+        """Create 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:
@@ -49,9 +75,7 @@ def __init__(self, access_token=None, base_url=DEFAULT_BASE_URL,
              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.
+             for a SPARK_ACCESS_TOKEN environment variable.
 
         A ciscosparkapiException is raised if an access token is not provided
         via one of these two methods.
@@ -64,10 +88,10 @@ def __init__(self, access_token=None, base_url=DEFAULT_BASE_URL,
                 individual API endpoint suffixes.
                 Defaults to ciscosparkapi.DEFAULT_BASE_URL.
             timeout(int): Timeout (in seconds) for RESTful HTTP requests.
-                Defaults to 60 seconds.
+                Defaults to ciscosparkapi.DEFAULT_TIMEOUT.
 
         Returns:
-            CiscoSparkAPI: A new CiscoSparkAPI connection object.
+            CiscoSparkAPI: A new CiscoSparkAPI object.
 
         Raises:
             AssertionError: If the parameter types are incorrect.
@@ -83,38 +107,37 @@ def __init__(self, access_token=None, base_url=DEFAULT_BASE_URL,
         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."
+            error_message = "You must provide an Spark access token to " \
+                            "interact with the Cisco Spark APIs, either via " \
+                            "a SPARK_ACCESS_TOKEN environment variable " \
+                            "or via the access_token argument."
             raise ciscosparkapiException(error_message)
         session_args = {u'timeout': timeout}
 
         # 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.
-        self.session = RestSession(access_token, base_url, **session_args)
+        self._session = RestSession(access_token, base_url, **session_args)
 
         # Spark API wrappers
+        self.people = PeopleAPI(self._session)
+        self.rooms = RoomsAPI(self._session)
+        self.memberships = MembershipsAPI(self._session)
+        self.messages = MessagesAPI(self._session)
+        self.teams = TeamsAPI(self._session)
+        self.team_memberships = TeamMembershipsAPI(self._session)
+        self.webhooks = WebhooksAPI(self._session)
         self.access_tokens = AccessTokensAPI(self.base_url, timeout=timeout)
-        self.people = PeopleAPI(self.session)
-        self.rooms = RoomsAPI(self.session)
-        self.memberships = MembershipsAPI(self.session)
-        self.messages = MessagesAPI(self.session)
-        self.teams = TeamsAPI(self.session)
-        self.team_memberships = TeamMembershipsAPI(self.session)
-        self.webhooks = WebhooksAPI(self.session)
 
     @property
     def access_token(self):
-        return self.session.access_token
+        return self._session.access_token
 
     @property
     def base_url(self):
-        return self.session.base_url
+        return self._session.base_url
 
     @property
     def timeout(self):
-        return self.session.timeout
+        return self._session.timeout

ciscosparkapi/api/accesstokens.py

@@ -19,7 +19,7 @@
 
 import requests
 
-from ciscosparkapi.helper import ERC, validate_base_url, \
+from ciscosparkapi.utils import ERC, validate_base_url, \
     check_response_code, extract_and_parse_json
 from ciscosparkapi.sparkdata import SparkData
 

ciscosparkapi/api/memberships.py

@@ -14,7 +14,7 @@
 from six import string_types
 
 from ciscosparkapi.exceptions import ciscosparkapiException
-from ciscosparkapi.helper import generator_container
+from ciscosparkapi.utils import generator_container
 from ciscosparkapi.restsession import RestSession
 from ciscosparkapi.sparkdata import SparkData
 
@@ -79,10 +79,6 @@ class MembershipsAPI(object):
     Wrappers the Cisco Spark Memberships-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):
@@ -98,7 +94,7 @@ def __init__(self, session):
         """
         assert isinstance(session, RestSession)
         super(MembershipsAPI, self).__init__()
-        self.session = session
+        self._session = session
 
     @generator_container
     def list(self, roomId=None, personId=None, personEmail=None, max=None):
@@ -133,8 +129,9 @@ def list(self, roomId=None, personId=None, personEmail=None, max=None):
                 the Spark service per request.
 
 
-        Yields:
-            Membership: The the next membership from the Cisco Spark query.
+        Returns:
+            GeneratorContainer: When iterated, the GeneratorContainer, yields
+                the memberships returned from the Cisco Spark query.
 
         Raises:
             AssertionError: If the parameter types are incorrect.
@@ -164,7 +161,7 @@ def list(self, roomId=None, personId=None, personEmail=None, max=None):
         if max:
             params['max'] = max
         # API request - get items
-        items = self.session.get_items('memberships', params=params)
+        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)
@@ -212,7 +209,7 @@ def create(self, roomId, personId=None, personEmail=None,
             raise ciscosparkapiException(error_message)
         post_data['isModerator'] = isModerator
         # API request
-        json_obj = self.session.post('memberships', json=post_data)
+        json_obj = self._session.post('memberships', json=post_data)
         # Return a Membership object created from the response JSON data
         return Membership(json_obj)
 
@@ -233,7 +230,7 @@ def get(self, membershipId):
         # Process args
         assert isinstance(membershipId, string_types)
         # API request
-        json_obj = self.session.get('memberships/'+membershipId)
+        json_obj = self._session.get('memberships/' + membershipId)
         # Return a Membership object created from the response JSON data
         return Membership(json_obj)
 
@@ -243,8 +240,6 @@ def update(self, membershipId, **update_attributes):
         Args:
             membershipId(string_types): The membershipId of the membership to
                 be updated.
-
-        **update_attributes:
             isModerator(bool): If True, sets the person as a moderator for the
                 room. If False, removes the person as a moderator for the room.
 
@@ -265,8 +260,8 @@ def update(self, membershipId, **update_attributes):
                             "argument must be specified."
             raise ciscosparkapiException(error_message)
         # API request
-        json_obj = self.session.post('memberships/'+membershipId,
-                                     json=update_attributes)
+        json_obj = self._session.post('memberships/' + membershipId,
+                                      json=update_attributes)
         # Return a Membership object created from the response JSON data
         return Membership(json_obj)
 
@@ -285,4 +280,4 @@ def delete(self, membershipId):
         # Process args
         assert isinstance(membershipId, string_types)
         # API request
-        self.session.delete('memberships/'+membershipId)
+        self._session.delete('memberships/' + membershipId)