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

[Jonathan Lange]

Add PistonRequester, enabling access to piston_mini_client functionality on a URL-by-URL basis

PistonAPI does two really useful things:
  1. It makes it really easy to define a Python front-end for an HTTP API
  2. It has a bunch of stuff to make doing HTTP requests easier

Sometimes, especially with callback services like pkgme-service, it would be really really useful to do 2. without doing 1. If you take a look at pkgme-service, you'll see code written by the original author (hello achuni!) that duplicates stuff going on in piston-mini-client.

This branch extracts that core, requesting logic into a base class and make PistonAPI subclass it. The base class is called PistonRequester (better names welcome).

Backwards compatibility has been preserved. Everything that subclasses PistonAPI today should still work after this change lands.

I've also changed setup.py to use setuptools, so I could run tox in a virtualenv.

Thanks,
jml

[lp:~jml/piston-mini-client/split-request-base-1041825]

69. By Jonathan Lange on 2012-09-20

Update docstring.

70. By Jonathan Lange on 2012-09-20

Scheme not needed in PistonRequester methods.

71. By Jonathan Lange on 2012-09-20

Give the full URL in errors, not just the service root.

72. By Jonathan Lange on 2012-09-20

Don't have special timeout handling logic. Just take parameters.

73. By Jonathan Lange on 2012-09-20

As few class variables as we can get away with.

74. By Jonathan Lange on 2012-09-20

Don't do special log_filename consulting in PistonRequester.

75. By Jonathan Lange on 2012-09-20

Use PistonRequester, rather than subclass it.

76. By Jonathan Lange on 2012-09-20

Make all the rest of the attributes private.

77. By Jonathan Lange on 2012-09-20

Issue deprecation warnings.

[Jonathan Lange (jml)]

On 2012-09-14::

16:48:19 <achuni> jml: I thought PistonAPI was going to use PistonRequester as a client in the end?
16:48:33 <achuni> (or did we agree to go the other way around in the end?)
16:48:59 <jml> achuni: you mean, use composition instead of inheritance?
16:49:04 <achuni> yep
16:49:51 <jml> achuni: I'd be very happy to do that. It'll mean potentially breaking backwards compat w/ existing PistonAPI users
16:50:21 <jml> achuni: or alternatively wrapping every existing method (e.g. _prepare_headers, _get_proxy_info, ...)
16:50:25 <achuni> jml: even if you leave the current _get / _post / ... methods there?
16:50:35 <achuni> ah, right
16:50:36 <achuni> hm
16:50:39 <jml> achuni: your call.
16:51:38 <achuni> jml: yep, we'd need to wrap all methods, I think... I'd say the wrappers can be deprecated immediately
16:52:23 <jml> achuni: want warnings for the deprecations, or are docstrings enough?
16:52:52 <achuni> jml: like PistonSerializable._as_serializable... I'm not sure that's the recommended way, but it's what was done last time
16:53:11 <jml> achuni: cool. I'll do that then.

I've now done this. I haven't cleared up the deprecation warnings in the tests.

[lp:~jml/piston-mini-client/split-request-base-1041825]

78. By Jonathan Lange on 2012-09-20

Rename to DEPRECATED_ATTRIBUTES

79. By Jonathan Lange on 2012-09-20

Update deprecation message.

80. By Jonathan Lange on 2012-09-20

Don't emit deprecation warnings on the public attributes

81. By Jonathan Lange on 2012-09-20

Fix a forwarding bug.

[Jonathan Lange (jml)]

I'm pretty sure that this version has addressed all concerns. I'd be glad to see it land.

[Anthony Lenton (elachuni)]

Thanks jml!

review: Approve

=== 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-09-20 17:51:19 +0000
@@ -225,36 +225,28 @@
         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`` that takes care of a few common tasks
