Clean up RestSession methods add DEFAULT_API_URL

Break out some code and checks to helper functions and add comments to
improve readability.

Add a DEFAULT_API_URL module constant so that an API URL doesn’t have
to be specified for most use cases.

Author: cmlccie

ciscosparkapi/restsession.py

@@ -1,14 +1,19 @@
 """RestSession class for creating 'connections' to the Cisco Spark APIs."""
 
+
 import urlparse
 import requests
 import exception
 
 
-GET_EXPECTED_RESPONSE_CODE = 200
-POST_EXPECTED_RESPONSE_CODE = 200
-PUT_EXPECTED_RESPONSE_CODE = 200
-DELETE_EXPECTED_RESPONSE_CODE = 204
+# Default api.ciscospark.com base URL
+DEFAULT_API_URL = 'https://api.ciscospark.com/v1/'
+
+# Cisco Spark cloud Expected Response Codes (HTTP Response Codes)
+ERC = {'GET': 200,
+       'POST': 200,
+       'PUT': 200,
+       'DELETE': 204}
 
 
 def _validate_base_url(base_url):
@@ -21,8 +26,13 @@ def _validate_base_url(base_url):
         raise exception.CiscoSparkApiException(error_message)
 
 
-def _check_response(response, expected_response_code):
-    if response.status_code != expected_response_code:
+def _raise_if_extra_kwargs(kwargs):
+    if kwargs:
+        raise TypeError("Unexpected **kwargs: %r" % kwargs)
+
+
+def _check_response_code(response, erc):
+    if response.status_code != erc:
         raise exception.CiscoSparkApiError(response.status_code,
                                            request=response.request,
                                            response=response)
@@ -33,7 +43,7 @@ def _extract_and_parse_json(response):
 
 
 class RestSession(object):
-    def __init__(self, base_url, access_token, timeout=None):
+    def __init__(self, access_token, base_url=DEFAULT_API_URL, timeout=None):
         super(RestSession, self).__init__()
         self._base_url = _validate_base_url(base_url)
         self._access_token = access_token
@@ -70,86 +80,108 @@ def timeout(self, value):
     def urljoin(self, suffix_url):
         return urlparse.urljoin(self.base_url, suffix_url)
 
-    def get(self, url, **kwargs):
+    def get(self, url, params=None, **kwargs):
+        # Process args
+        assert isinstance(url, basestring)
+        assert params is None or isinstance(params, dict)
+        abs_url = self.urljoin(url)
+        # Process kwargs
         timeout = kwargs.pop('timeout', self.timeout)
-        expected_response_code = kwargs.pop('expected_response_code',
-                                            GET_EXPECTED_RESPONSE_CODE)
-        if kwargs:
-            raise TypeError(' Unexpected **kwargs: %r' % kwargs)
+        erc = kwargs.pop('erc', ERC['GET'])
+        _raise_if_extra_kwargs(kwargs)
         # API request
-        response = self._req_session.get(self.urljoin(url), timeout=timeout)
+        response = self._req_session.get(abs_url,
+                                         params=params,
+                                         timeout=timeout)
         # Process response
-        _check_response(response, expected_response_code)
+        _check_response_code(response, erc)
         return _extract_and_parse_json(response)
 
-    def get_pages(self, url, **kwargs):
+    def get_pages(self, url, params=None, **kwargs):
+        # Process args
+        assert isinstance(url, basestring)
+        assert params is None or isinstance(params, dict)
+        abs_url = self.urljoin(url)
+        # Process kwargs
         timeout = kwargs.pop('timeout', self.timeout)
-        expected_response_code = kwargs.pop('expected_response_code',
-                                            GET_EXPECTED_RESPONSE_CODE)
-        if kwargs:
-            raise TypeError(' Unexpected **kwargs: %r' % kwargs)
+        erc = kwargs.pop('erc', ERC['GET'])
+        _raise_if_extra_kwargs(kwargs)
         # API request - get first page
-        response = self._req_session.get(self.urljoin(url), timeout=timeout)
-        _check_response(response, expected_response_code)
-        json_dict = _extract_and_parse_json(response)
+        response = self._req_session.get(abs_url,
+                                         params=params,
+                                         timeout=timeout)
         while True:
-            # Yield response content
-            yield json_dict
+            # Process response - Yield page's JSON data
+            _check_response_code(response, erc)
+            yield _extract_and_parse_json(response)
             # Get next page
             if response.links.get('next'):
                 next_url = response.links.get('next').get('url')
                 # API request - get next page
                 response = self._req_session.get(next_url, timeout=timeout)
-                _check_response(response, expected_response_code)
-                json_dict = _extract_and_parse_json(response)
             else:
                 raise StopIteration
 
-    def get_items(self, url, **kwargs):
-        pages = self.get_pages(url, **kwargs)
-        for json_dict in pages:
-            assert isinstance(json_dict, dict)
-            items = json_dict.get(u'items')
+    def get_items(self, url, params=None, **kwargs):
+        # Get iterator for pages of JSON data
+        pages = self.get_pages(url, params=params, **kwargs)
+        # Process pages
+        for json_page in pages:
+            # Process each page of JSON data yielding the individual JSON
+            # objects contained within the top level 'items' array
+            assert isinstance(json_page, dict)
+            items = json_page.get(u'items')
             if items:
                 for item in items:
                     yield item
             else:
                 error_message = "'items' object not found in JSON data: %r" \
-                                % json_dict
+                                % json_page
                 raise exception.CiscoSparkApiException(error_message)
 
     def post(self, url, json_dict, **kwargs):
+        # Process args
+        assert isinstance(url, basestring)
+        assert isinstance(json_dict, dict)
+        abs_url = self.urljoin(url)
+        # Process kwargs
         timeout = kwargs.pop('timeout', self.timeout)
-        expected_response_code = kwargs.pop('expected_response_code',
-                                            POST_EXPECTED_RESPONSE_CODE)
-        if kwargs:
-            raise TypeError(' Unexpected **kwargs: %r' % kwargs)
+        erc = kwargs.pop('erc', ERC['POST'])
+        _raise_if_extra_kwargs(kwargs)
         # API request
-        response = self._req_session.post(self.urljoin(url),
+        response = self._req_session.post(abs_url,
                                           json=json_dict,
                                           timeout=timeout)
-        _check_response(response, expected_response_code)
+        # Process response
+        _check_response_code(response, erc)
         return _extract_and_parse_json(response)
 
     def put(self, url, json_dict, **kwargs):
+        # Process args
+        assert isinstance(url, basestring)
+        assert isinstance(json_dict, dict)
+        abs_url = self.urljoin(url)
+        # Process kwargs
         timeout = kwargs.pop('timeout', self.timeout)
-        expected_response_code = kwargs.pop('expected_response_code',
-                                            PUT_EXPECTED_RESPONSE_CODE)
-        if kwargs:
-            raise TypeError(' Unexpected **kwargs: %r' % kwargs)
+        erc = kwargs.pop('erc', ERC['PUT'])
+        _raise_if_extra_kwargs(kwargs)
         # API request
-        response = self._req_session.put(self.urljoin(url),
+        response = self._req_session.put(abs_url,
                                          json=json_dict,
                                          timeout=timeout)
-        _check_response(response, expected_response_code)
+        # Process response
+        _check_response_code(response, erc)
         return _extract_and_parse_json(response)
 
     def delete(self, url, **kwargs):
+        # Process args
+        assert isinstance(url, basestring)
+        abs_url = self.urljoin(url)
+        # Process kwargs
         timeout = kwargs.pop('timeout', self.timeout)
-        expected_response_code = kwargs.pop('expected_response_code',
-                                            DELETE_EXPECTED_RESPONSE_CODE)
-        if kwargs:
-            raise TypeError(' Unexpected **kwargs: %r' % kwargs)
+        erc = kwargs.pop('erc', ERC['DELETE'])
+        _raise_if_extra_kwargs(kwargs)
         # API request
-        response = self._req_session.delete(self.urljoin(url), timeout=timeout)
-        _check_response(response, expected_response_code)
+        response = self._req_session.delete(abs_url, timeout=timeout)
+        # Process response
+        _check_response_code(response, erc)