Update package structure to clarify package API

Issue #25 - Refactor module and class names to clearly communicate the intended user interfaces

Update the `ciscosparkapi.__init__.py` API to clarify what classes and data are being exposed to the user.

Update the package docstrings and documentation accordingly.

Author: cmlccie

ciscosparkapi/__init__.py

@@ -15,32 +15,53 @@
 import logging
 import os
 
-from ciscosparkapi.exceptions import ciscosparkapiException, SparkApiError
-from ciscosparkapi.restsession import (
+from .api.people import Person
+from .api.rooms import Room
+from .api.memberships import Membership
+from .api.messages import Message
+from .api.teams import Team
+from .api.team_memberships import TeamMembership
+from .api.webhooks import Webhook, WebhookEvent
+from .api.organizations import Organization
+from .api.licenses import License
+from .api.roles import Role
+from .api.access_tokens import AccessToken
+
+from .api.people import PeopleAPI as _PeopleAPI
+from .api.rooms import RoomsAPI as _RoomsAPI
+from .api.memberships import MembershipsAPI as _MembershipsAPI
+from .api.messages import MessagesAPI as _MessagesAPI
+from .api.teams import TeamsAPI as _TeamsAPI
+from .api.team_memberships import TeamMembershipsAPI as _TeamMembershipsAPI
+from .api.webhooks import WebhooksAPI as _WebhooksAPI
+from .api.organizations import OrganizationsAPI as _OrganizationsAPI
+from .api.licenses import LicensesAPI as _LicensesAPI
+from .api.roles import RolesAPI as _RolesAPI
+from .api.access_tokens import AccessTokensAPI as _AccessTokensAPI
+
+from .exceptions import (
+    ciscosparkapiException,
+    SparkApiError,
+    SparkRateLimitError,
+)
+
+from .restsession import (
     DEFAULT_SINGLE_REQUEST_TIMEOUT,
     DEFAULT_WAIT_ON_RATE_LIMIT,
-    RestSession,
-)
-from ciscosparkapi.api.people import Person, PeopleAPI
-from ciscosparkapi.api.rooms import Room, RoomsAPI
-from ciscosparkapi.api.memberships import Membership, MembershipsAPI
-from ciscosparkapi.api.messages import Message, MessagesAPI
-from ciscosparkapi.api.teams import Team, TeamsAPI
-from ciscosparkapi.api.teammemberships import (
-    TeamMembership,
-    TeamMembershipsAPI
+    RestSession as _RestSession,
 )
-from ciscosparkapi.api.webhooks import Webhook, WebhookEvent, WebhooksAPI
-from ciscosparkapi.api.organizations import Organization, OrganizationsAPI
-from ciscosparkapi.api.licenses import License, LicensesAPI
-from ciscosparkapi.api.roles import Role, RolesAPI
-from ciscosparkapi.api.accesstokens import AccessToken, AccessTokensAPI
 
 
 __author__ = "Chris Lunsford"
 __author_email__ = "chrlunsf@cisco.com"
 __copyright__ = "Copyright (c) 2016 Cisco Systems, Inc."
 __license__ = "MIT"
+__all__ = [
+    "CiscoSparkAPI", "ciscosparkapiException", "SparkApiError",
+    "SparkRateLimitError", "Person", "Room", "Membership", "Message", "Team",
+    "TeamMembership", "Webhook", "WebhookEvent", "Organization", "License",
+    "Role", "AccessToken"
+]
 
 
 # Versioneer version control
@@ -151,7 +172,7 @@ def __init__(self, access_token=None, base_url=DEFAULT_BASE_URL,
         # 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(
+        self._session = _RestSession(
             access_token,
             base_url,
             timeout=timeout,
@@ -160,34 +181,39 @@ def __init__(self, access_token=None, base_url=DEFAULT_BASE_URL,
         )
 
         # 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.organizations = OrganizationsAPI(self._session)
-        self.licenses = LicensesAPI(self._session)
-        self.roles = RolesAPI(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)
+        self.organizations = _OrganizationsAPI(self._session)
+        self.licenses = _LicensesAPI(self._session)
+        self.roles = _RolesAPI(self._session)
+        self.access_tokens = _AccessTokensAPI(self.base_url, timeout=timeout)
 
     @property
     def access_token(self):
+        """The access token used for API calls to the Cisco Spark service."""
         return self._session.access_token
 
     @property
     def base_url(self):
+        """The base URL prefixed to the individual API endpoint suffixes."""
         return self._session.base_url
 
     @property
     def timeout(self):
+        """[deprecated] Timeout (in seconds) for RESTful HTTP requests."""
         return self._session.timeout
 
     @property
     def single_request_timeout(self):
+        """Timeout (in seconds) for an single HTTP request."""
         return self._session.single_request_timeout
 
     @property
     def wait_on_rate_limit(self):
+        """Automatic rate-limit handling enabled / disabled."""
         return self._session.wait_on_rate_limit

ciscosparkapi/api/accesstokens.py renamed to ciscosparkapi/api/access_tokens.py

@@ -1,11 +1,11 @@
 # -*- coding: utf-8 -*-
-"""Cisco Spark Access-Tokens-API wrapper classes.
+"""Cisco Spark Access-Tokens API wrapper.
 
 Classes:
     AccessToken: Models a Spark 'access token' JSON object as a native Python
         object.
-    AccessTokensAPI: Wraps the Cisco Spark Access-Tokens-API and exposes the
-        APIs as native Python methods that return native Python objects.
+    AccessTokensAPI: Wraps the Cisco Spark Access-Tokens API and exposes the
+        API as native Python methods that return native Python objects.
 
 """
 
@@ -26,9 +26,9 @@
 
 import requests
 
-from ciscosparkapi.responsecodes import EXPECTED_RESPONSE_CODE
-from ciscosparkapi.sparkdata import SparkData
-from ciscosparkapi.utils import (
+from ..response_codes import EXPECTED_RESPONSE_CODE
+from ..sparkdata import SparkData
+from ..utils import (
     check_response_code,
     check_type,
     dict_from_items_with_values,
@@ -83,9 +83,9 @@ def refresh_token_expires_in(self):
 
 
 class AccessTokensAPI(object):
-    """Cisco Spark Access-Tokens-API wrapper class.
+    """Cisco Spark Access-Tokens API wrapper.
 
-    Wraps the Cisco Spark Access-Tokens-API and exposes the APIs as native
+    Wraps the Cisco Spark Access-Tokens API and exposes the API as native
     Python methods that return native Python objects.
 
     """

ciscosparkapi/api/licenses.py

@@ -1,9 +1,9 @@
 # -*- coding: utf-8 -*-
-"""Cisco Spark Licenses-API wrapper.
+"""Cisco Spark Licenses API wrapper.
 
 Classes:
     License: Models a Spark License JSON object as a native Python object.
-    LicensesAPI: Wraps the Cisco Spark Licenses-API and exposes the APIs as
+    LicensesAPI: Wraps the Cisco Spark Licenses API and exposes the API as
         native Python methods that return native Python objects.
 
 """
@@ -19,9 +19,9 @@
 from builtins import *
 from past.builtins import basestring
 
-from ciscosparkapi.restsession import RestSession
-from ciscosparkapi.sparkdata import SparkData
-from ciscosparkapi.utils import (
+from ..restsession import RestSession
+from ..sparkdata import SparkData
+from ..utils import (
     check_type,
     dict_from_items_with_values,
     generator_container,
@@ -71,9 +71,9 @@ def consumedUnits(self):
 
 
 class LicensesAPI(object):
-    """Cisco Spark Licenses-API wrapper.
+    """Cisco Spark Licenses API wrapper.
 
-    Wraps the Cisco Spark Licenses-API and exposes the APIs as native Python
+    Wraps the Cisco Spark Licenses API and exposes the API as native Python
     methods that return native Python objects.
 
     """

ciscosparkapi/api/memberships.py

@@ -1,10 +1,10 @@
 # -*- coding: utf-8 -*-
-"""Cisco Spark Memberships-API wrapper classes.
+"""Cisco Spark Memberships API wrapper.
 
 Classes:
     Membership: Models a Spark 'membership' JSON object as a native Python
         object.
-    MembershipsAPI: Wraps the Cisco Spark Memberships-API and exposes the
+    MembershipsAPI: Wraps the Cisco Spark Memberships API and exposes the
         APIs as native Python methods that return native Python objects.
 
 """
@@ -20,9 +20,9 @@
 from builtins import *
 from past.builtins import basestring
 
-from ciscosparkapi.restsession import RestSession
-from ciscosparkapi.sparkdata import SparkData
-from ciscosparkapi.utils import (
+from ..restsession import RestSession
+from ..sparkdata import SparkData
+from ..utils import (
     check_type,
     dict_from_items_with_values,
     generator_container,
@@ -97,9 +97,9 @@ def created(self):
 
 
 class MembershipsAPI(object):
-    """Cisco Spark Memberships-API wrapper class.
+    """Cisco Spark Memberships API wrapper.
 
-    Wraps the Cisco Spark Memberships-API and exposes the APIs as native Python
+    Wraps the Cisco Spark Memberships API and exposes the API as native Python
     methods that return native Python objects.
 
     """

ciscosparkapi/api/messages.py

@@ -1,9 +1,9 @@
 # -*- coding: utf-8 -*-
-"""Cisco Spark Messages-API wrapper classes.
+"""Cisco Spark Messages API wrapper.
 
 Classes:
     Message: Models a Spark 'message' JSON object as a native Python object.
-    MessagesAPI: Wraps the Cisco Spark Messages-API and exposes the APIs as
+    MessagesAPI: Wraps the Cisco Spark Messages API and exposes the API as
         native Python methods that return native Python objects.
 
 """
@@ -21,9 +21,9 @@
 
 from requests_toolbelt import MultipartEncoder
 
-from ciscosparkapi.restsession import RestSession
-from ciscosparkapi.sparkdata import SparkData
-from ciscosparkapi.utils import (
+from ..restsession import RestSession
+from ..sparkdata import SparkData
+from ..utils import (
     check_type,
     dict_from_items_with_values,
     generator_container,
@@ -111,9 +111,9 @@ def created(self):
 
 
 class MessagesAPI(object):
-    """Cisco Spark Messages-API wrapper class.
+    """Cisco Spark Messages API wrapper.
 
-    Wraps the Cisco Spark Messages-API and exposes the APIs as native Python
+    Wraps the Cisco Spark Messages API and exposes the API as native Python
     methods that return native Python objects.
 
     """

ciscosparkapi/api/organizations.py

@@ -1,10 +1,10 @@
 # -*- coding: utf-8 -*-
-"""Cisco Spark Organizations-API wrapper.
+"""Cisco Spark Organizations API wrapper.
 
 Classes:
     Organization: Models a Spark Organization JSON object as a native Python
         object.
-    OrganizationsAPI: Wraps the Cisco Spark Organizations-API and exposes the
+    OrganizationsAPI: Wraps the Cisco Spark Organizations API and exposes the
         APIs as native Python methods that return native Python objects.
 
 """
@@ -20,9 +20,9 @@
 from builtins import *
 from past.builtins import basestring
 
-from ciscosparkapi.restsession import RestSession
-from ciscosparkapi.sparkdata import SparkData
-from ciscosparkapi.utils import (
+from ..restsession import RestSession
+from ..sparkdata import SparkData
+from ..utils import (
     check_type,
     dict_from_items_with_values,
     generator_container,
@@ -67,9 +67,9 @@ def created(self):
 
 
 class OrganizationsAPI(object):
-    """Cisco Spark Organizations-API wrapper.
+    """Cisco Spark Organizations API wrapper.
 
-    Wraps the Cisco Spark Organizations-API and exposes the APIs as native
+    Wraps the Cisco Spark Organizations API and exposes the API as native
     Python methods that return native Python objects.
 
     """

ciscosparkapi/api/people.py

@@ -1,9 +1,9 @@
 # -*- coding: utf-8 -*-
-"""Cisco Spark People-API wrapper classes.
+"""Cisco Spark People API wrapper classes.
 
 Classes:
     Person: Models a Spark 'person' JSON object as a native Python object.
-    PeopleAPI: Wraps the Cisco Spark People-API and exposes the APIs as native
+    PeopleAPI: Wraps the Cisco Spark People API and exposes the API as native
         Python methods that return native Python objects.
 
 """
@@ -19,9 +19,9 @@
 from builtins import *
 from past.builtins import basestring
 
-from ciscosparkapi.restsession import RestSession
-from ciscosparkapi.sparkdata import SparkData
-from ciscosparkapi.utils import (
+from ..restsession import RestSession
+from ..sparkdata import SparkData
+from ..utils import (
     check_type,
     dict_from_items_with_values,
     generator_container,
@@ -131,9 +131,9 @@ def loginEnabled(self):
 
 
 class PeopleAPI(object):
-    """Cisco Spark People-API wrapper class.
+    """Cisco Spark People API wrapper.
 
-    Wraps the Cisco Spark People-API and exposes the APIs as native Python
+    Wraps the Cisco Spark People API and exposes the API as native Python
     methods that return native Python objects.
 
     """

ciscosparkapi/api/roles.py

@@ -1,9 +1,9 @@
 # -*- coding: utf-8 -*-
-"""Cisco Spark Roles-API wrapper.
+"""Cisco Spark Roles API wrapper.
 
 Classes:
     Role: Models a Spark Role JSON object as a native Python object.
-    RolesAPI: Wraps the Cisco Spark Roles-API and exposes the APIs as native
+    RolesAPI: Wraps the Cisco Spark Roles API and exposes the API as native
         Python methods that return native Python objects.
 
 """
@@ -19,9 +19,9 @@
 from builtins import *
 from past.builtins import basestring
 
-from ciscosparkapi.restsession import RestSession
-from ciscosparkapi.sparkdata import SparkData
-from ciscosparkapi.utils import (
+from ..restsession import RestSession
+from ..sparkdata import SparkData
+from ..utils import (
     check_type,
     dict_from_items_with_values,
     generator_container,
@@ -61,9 +61,9 @@ def name(self):
 
 
 class RolesAPI(object):
-    """Cisco Spark Roles-API wrapper.
+    """Cisco Spark Roles API wrapper.
 
-    Wraps the Cisco Spark Roles-API and exposes the APIs as native Python
+    Wraps the Cisco Spark Roles API and exposes the API as native Python
     methods that return native Python objects.
 
     """