+    around making HTTP requests: authentication, proxies, serialization,
+    timeouts, etc.
+
+    To use it, just instantiate it and call ``get``, ``post``, ``put`` or
+    ``delete`` to do various requests.
+
+    If you want to wrap an HTTP API, you probably want to make a subclass of
+    ``PistonAPI``, which uses 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,
+    def __init__(self, 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``.
+                 log_filename=None, timeout=None, fail_handler=None,
+                 extra_headers=None, serializers=None,
+                 default_content_type='application/json'):
+        """Initialize a ``PistonRequester``.
 
         ``cachedir`` will be used as ``httplib2``'s cache directory if
         provided.
@@ -274,26 +266,7 @@
 
         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)
         if cachedir:
             self._create_dir_if_needed(cachedir)
             self._httplib2_cache = httplib2.FileCache(cachedir, safe=safename)
@@ -302,11 +275,6 @@
         self._auth = auth
         self._offline_mode = offline_mode
         self._disable_ssl_validation = disable_ssl_validation
-        if timeout is None:
-            try:
-                timeout = float(os.environ.get(TIMEOUT_ENVVAR))
-            except (TypeError, ValueError):
-                timeout = self.default_timeout
         self._timeout = timeout
         # create one httplib2.Http object per scheme so that we can
         # have per-scheme proxy settings (see also Issue 26
@@ -314,11 +282,15 @@
         self._http = {}
         for scheme in self.SUPPORTED_SCHEMAS:
             self._http[scheme] = self._get_http_obj_for_scheme(scheme)
-        if self.serializers is None:
-            self.serializers = {}
-        if log_filename is None:
-            log_filename = os.environ.get(LOG_FILENAME_ENVVAR)
-        self.log_filename = log_filename
+        if serializers is None:
+            serializers = {}
+        self._serializers = {}
+        self._log_filename = log_filename
+        self._default_content_type = default_content_type
+        if fail_handler is None:
+            fail_handler = ExceptionFailHandler
+        self._fail_handler = fail_handler
+        self._extra_headers = extra_headers
 
     def _create_dir_if_needed(self, path):
         """ helper that checks/creates path if it does not exists
@@ -372,120 +344,17 @@
             return proxy_info
         return 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``
-        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 _prepare_request(self, data=None, content_type=None,
                          extra_headers=None):
         """Put together a set of headers and a body for a request.
 
-        If ``content_type`` is not provided, ``self.default_content_type``
+        If ``content_type`` is not provided, ``self._default_content_type``
         will be assumed.
 
         You probably never need to call this method directly.
         """
         if content_type is None:
-            content_type = self.default_content_type
+            content_type = self._default_content_type
         body = self._prepare_body(data, content_type)
         headers = self._prepare_headers(content_type, extra_headers)
         return body, headers
@@ -503,8 +372,8 @@
         headers = {}
         if content_type:
             headers['Content-type'] = content_type
-        if self.extra_headers is not None:
-            headers.update(self.extra_headers)
+        if self._extra_headers is not None:
+            headers.update(self._extra_headers)
         if extra_headers is not None:
             headers.update(extra_headers)
         return headers
@@ -523,17 +392,14 @@
             body = serializer.serialize(data)
         return body
 
-    def _request(self, path, method, body='', headers=None, scheme=None):
+    def request_url(self, url, method, body='', headers=None):
         """Perform an HTTP request.
 
-        You probably want to call one of the ``_get``, ``_post``, ``_put``
+        You probably want to call one of the ``get``, ``post``, ``put``
         methods instead.
         """
         if headers is None:
             headers = {}
-        if scheme not in [None, 'http', 'https']:
-            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,12 +408,11 @@
                 raise OfflineModeException(err)
             return self._get_from_cache(url)
 
-        if scheme is None:
-            scheme = urlparse(url).scheme
+        scheme = urlparse(url).scheme
 
         if self._auth:
             self._auth.sign_request(url, method, body, headers)
