Merge lp:~jml/piston-mini-client/split-request-1041825 into lp:piston-mini-client

[Jonathan Lange]

Unmerged revisions

60. By Jonathan Lange on 2012-08-26

RED: Roughly hew a PistonRequester out of PistonAPI

=== modified file 'piston_mini_client/__init__.py'
--- piston_mini_client/__init__.py	2012-07-30 17:09:26 +0000
+++ piston_mini_client/__init__.py	2012-08-26 15:27:21 +0000
@@ -225,36 +225,23 @@
         return self.as_serializable()
 
 
-class PistonAPI(object):
+class PistonRequester(object):
     """This class provides methods to make http requests slightly easier.
 
-    It's a wrapper around ``httplib2`` to allow for a bit of state to
-    be stored (like the service root) so that you don't need to repeat
-    yourself as much.
-
-    It's not intended to be used directly.  Children classes should implement
-    methods that actually call out to the api methods.
-
-    When you define your API's methods you'll
-    want to just call out to the ``_get``, ``_post``, ``_put`` or ``_delete``
-    methods provided by this class.
+    It's a wrapper around ``httplib2`` to allow for a bit of state to be
+    stored so that you don't need to repeat yourself as much.
     """
+
     SUPPORTED_SCHEMAS = ("http", "https")
-    default_service_root = ''
-    default_content_type = 'application/json'
     default_timeout = None
     fail_handler = ExceptionFailHandler
     extra_headers = None
     serializers = None
 
-    def __init__(self, service_root=None, cachedir=None, auth=None,
-                 offline_mode=False, disable_ssl_validation=False,
-                 log_filename=None, timeout=None):
-        """Initialize a ``PistonAPI``.
-
-        ``service_root`` is the url to the server's service root.
-        Children classes can provide a ``default_service_root`` class
-        attribute that will be used if ``service_root`` is ``None``.
+    def __init__(self, cachedir=None, auth=None, offline_mode=False,
+                 disable_ssl_validation=False, log_filename=None,
+                 timeout=None):
+        """Initialize a ``PistonRequest``.
 
         ``cachedir`` will be used as ``httplib2``'s cache directory if
         provided.
@@ -284,16 +271,6 @@
         default is also None, Python's default timeout for sockets will be
         used.  All these should be in seconds.
         """
-        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)
-        scheme = parsed_service_root.scheme
-        if scheme not in self.SUPPORTED_SCHEMAS:
-            raise ValueError("service_root's scheme must be http or https")
-        self._service_root = service_root
-        self._parsed_service_root = list(parsed_service_root)
         if cachedir:
             self._create_dir_if_needed(cachedir)
             self._httplib2_cache = httplib2.FileCache(cachedir, safe=safename)
@@ -372,7 +349,7 @@
             return proxy_info
         return None
 
-    def _get(self, path, args=None, scheme=None, extra_headers=None):
+    def get(self, path, args=None, scheme=None, extra_headers=None):
         """Perform an HTTP GET request.
 
         The provided ``path`` is appended to this resource's ``_service_root``
@@ -398,8 +375,13 @@
         return self._request(path, method='GET', scheme=scheme,
                              headers=headers)
 
+<<<<<<< TREE
     def _post(self, path, data=None, content_type=None, scheme=None,
               extra_headers=None):
+=======
+    def post(self, path, data=None, content_type=None, scheme=None,
+        extra_headers=None):
+>>>>>>> MERGE-SOURCE
         """Perform an HTTP POST request.
 
         The provided ``path`` is appended to this api's ``_service_root``
@@ -428,8 +410,13 @@
         return self._request(path, method='POST', body=body,
                              headers=headers, scheme=scheme)
 
+<<<<<<< TREE
     def _put(self, path, data=None, content_type=None, scheme=None,
              extra_headers=None):
+=======
+    def put(self, path, data=None, content_type=None, scheme=None,
+        extra_headers=None):
+>>>>>>> MERGE-SOURCE
         """Perform an HTTP PUT request.
 
         The provided ``path`` is appended to this api's ``_service_root``
