Merge lp:~elachuni/piston-mini-client/dual-scheme-support into lp:piston-mini-client

[Anthony Lenton]

Overview
========
Provide support for talking to dual http/https apis.

Details
=======
Base work needed to allow certain methods in our api to use http requests, while others need to use https. Detailed docs in the diff itself, and in the related bugs.

[Danny Tamez (zematynnad)]

Approved. Nice docs!

review: Approve

=== modified file 'doc/conf.py'
--- doc/conf.py	2011-01-12 17:21:36 +0000
+++ doc/conf.py	2011-01-20 14:24:08 +0000
@@ -18,6 +18,8 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0, os.path.abspath('.'))
 
+sys.path.insert(0, os.path.abspath('..'))
+
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 
=== modified file 'doc/index.rst'
--- doc/index.rst	2010-12-09 21:02:11 +0000
+++ doc/index.rst	2011-01-20 14:24:08 +0000
@@ -12,6 +12,7 @@
    :maxdepth: 2
 
    quickstart
+   reference
 
 Overview
 ========
 
=== modified file 'doc/quickstart.rst'
--- doc/quickstart.rst	2011-01-12 15:37:40 +0000
+++ doc/quickstart.rst	2011-01-20 14:24:08 +0000
@@ -186,3 +186,38 @@
  * ``MultiExceptionFailHandler``: Raises a different exception according to
    what went wrong.
 
+===============================
+Talking to dual http/https apis
+===============================
+
+Often your API provides a set of public calls, and some other calls that
+are authenticated.
+
+Public calls sometimes are heavily used, so we'd like to
+serve them over http.  They're public anyway.
+
+Authenticated calls involve some sensitive information passing with the user's
+credentials, so we like serving those over https.  
+
+Once you've got all this set up on the server, you can ask piston_mini_client
+to make each call using the appropriate scheme by using the ``scheme``
+optional argument when you call ``_get`` or ``_post``::
+
+    class DualAPI(PistonAPI):
+        default_service_root = 'http://myhostname.com/api/1.0'
+
+        def public_method(self):
+            return self._get('public_method/', scheme='http')
+
+        def private_method(self):
+            return self._post('private_method/', scheme='https')
+
+        def either(self):
+            return self._get('either/')
+
+In this case, no matter what scheme the service root uses, calls to
+``public_method()`` will result in
+an http request, and calls to ``private_method()``  will result in an https
+request.  Calls to ``either()`` will leave the scheme alone, so it will
+follow the scheme used to instantiate the api, or fall back to
+``default_service_root``'s scheme.
 \ No newline at end of file
 
=== added file 'doc/reference.rst'
--- doc/reference.rst	1970-01-01 00:00:00 +0000
+++ doc/reference.rst	2011-01-20 14:24:08 +0000
@@ -0,0 +1,33 @@
+Reference
+=========
+
+.. automodule:: piston_mini_client
+   :members:
+
+==========
+Validators
+==========
+
+.. automodule:: piston_mini_client.validators
+   :members:
+
+=============
+Fail handlers
+=============
+
+.. automodule:: piston_mini_client.failhandlers
+   :members:
+
+===========
+Serializers
+===========
+
+.. automodule:: piston_mini_client.serializers
+   :members:
+
+==============
+Authentication
+==============
+
+.. automodule:: piston_mini_client.auth
+   :members:
 
=== modified file 'piston_mini_client/__init__.py'
--- piston_mini_client/__init__.py	2011-01-12 17:21:36 +0000
+++ piston_mini_client/__init__.py	2011-01-20 14:24:08 +0000
@@ -6,6 +6,7 @@
 import simplejson
 import urllib
 from functools import wraps
+from urlparse import urlparse, urlunparse
 
 from failhandlers import ExceptionFailHandler, APIError
 
@@ -61,8 +62,7 @@
 
 
 class PistonResponseObject(object):
-    """Base class for objects that are returned from api calls.
-    """
+    """Base class for objects that are returned from api calls."""
     @classmethod
     def from_response(cls, body, none_allowed=False):
         data = simplejson.loads(body)
@@ -79,8 +79,7 @@
         return obj
 
 class PistonSerializable(object):
-    """Base class for objects that want to be used as api call arguments.
-    """
+    """Base class for objects that want to be used as api call arguments."""
     _atts = ()
 
     def __init__(self, **kwargs):
@@ -119,11 +118,17 @@
     def __init__(self, service_root=None, cachedir=None, auth=None):
         if service_root is None:
             service_root = self.default_service_root
+        if not service_root:
+            raise ValueError("No service_root provided, and no default found")
+        parsed_service_root = urlparse(service_root)
+        if parsed_service_root.scheme not in ['http', 'https']:
+            raise ValueError("service_root's scheme must be http or https")
         self._service_root = service_root
+        self._parsed_service_root = list(parsed_service_root)
         self._cachedir = cachedir
         self._auth = auth
 