-        if self.log_filename:
+        if self._log_filename:
             self._dump_request(url, method, body, headers)
         try:
             response, response_body = self._http[scheme].request(
@@ -555,24 +420,24 @@
         except AttributeError as e:
             # Special case out httplib2's way of telling us unable to connect
             if e.args[0] == "'NoneType' object has no attribute 'makefile'":
-                raise APIError('Unable to connect to %s' % self._service_root)
+                raise APIError('Unable to connect to %s' % (url,))
             else:
                 raise
         except socket.timeout as e:
             raise TimeoutError('Timed out attempting to connect to %s' %
-                               self._service_root)
+                               (url,))
         except (socket.gaierror, socket.error) as e:
-            msg = 'connecting to %s: %s' % (self._service_root, e.message)
+            msg = 'connecting to %s: %s' % (url, e.message)
             raise SocketError(msg)
-        if self.log_filename:
+        if self._log_filename:
             self._dump_response(response, response_body)
-        handler = self.fail_handler(url, method, body, headers)
+        handler = self._fail_handler(url, method, body, headers)
         body = handler.handle(response, response_body)
         return body
 
     def _dump_request(self, url, method, body, headers):
         try:
-            with open(self.log_filename, 'a') as f:
+            with open(self._log_filename, 'a') as f:
                 formatted = format_request(url, method, body, headers)
                 f.write("{0}: {1}".format(datetime.now(), formatted))
         except IOError:
@@ -580,7 +445,7 @@
 
     def _dump_response(self, response, body):
         try:
-            with open(self.log_filename, 'a') as f:
+            with open(self._log_filename, 'a') as f:
                 formatted = format_response(response, body)
                 f.write("{0}: {1}".format(datetime.now(), formatted))
         except IOError:
@@ -599,6 +464,300 @@
                     '\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)