@@ -458,7 +445,7 @@
         return self._request(path, method='PUT', body=body,
                              headers=headers, scheme=scheme)
 
-    def _delete(self, path, scheme=None, extra_headers=None):
+    def delete(self, path, scheme=None, extra_headers=None):
         """Perform an HTTP DELETE request.
 
         The provided ``path`` is appended to this resource's ``_service_root``
@@ -523,7 +510,7 @@
             body = serializer.serialize(data)
         return body
 
-    def _request(self, path, method, body='', headers=None, scheme=None):
+    def _request(self, url, method, body='', headers=None, scheme=None):
         """Perform an HTTP request.
 
         You probably want to call one of the ``_get``, ``_post``, ``_put``
@@ -531,9 +518,10 @@
         """
         if headers is None:
             headers = {}
-        if scheme not in [None, 'http', 'https']:
+        if scheme is None:
+            scheme = urlparse(url).scheme
+        if scheme not in self.SUPPORTED_SCHEMAS:
             raise ValueError('Invalid scheme %s' % scheme)
-        url = self._path2url(path, scheme=scheme)
 
         # in offline mode either get it from the cache or return None
         if self._offline_mode:
@@ -542,9 +530,6 @@
                 raise OfflineModeException(err)
             return self._get_from_cache(url)
 
-        if scheme is None:
-            scheme = urlparse(url).scheme
-
         if self._auth:
             self._auth.sign_request(url, method, body, headers)
         if self.log_filename:
@@ -599,6 +584,191 @@
                     '\r\n\r\n', 1)
                 return content
 
+    def _get_serializer(self, content_type=None):
+        # Import here to avoid a circular import
+        from piston_mini_client.serializers import get_serializer
+        if content_type is None:
+            content_type = self.default_content_type
+        default_serializer = get_serializer(content_type)
+        return self.serializers.get(content_type, default_serializer)
+
+
+class PistonAPI(object):
+    """This class provides methods to make http requests slightly easier.
+
+    It's a wrapper around ``httplib2`` to allow for a bit of state to
+    be stored (like the service root) so that you don't need to repeat
+    yourself as much.
+
+    It's not intended to be used directly.  Children classes should implement
+    methods that actually call out to the api methods.
+
+    When you define your API's methods you'll
+    want to just call out to the ``_get``, ``_post``, ``_put`` or ``_delete``
+    methods provided by this class.
+    """
+    SUPPORTED_SCHEMAS = ("http", "https")
+    default_service_root = ''
+    default_content_type = 'application/json'
+    default_timeout = None
+    fail_handler = ExceptionFailHandler
+    extra_headers = None
+    serializers = None
+
+    def __init__(self, service_root=None, cachedir=None, auth=None,
+                 offline_mode=False, disable_ssl_validation=False,
+                 log_filename=None, timeout=None):
+        """Initialize a ``PistonAPI``.
+
+        ``service_root`` is the url to the server's service root.
+        Children classes can provide a ``default_service_root`` class
+        attribute that will be used if ``service_root`` is ``None``.
+
+        ``cachedir`` will be used as ``httplib2``'s cache directory if
+        provided.
+
+        ``auth`` can be an instance of ``BasicAuthorizer`` or
+        ``OAuthAuthorizer`` or any object that provides a ``sign_request``
+        method.  If ``auth`` is ``None`` you'll only be able to make public
+        API calls.  See :ref:`authentication` for details.
+
+        ``disable_ssl_validation`` will skip server SSL certificate
+        validation when using secure connections.  ``httplib2`` < 0.7.0
+        doesn't support certificate validation anyway, so if you're using an
+        older ``httplib2`` this will have no effect.
+
+        ``offline_mode`` will not touch the network.  In this case only cached
+        results will be available.
+
+        If you pass in a ``log_filename``, all requests and responses
+        including headers will be logged to this file.
+
+        ``timeout`` will be used as a socket timeout for all calls this
+        instance makes.  To explicitly set no timeout, set timeout=0.  The
+        default timeout=None will first check for an environment variable
+        ``PISTON_MINI_CLIENT_DEFAULT_TIMEOUT`` and try to use that. If this
+        environment variable is not found or it is an invalid float, the
+        class's ``default_timeout`` will be used.  Finally, if the class's
+        default is also None, Python's default timeout for sockets will be
+        used.  All these should be in seconds.
+        """
+        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)
+        scheme = parsed_service_root.scheme
+        if scheme not in self.SUPPORTED_SCHEMAS:
+            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._requester = PistonRequester(
+            cachedir, auth, offline_mode, disable_ssl_validation,
+            log_filename, timeout)
+
+    def _get(self, path, args=None, scheme=None, extra_headers=None):
+        """Perform an HTTP GET request.
+
+        The provided ``path`` is appended to this resource's ``_service_root``
+        attribute to obtain the absolute URL that will be requested.
+
+        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.
+
+        ``extra_headers`` is an optional dictionary of header key/values that
+        will be added to the http request.
+        """
+        if args is not None:
+            if '?' in path:
+                path += '&'
+            else:
+                path += '?'
+            path += urlencode(args)
+        headers = self._prepare_headers(extra_headers=extra_headers)
+        return self._request(path, method='GET', scheme=scheme,
+            headers=headers)
+
+    def _post(self, path, data=None, content_type=None, scheme=None,
+        extra_headers=None):
+        """Perform an HTTP POST request.
+
+        The provided ``path`` is appended to this api's ``_service_root``
+        attribute to obtain the absolute URL that will be requested.  ``data``
+        should be:
+
+         - A string, in which case it will be used directly as the request's
+           body, or
+         - A ``list``, ``dict``, ``int``, ``bool`` or ``PistonSerializable``
+           (something with an ``as_serializable`` method) or even ``None``,
+           in which case it will be serialized into a string according to
+           ``content_type``.
+
+        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.
+
+        ``extra_headers`` is an optional dictionary of header key/values that
+        will be added to the http request.
+        """
+        body, headers = self._prepare_request(data, content_type,
+            extra_headers=extra_headers)
+        return self._request(path, method='POST', body=body,
+            headers=headers, scheme=scheme)
+
+    def _put(self, path, data=None, content_type=None, scheme=None,
+        extra_headers=None):
+        """Perform an HTTP PUT request.
+
+        The provided ``path`` is appended to this api's ``_service_root``
+        attribute to obtain the absolute URL that will be requested.  ``data``
+        should be:
+
+         - A string, in which case it will be used directly as the request's
+           body, or
+         - A ``list``, ``dict``, ``int``, ``bool`` or ``PistonSerializable``
+           (something with an ``as_serializable`` method) or even ``None``,
+           in which case it will be serialized into a string according to
+           ``content_type``.
+
+        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.
+
+        ``extra_headers`` is an optional dictionary of header key/values that
+        will be added to the http request.
+        """
+        body, headers = self._prepare_request(data, content_type,
+            extra_headers=extra_headers)
+        return self._request(path, method='PUT', body=body,
+            headers=headers, scheme=scheme)
+
+    def _delete(self, path, scheme=None, extra_headers=None):
+        """Perform an HTTP DELETE request.
+
+        The provided ``path`` is appended to this resource's ``_service_root``
+        attribute to obtain the absolute URL that will be requested.
+
+        ``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.
+
+        ``extra_headers`` is an optional dictionary of header key/values that
+        will be added to the http request.
+        """
+        headers = self._prepare_headers(extra_headers=extra_headers)
+        return self._request(path, method='DELETE', scheme=scheme,
+            headers=headers)
+
     def _path2url(self, path, scheme=None):
         if scheme is None:
             service_root = self._service_root
@@ -606,11 +776,3 @@
             parts = [scheme] + self._parsed_service_root[1:]
             service_root = urlunparse(parts)
         return (service_root.strip('/') + '/' + path.lstrip('/'))
-
-    def _get_serializer(self, content_type=None):
-        # Import here to avoid a circular import
-        from piston_mini_client.serializers import get_serializer
-        if content_type is None:
-            content_type = self.default_content_type
-        default_serializer = get_serializer(content_type)
-        return self.serializers.get(content_type, default_serializer)