-    def _get(self, path, args=None):
+    def _get(self, path, args=None, scheme=None):
         """Perform an HTTP GET request.
 
         The provided 'path' is appended to this resource's '_service_root'
@@ -131,6 +136,10 @@
 
         If provided, 'args' should be a dict specifying additional GET
         arguments that will be encoded on to the end of the url.
+
+        'scheme' must be one of 'http' or 'https', and will determine the
+        scheme used for this particular request.  If not provided the
+        service_root's scheme will be used.
         """
         if args is not None:
             if '?' in path:
@@ -138,9 +147,9 @@
             else:
                 path += '?'
             path += urllib.urlencode(args)
-        return self._request(path, method='GET')
+        return self._request(path, method='GET', scheme=scheme)
 
-    def _post(self, path, data=None, content_type=None):
+    def _post(self, path, data=None, content_type=None, scheme=None):
         """Perform an HTTP POST request.
 
         The provided path is appended to this api's '_service_root' attribute
@@ -153,6 +162,10 @@
            serializer from serializers.
 
         If content_type is None, self.default_content_type will be used.
+
+        'scheme' must be one of 'http' or 'https', and will determine the
+        scheme used for this particular request.  If not provided the
+        service_root's scheme will be used.
         """
         body = data
         if content_type is None:
@@ -163,9 +176,10 @@
             serializer = get_serializer(content_type)(data)
             body = serializer.serialize()
         headers = {'Content-type': content_type}
-        return self._request(path, method='POST', body=body, headers=headers)
+        return self._request(path, method='POST', body=body,
+            headers=headers, scheme=scheme)
 
-    def _request(self, path, method, body='', headers=None):
+    def _request(self, path, method, body='', headers=None, scheme=None):
         """Perform an HTTP request.
 
         You probably want to call one of the _get, _post methods instead.
@@ -173,7 +187,9 @@
         http = httplib2.Http(cache=self._cachedir)
         if headers is None:
             headers = {}
-        url = self._path2url(path)
+        if scheme not in [None, 'http', 'https']:
+            raise ValueError('Invalid scheme %s' % scheme)
+        url = self._path2url(path, scheme=scheme)
         if self._auth:
             self._auth.sign_request(url, method, body, headers)
         try:
@@ -189,6 +205,11 @@
         body = handler.handle(response, body)
         return body
 
-    def _path2url(self, path):
-        return self._service_root.rstrip('/') + '/' + path.lstrip('/')
+    def _path2url(self, path, scheme=None):
+        if scheme is None:
+            service_root = self._service_root
+        else:
+            parts = [scheme] + self._parsed_service_root[1:]
+            service_root = urlunparse(parts)
+        return service_root.strip('/') + '/' + path.lstrip('/')
 
 
=== modified file 'piston_mini_client/failhandlers.py'
--- piston_mini_client/failhandlers.py	2011-01-18 14:44:10 +0000
+++ piston_mini_client/failhandlers.py	2011-01-20 14:24:08 +0000
@@ -8,6 +8,15 @@
 possibly decorators) to know what to do with these returned objects.
 """
 
+__all__ = [
+    'APIError',
+    'BaseFailHandler',
+    'ExceptionFailHandler',
+    'DictFailHandler',
+    'NoneFailHandler',
+    'MultiExceptionFailHandler',
+]
+
 class APIError(Exception):
     def __init__(self, msg, body=None):
         self.msg = msg