+
+    def get(self, url, args=None, extra_headers=None):
+        """Perform an HTTP GET request from ``url``.
+
+        If provided, ``args`` should be a dict specifying additional GET
+        arguments that will be encoded on to the end of the url.
+
+        ``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 url:
+                url += '&'
+            else:
+                url += '?'
+            url += urlencode(args)
+        headers = self._prepare_headers(extra_headers=extra_headers)
+        return self.request_url(url, method='GET', headers=headers)
+
+    def post(self, url, data=None, content_type=None, extra_headers=None):
+        """Perform an HTTP POST request to ``url``.
+
+        ``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.
+
+        ``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_url(
+            url, method='POST', body=body, headers=headers)
+
+    def put(self, url, data=None, content_type=None, extra_headers=None):
+        """Perform an HTTP PUT request to ``url``.
+
+        ``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.
+
+        ``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_url(
+            url, method='PUT', body=body, headers=headers)
+
+    def delete(self, url, extra_headers=None):
+        """Perform an HTTP DELETE request on ``url``.
+
+        ``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_url(url, method='DELETE', headers=headers)
+
+
+class _DeprecatedRequesterDecorator(object):
+
+    __DEPRECATED_ATTRIBUTES = {
+        '_httplib2_cache': '_httplib2_cache',
+        '_auth': '_auth',
+        '_offline_mode': '_offline_mode',
+        '_disable_ssl_validation': '_disable_ssl_validation',
+        '_timeout': '_timeout',
+        '_http': '_http',
+    }
+
+    def __warn(self, name):
+        import warnings
+        warnings.warn(
+            "PistonAPI.%s is deprecated; Use PistonAPI._requester.%s "
+            "instead.  Both are likely to break in the future.  Please "
+            "file a bug if you'd like them not to" % (name, name),
+            DeprecationWarning,
+            stacklevel=4)
+
+    def __getattr__(self, name):
+        if name in self.__DEPRECATED_ATTRIBUTES:
+            self.__warn(name)
+            return getattr(self._requester, self.__DEPRECATED_ATTRIBUTES[name])
+        raise AttributeError(
+            '%r object has no attribute %r'
+            % (self.__class__.__name__, name))
+
+    def __setattr__(self, name, value):
+        if name in self.__DEPRECATED_ATTRIBUTES:
+            self.__warn(name)
+            setattr(self._requester, self.__DEPRECATED_ATTRIBUTES[name], value)
+        else:
+            super(_DeprecatedRequesterDecorator, self).__setattr__(name, value)
+
+    def __deprecated_call(self, method_name, *args, **kwargs):
+        self.__warn(method_name)
+        method = getattr(self._requester, method_name)
+        return method(*args, **kwargs)
+
+    def _create_dir_if_needed(self, path):
+        """ helper that checks/creates path if it does not exists
+        """
+        return self.__deprecated_call('_create_dir_if_needed', path)
+
+    def _get_http_obj_for_scheme(self, scheme):
+        return self.__deprecated_call('_get_http_obj_for_scheme', scheme)
+
+    def _get_proxy_info(self, scheme):
+        return self.__deprecated_call('_get_proxy_info', scheme)
+
+    def _prepare_request(self, data=None, content_type=None,
+                         extra_headers=None):
+        """Put together a set of headers and a body for a request.
+
+        If ``content_type`` is not provided, ``self.default_content_type``
+        will be assumed.
+
+        You probably never need to call this method directly.
+        """
+        return self.__deprecated_call(
+            '_prepare_request', data=data, content_type=content_type,
+            extra_headers=extra_headers)
+
+    def _prepare_headers(self, content_type=None, extra_headers=None):
+        """Put together and return a complete set of headers.
+
+        If ``content_type`` is provided, it will be added as
+        the Content-type header.
+
+        Any provided ``extra_headers`` will be added last.
+
+        You probably never need to call this method directly.
+        """
+        return self.__deprecated_call(
+            '_prepare_headers', content_type=content_type,
+            extra_headers=extra_headers)
+
+    def _prepare_body(self, data=None, content_type=None):
+        """Serialize data into a request body.
+
+        ``data`` will be serialized into a string, according to
+        ``content_type``.
+
+        You probably never need to call this method directly.
+        """
+        return self.__deprecated_call(
+            '_prepare_body', data=data, content_type=content_type)
+
+    def _dump_request(self, url, method, body, headers):
+        return self.__deprecated_call(
+            '_dump_request', url, method, body, headers)
+
+    def _dump_response(self, response, body):
+        return self.__deprecated_call('_dump_response', response, body)
+
+    def _get_from_cache(self, url):
+        """ get a given url from the cachedir even if its expired
+            or return None if no data is available
+        """
+        return self.__deprecated_call('_get_from_cache', url)
+
+    def _get_serializer(self, content_type=None):
+        return self.__deprecated_call(
+            '_get_serializer', content_type=content_type)
+
+
+class PistonAPI(_DeprecatedRequesterDecorator):
+    """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 = PistonRequester.SUPPORTED_SCHEMAS
+    default_service_root = ''
+    default_timeout = None
+    fail_handler = ExceptionFailHandler
+    extra_headers = None
+    serializers = None
+    default_content_type = 'application/json'
+
+    # Attributes that are forwarded to PistonRequester for backwards
+    # compatibility reasons, but are not deprecated.
+    #
+    # Should only have attributes that users are expected to set on
+    # constructed PistonAPI instances.
+    __FORWARDED_ATTRIBUTES = {
+        'serializers': '_serializers',
+        'log_filename': '_log_filename',
+        'default_content_type': '_default_content_type',
+        'fail_handler': '_fail_handler',
+        'extra_headers': '_extra_headers',
+    }
+
+    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``.
+
+        ``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.
+
+        For all other arguments, see ``PistonRequester``.
+        """
+        if timeout is None:
+            try:
+                timeout = float(os.environ.get(TIMEOUT_ENVVAR))
+            except (TypeError, ValueError):
+                timeout = self.default_timeout
+        if log_filename is None:
+            log_filename = os.environ.get(LOG_FILENAME_ENVVAR)
+        self._requester = PistonRequester(
+            cachedir=cachedir,
+            auth=auth,
+            offline_mode=offline_mode,
+            disable_ssl_validation=disable_ssl_validation,
+            log_filename=log_filename,
+            timeout=timeout,
+            fail_handler=self.fail_handler,
+            extra_headers=self.extra_headers,
+            default_content_type=self.default_content_type,
+            serializers=self.serializers)
+        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)
+
+    def __getattr__(self, name):
+        if name in self.__FORWARDED_ATTRIBUTES:
+            return getattr(self._requester, self.__FORWARDED_ATTRIBUTES[name])
+        return super(PistonAPI, self).__getattr__(name)
+
+    def __setattr__(self, name, value):
+        if name in self.__FORWARDED_ATTRIBUTES:
+            setattr(self._requester, self.__FORWARDED_ATTRIBUTES[name], value)
+        super(PistonAPI, self).__setattr__(name, value)
+
+    def _request(self, path, method, body='', headers=None, scheme=None):
+        """Perform an HTTP request.
+
+        You probably want to call one of the ``_get``, ``_post``, ``_put``
+        methods instead.
+        """
+        url = self._path2url(path, scheme)
+        return self._requester.request_url(
+            url, method, body=body, headers=headers)
+
     def _path2url(self, path, scheme=None):
         if scheme is None:
             service_root = self._service_root
