Support session objects.

This not only improves general performance by sharing socket connections
between HTTP calls, but also allows for caching with Requests-Cache.

README.md

@@ -1,2 +1,23 @@
 # Pillar Python REST SDK
 Integrate this module in your Python app to communicate with an Pillar server.
+
+
+## Caching
+
+[Requests-Cache](https://requests-cache.readthedocs.org/) can be used to
+cache HTTP requests. The Pillar Python REST SDK does not support it
+directly, but provides the means to plug in different session objects:
+
+    import requests_cache
+    import pillarsdk
+
+    req_sess = requests_cache.CachedSession(backend='sqlite',
+                                            cache_name='blender_cloud')
+    pillarsdk.Api.requests_session = req_sess
+
+Any `pillarsdk.Api` instance will now use the cached session. To
+temporary disable it, use:
+
+    api = pillarsdk.Api.Default(endpoint="https://your.endpoint")
+    with api.requests_session.cache_disabled():
+        node = pillarsdk.Node.find('1234')

pillarsdk/api.py

@@ -18,6 +18,9 @@ class Api(object):
         __version__, library_details)
     _api_singleton = None
 
+    # Global session object to do HTTP requests.
+    requests_session = requests.session()
+
     def __init__(self, options=None, **kwargs):
         """Create API object
 
@@ -119,7 +122,12 @@ class Api(object):
     def http_call(self, url, method, **kwargs):
         """Makes a http call. Logs response information.
         """
-        response = requests.request(method, url, **kwargs)
+
+        try:
+            response = self.requests_session.request(method, url, **kwargs)
+        except Exception as ex:
+            logging.warning('Error performing HTTP %s request to %s: %s', method, url, str(ex))
+            raise
 
         try:
             error = self.handle_response(response,