@@ -53,7 +62,7 @@
     went wrong.
     """
     def handle(self, response, body):
-        """Raise APIError if a strange status code is found"""
+        """Return None if a strange status code is found"""
         if self.was_error(response):
             return None
         return body
@@ -63,6 +72,12 @@
     """A fail handler that returns error information in a dict"""
 
     def handle(self, response, body):
+        """Return a dict if a strange status code is found.
+
+        The returned dict will have two keys:
+         * 'response': the httplib2 response header dict
+         * 'body': the response body, as a string
+        """
         if self.was_error(response):
             return {'response': response, 'body': body}
         return body
@@ -94,6 +109,14 @@
     }
 
     def handle(self, response, body):
+        """Return an exception according to what went wrong.
+
+        Status codes currently returning their own exception class are:
+         * 400: BadRequestError,
+         * 401: UnauthorizedError,
+         * 404: NotFoundError, and
+         * 500: InternalServerErrorError
+        """
         if self.was_error(response):
             status = response.get('status')
             exception_class = self.exceptions.get(status, APIError)
 
=== modified file 'piston_mini_client/serializers.py'
--- piston_mini_client/serializers.py	2011-01-12 17:21:36 +0000
+++ piston_mini_client/serializers.py	2011-01-20 14:24:08 +0000
@@ -2,6 +2,12 @@
 # Copyright 2010-2011 Canonical Ltd.  This software is licensed under the
 # GNU Lesser General Public License version 3 (see the file LICENSE).
 
+__all__ = [
+    'BaseSerializer',
+    'JSONSerializer',
+    'FormSerializer',
+]
+
 import simplejson
 import urllib
 
 
=== modified file 'piston_mini_client/test/test_resource.py'
--- piston_mini_client/test/test_resource.py	2011-01-18 14:44:10 +0000
+++ piston_mini_client/test/test_resource.py	2011-01-20 14:24:08 +0000
@@ -13,7 +13,6 @@
 
 
 class PistonAPITestCase(TestCase):
-    # XXX achuni 2010-11-30: We need to test different return codes
     class CoffeeAPI(PistonAPI):
         default_service_root = 'http://localhost:12345'
         def brew(self):
@@ -26,6 +25,7 @@
             'auth': environ.get('HTTP_AUTHORIZATION'),
             'content_type': environ.get('CONTENT_TYPE'),
             'query': environ.get('QUERY_STRING'),
+            'scheme': environ.get('wsgi.url_scheme'),
         }
         return 'hello world'
 
@@ -97,17 +97,51 @@
         self.assertEqual('zot=ping&foo=bar', self.called['query'])
 
     def test_path2url_with_no_ending_slash(self):
-        resource = PistonAPI()
-        resource._service_root = 'http://example.com/api'
+        resource = PistonAPI('http://example.com/api')
         expected = 'http://example.com/api/frobble'
         self.assertEqual(expected, resource._path2url('frobble'))
 
     def test_path2url_with_ending_slash(self):
-        resource = PistonAPI()
-        resource._service_root = 'http://example.com/api/'
+        resource = PistonAPI('http://example.com/api/')
         expected = 'http://example.com/api/frobble'
         self.assertEqual(expected, resource._path2url('frobble'))
 
+    def test_instantiation_fails_with_no_service_root(self):
+        try:
+            self.CoffeeAPI.default_service_root = None
+            self.assertRaises(ValueError, self.CoffeeAPI)
+        finally:
+            self.CoffeeAPI.default_service_root = 'http://localhost:12345'
+
+
+    def test_instantiation_fails_with_invalid_scheme(self):
+        self.assertRaises(ValueError, self.CoffeeAPI, 'ftp://foobar.baz')
+
+    @patch('httplib2.Http.request')
+    def test_request_scheme_switch_to_https(self, mock_request):
+        mock_request.return_value = ({'status': '200'}, '""')
+        api = self.CoffeeAPI()
+        api._request('/foo', 'GET', scheme='https')
+        mock_request.assert_called_with('https://localhost:12345/foo',
+            body='', headers={}, method='GET')
+
+    @patch('httplib2.Http.request')
+    def test_get_scheme_switch_to_https(self, mock_request):
+        mock_request.return_value = ({'status': '200'}, '""')
+        api = self.CoffeeAPI()
+        api._get('/foo', scheme='https')
+        mock_request.assert_called_with('https://localhost:12345/foo',
+            body='', headers={}, method='GET')
+
+    @patch('httplib2.Http.request')
+    def test_post_scheme_switch_to_https(self, mock_request):
+        mock_request.return_value = ({'status': '200'}, '""')
+        api = self.CoffeeAPI()
+        api._post('/foo', scheme='https')
+        mock_request.assert_called_with('https://localhost:12345/foo',
+            body='null', headers={'Content-type': 'application/json'},
+            method='POST')
+
 
 class PistonResponseObjectTestCase(TestCase):
     def test_from_response(self):
@@ -122,7 +156,7 @@
 class ReturnsJSONTestCase(TestCase):
     def test_returns_json(self):
         class MyAPI(PistonAPI):
-            default_service_root = 'foo'
+            default_service_root = 'http://foo'
             @returns_json
             def func(self):
                 return '{"foo": "bar", "baz": 42}'
@@ -134,7 +168,7 @@
 class ReturnsTestCase(TestCase):
     def test_returns(self):
         class MyAPI(PistonAPI):
-            default_service_root = 'foo'
+            default_service_root = 'http://foo'
             @returns(PistonResponseObject)
             def func(self):
                 return '{"foo": "bar", "baz": 42}'
@@ -144,7 +178,7 @@
 
     def test_returns_none_allowed(self):
         class MyAPI(PistonAPI):
-            default_service_root = 'foo'
+            default_service_root = 'http://foo'
             @returns(PistonResponseObject, none_allowed=True)
             def func(self):
                 return 'null'
@@ -154,7 +188,7 @@
 
     def test_returns_none_allowed_normal_response(self):
         class MyAPI(PistonAPI):
-            default_service_root = 'foo'
+            default_service_root = 'http://foo'
             @returns(PistonResponseObject, none_allowed=True)
             def func(self):
                 return '{"foo": "bar", "baz": 42}'
@@ -166,7 +200,7 @@
 class ReturnsListOfTestCase(TestCase):
     def test_returns(self):
         class MyAPI(PistonAPI):
-            default_service_root = 'foo'
+            default_service_root = 'http://foo'
             @returns_list_of(PistonResponseObject)
             def func(self):
                 return '[{"foo": "bar"}, {"baz": 42}]'