@@ -607,10 +766,96 @@
             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)
+    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.
+        """
+        return self._requester.get(
+            self._path2url(path, scheme), args=args,
+            extra_headers=extra_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.
+        """
+        return self._requester.post(
+            self._path2url(path, scheme), data=data,
+            content_type=content_type, extra_headers=extra_headers)
+
+    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.
+        """
+        return self._requester.put(
+            self._path2url(path, scheme), data=data,
+            content_type=content_type, extra_headers=extra_headers)
+
+    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.
+        """
+        return self._requester.delete(
+            self._path2url(path, scheme), extra_headers=extra_headers)

=== modified file 'piston_mini_client/tests/test_failhandlers.py'
--- piston_mini_client/tests/test_failhandlers.py	2012-07-30 17:09:26 +0000
+++ piston_mini_client/tests/test_failhandlers.py	2012-09-20 17:51:19 +0000
@@ -143,6 +143,21 @@
 
         self.assertEqual(None, api.grow())
 
+    def test_set_via_class_variable(self):
+        """fail_handler can be overridden by specifying it as a class variable.
+        """
+        api = GardeningAPI()
+        self.assertEqual(NoneFailHandler, api.fail_handler)
+
+    def test_forwarding(self):
+        """Setting fail_handler on a PistonAPI instance actually works."""
+        sentinel = object()
+        api = GardeningAPI()
+        api.fail_handler = sentinel
+        self.assertEqual(sentinel, api.fail_handler)
+        # Not a public API, so OK if future changes break this.
+        self.assertEqual(sentinel, api._requester._fail_handler)
+
     @patch('httplib2.Http.request')
     def test_interacts_well_with_returns_on_fail(self, mock_request):
         """Check that NoneFailHandler interacts well with returns"""

=== modified file 'piston_mini_client/tests/test_log_to_file.py'
--- piston_mini_client/tests/test_log_to_file.py	2012-07-30 17:09:26 +0000
+++ piston_mini_client/tests/test_log_to_file.py	2012-09-20 17:51:19 +0000
@@ -76,4 +76,4 @@
         api = AnnoyAPI()
 
         self.assertEqual(api.log_filename, sentinel)
-        mock_get.assert_called_with(LOG_FILENAME_ENVVAR)
+        mock_get.assert_any_call(LOG_FILENAME_ENVVAR)

=== modified file 'setup.py'
--- setup.py	2012-06-13 13:25:54 +0000
+++ setup.py	2012-09-20 17:51:19 +0000
@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 
-from distutils.core import setup
+from setuptools import setup
 
 setup(name='piston-mini-client',
     version='0.7.2',