Merge lp:~leonardr/launchpadlib/restfulclient into lp:~launchpad-pqm/launchpadlib/devel

[Leonard Richardson]

[Leonard Richardson (leonardr)]

Pre-imple: flacoste
Tests: ./test.py -vvt launchpadlib.
Diff: https://pastebin.canonical.com/15558/

This branch refactors almost all of the launchpadlib code into a
generic library called "restfulclient". In a future branch this code
will be separated from launchpadlib and put in the lazr.restfulclient
project.

launchpadlib is now a very small specialization. The
Launchpad-specific code is as follows:

* PersonSet, BugSet, PillarSet: Launchpad-specific data object classes.

* Launchpad: Now a specialization of restfulclient's ServiceRoot, the
  Launchpad class includes code for tracking OAuth credentials.

* OAuthSigningHttp: A specialization of restfulclient's RestfulHttp
  which signs an outgoing HTTP request with OAuth credentials.

* credentials.py is pretty much unchanged.

One thing I haven't done is move wadl-to-refhtml.xsl into
restfulclient. This would mean changing the Launchpad Makefile, which
would mean landing Launchpad and launchpadlib changes
simultaneously. Then I'd have to do it all again when I separate the
restfulclient directory out into the lazr.restfulclient project. I'll
move wadl-to-refhtml.xsl directly into lazr.restfulclient in my next
branch, and save myself the trouble

[Celso Providelo (cprov)]

Hi Leonard,

Tests pass and the code looks good.

The transition with the restfulclient library within launchpadlib was a very good idea, it makes the migration much easier. Thanks for thinking about it.

r=me, nothing to complain about ;)

review: Approve

[lp:~leonardr/launchpadlib/restfulclient]

45. By Leonard Richardson on 2009-03-30

Removed xsl file that was moved to restfulclient.

Unmerged revisions

45. By Leonard Richardson on 2009-03-30

Removed xsl file that was moved to restfulclient.

44. By Leonard Richardson on 2009-03-26

Changed imports to reduce the size of the diff.

43. By Leonard Richardson on 2009-03-26

Moved wadl-to-refhtml.xsl back so I don't have to change launchpadlib and launchpad simultaneously more than once.

42. By Leonard Richardson on 2009-03-26

Renamed LaunchpadError.

41. By Leonard Richardson on 2009-03-26

Removed now-useless file.

40. By Leonard Richardson on 2009-03-26

Fixed copyright notices.

=== removed file 'src/launchpadlib/_browser.py'
--- src/launchpadlib/_browser.py	2009-03-20 20:46:06 +0000
+++ src/launchpadlib/_browser.py	1970-01-01 00:00:00 +0000
@@ -1,265 +0,0 @@
-# Copyright 2008 Canonical Ltd.
-
-# This file is part of launchpadlib.
-#
-# launchpadlib is free software: you can redistribute it and/or modify it
-# under the terms of the GNU Lesser General Public License as published by the
-# Free Software Foundation, version 3 of the License.
-#
-# launchpadlib is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
-# for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with launchpadlib. If not, see <http://www.gnu.org/licenses/>.
-
-"""Browser object to make requests of Launchpad web service.
-
-The `Browser` class implements OAuth authenticated communications with
-Launchpad.  It is not part of the public launchpadlib API.
-"""
-
-__metaclass__ = type
-__all__ = [
-    'Browser',
-    ]
-
-
-import atexit
-from cStringIO import StringIO
-import gzip
-from httplib2 import (
-    FailedToDecompressContent, FileCache, Http, safename, urlnorm)
-from lazr.uri import URI
-from oauth.oauth import (
-    OAuthRequest, OAuthSignatureMethod_PLAINTEXT)
-import shutil
-import simplejson
-import tempfile
-from urllib import urlencode
-from wadllib.application import Application
-import zlib
-
-from launchpadlib.errors import HTTPError
-from launchpadlib._json import DatetimeJSONEncoder
-
-
-OAUTH_REALM = 'https://api.launchpad.net'
-
-# A drop-in replacement for httplib2's _decompressContent, which looks
-# in the Transfer-Encoding header instead of in Content-Encoding.
-def _decompressContent(response, new_content):
-    content = new_content
-    try:
-        encoding = response.get('transfer-encoding', None)
-        if encoding in ['gzip', 'deflate']:
-            if encoding == 'gzip':
-                content = gzip.GzipFile(
-                    fileobj=StringIO.StringIO(new_content)).read()
-            if encoding == 'deflate':
-                content = zlib.decompress(content)
-            response['content-length'] = str(len(content))
-            del response['transfer-encoding']
-    except IOError:
-        content = ""
-        raise FailedToDecompressContent(
-            ("Content purported to be compressed with %s but failed "
-             "to decompress." % response.get('transfer-encoding')),
-            response, content)
-    return content
-
-
-class OAuthSigningHttp(Http):
-    """A client that signs every outgoing request with OAuth credentials."""
-
-    def __init__(self, oauth_credentials, cache=None, timeout=None,
-                 proxy_info=None):
-        self.oauth_credentials = oauth_credentials
-        Http.__init__(self, cache, timeout, proxy_info)
-
-    def _request(self, conn, host, absolute_uri, request_uri, method, body,
-                 headers, redirections, cachekey):
-        """Sign a request with OAuth credentials before sending it."""
-        oauth_request = OAuthRequest.from_consumer_and_token(
-            self.oauth_credentials.consumer,
-            self.oauth_credentials.access_token,
-            http_url=absolute_uri)
-        oauth_request.sign_request(
-            OAuthSignatureMethod_PLAINTEXT(),
-            self.oauth_credentials.consumer,
-            self.oauth_credentials.access_token)
-        if headers.has_key('authorization'):
-            # There's an authorization header left over from a
-            # previous request that resulted in a redirect. Remove it
-            # and start again.
-            del headers['authorization']
-
-        # httplib2 asks for compressed representations in
-        # Accept-Encoding.  But a different content-encoding means a
-        # different ETag, which can cause problems later when we make
-        # a conditional request. We don't want to treat a
-        # representation differently based on whether or not we asked
-        # for a compressed version of it.
-        #
-        # So we move the compression request from Accept-Encoding to
-        # TE. Transfer-encoding compression can be handled transparently.
-        if 'accept-encoding' in headers:
-            headers['te'] = 'deflate, gzip'
-            del headers['accept-encoding']
-        headers.update(oauth_request.to_header(OAUTH_REALM))
-        return super(OAuthSigningHttp, self)._request(
-            conn, host, absolute_uri, request_uri, method, body, headers,
-            redirections, cachekey)
-
-    def _conn_request(self, conn, request_uri, method, body, headers):
-        """Decompress content using our version of _decompressContent."""
-        response, content = super(OAuthSigningHttp, self)._conn_request(
-            conn, request_uri, method, body, headers)
-        # Decompress the response, if it was compressed.
-        if method != "HEAD":
-            content = _decompressContent(response, content)
-        return (response, content)
-
-    def _getCachedHeader(self, uri, header):
-        """Retrieve a cached value for an HTTP header."""
-        if isinstance(self.cache, MultipleRepresentationCache):
-            return self.cache._getCachedHeader(uri, header)
-        return None
-
-
-class MultipleRepresentationCache(FileCache):
-    """A cache that can hold different representations of the same resource.
-
-    If a resource has two representations with two media types,
-    FileCache will only store the most recently fetched
-    representation. This cache can keep track of multiple
-    representations of the same resource.
-
-    This class works on the assumption that outside calling code sets
-    an instance's request_media_type attribute to the value of the
-    'Accept' header before initiating the request.
-
-    This class is very much not thread-safe, but FileCache isn't
-    thread-safe anyway.
-    """
-    def __init__(self, cache):
-        """Tell FileCache to call append_media_type when generating keys."""
-        super(MultipleRepresentationCache, self).__init__(
-            cache, self.append_media_type)
-        self.request_media_type = None
-
-    def append_media_type(self, key):
-        """Append the request media type to the cache key.
-
-        This ensures that representations of the same resource will be
-        cached separately, so long as they're served as different
-        media types.
-        """
-        if self.request_media_type is not None:
-            key = key + '-' + self.request_media_type
-        return safename(key)
-
-
-    def _getCachedHeader(self, uri, header):
-        """Retrieve a cached value for an HTTP header."""
-        (scheme, authority, request_uri, cachekey) = urlnorm(uri)
-        cached_value = self.get(cachekey)
-        header_start = header + ':'
-        if cached_value is not None:
-            for line in StringIO(cached_value):
-                if line.startswith(header_start):
-                    return line[len(header_start):].strip()
-        return None
-
-
-class Browser:
-    """A class for making calls to Launchpad web services."""
-
-    def __init__(self, credentials, cache=None, timeout=None,
-                 proxy_info=None):
-        """Initialize, possibly creating a cache.
-
-        If no cache is provided, a temporary directory will be used as
-        a cache. The temporary directory will be automatically removed
-        when the Python process exits.
-        """
-        if cache is None:
-            cache = tempfile.mkdtemp()
-            atexit.register(shutil.rmtree, cache)
-        if isinstance(cache, str):
-            cache = MultipleRepresentationCache(cache)
-        self._connection = OAuthSigningHttp(
-            credentials, cache, timeout, proxy_info)
-
-    def _request(self, url, data=None, method='GET',
-                 media_type='application/json', extra_headers=None):
-        """Create an authenticated request object."""
-        # Add extra headers for the request.
-        headers = {'Accept' : media_type}
-        if isinstance(self._connection.cache, MultipleRepresentationCache):
-            self._connection.cache.request_media_type = media_type
-        if extra_headers is not None:
-            headers.update(extra_headers)
-        # Make the request. It will be signed automatically when
-        # _request is called.
-        response, content = self._connection.request(
-            str(url), method=method, body=data, headers=headers)
-        # Turn non-2xx responses into exceptions.
-        if response.status // 100 != 2:
-            raise HTTPError(response, content)
-        return response, content
-
-    def get(self, resource_or_uri, headers=None, return_response=False):
-        """GET a representation of the given resource or URI."""
-        if isinstance(resource_or_uri, (basestring, URI)):
-            url = resource_or_uri
-        else:
-            method = resource_or_uri.get_method('get')
-            url = method.build_request_url()
-        response, content = self._request(url, extra_headers=headers)
-        if return_response:
-            return (response, content)
-        return content
-
-    def get_wadl_application(self, url):
-        """GET a WADL representation of the resource at the requested url."""
-        response, content = self._request(
-            url, media_type='application/vd.sun.wadl+xml')
-        return Application(str(url), content)
-
-    def post(self, url, method_name, **kws):
-        """POST a request to the web service."""
-        kws['ws.op'] = method_name
-        data = urlencode(kws)
-        return self._request(url, data, 'POST')
-
-    def put(self, url, representation, media_type, headers=None):
-        """PUT the given representation to the URL."""
-        extra_headers = {'Content-Type': media_type}
-        if headers is not None:
-            extra_headers.update(headers)
-        return self._request(
-            url, representation, 'PUT', extra_headers=extra_headers)
-
-    def delete(self, url):
-        """DELETE the resource at the given URL."""
-        self._request(url, method='DELETE')
-
-    def patch(self, url, representation, headers=None):
-        """PATCH the object at url with the updated representation."""
-        extra_headers = {'Content-Type': 'application/json'}
-        if headers is not None:
-            extra_headers.update(headers)
-        # httplib2 doesn't know about the PATCH method, so we need to
-        # do some work ourselves. Pull any cached value of "ETag" out
-        # and use it as the value for "If-Match".
-        cached_etag = self._connection._getCachedHeader(str(url), 'etag')
-        if cached_etag is not None and not self._connection.ignore_etag:
-            # http://www.w3.org/1999/04/Editing/
-            headers['If-Match'] = cached_etag
-
-        return self._request(
-            url, simplejson.dumps(representation,
-                                  cls=DatetimeJSONEncoder),
-            'PATCH', extra_headers=extra_headers)

=== modified file 'src/launchpadlib/credentials.py'
--- src/launchpadlib/credentials.py	2009-03-23 21:50:35 +0000
+++ src/launchpadlib/credentials.py	2009-03-26 19:26:13 +0000
@@ -29,7 +29,7 @@
 from oauth.oauth import OAuthConsumer, OAuthToken
 from urllib import urlencode
 
-from launchpadlib.errors import CredentialsFileError, HTTPError
+from launchpadlib.restfulclient.errors import CredentialsFileError, HTTPError
 
 
 CREDENTIALS_FILE_VERSION = '1'

=== modified file 'src/launchpadlib/errors.py'
--- src/launchpadlib/errors.py	2009-03-20 20:46:06 +0000
+++ src/launchpadlib/errors.py	2009-03-26 19:08:48 +0000
@@ -14,50 +14,7 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with launchpadlib. If not, see <http://www.gnu.org/licenses/>.
 
-"""launchpadlib errors."""
-
-__metaclass__ = type
-__all__ = [
-    'CredentialsError',
-    'CredentialsFileError',
-    'HTTPError',
-    'LaunchpadError',
-    'ResponseError',
-    'UnexpectedResponseError',
-    ]
-
-
-class LaunchpadError(Exception):
-    """Base error for the Launchpad API library."""
-
-
-class CredentialsError(LaunchpadError):
-    """Base credentials/authentication error."""
-
-
-class CredentialsFileError(CredentialsError):
-    """Error in credentials file."""
-
-
-class ResponseError(LaunchpadError):
-    """Error in response."""
-
-    def __init__(self, response, content):
-        LaunchpadError.__init__(self)
-        self.response = response
-        self.content = content
-
-
-class UnexpectedResponseError(ResponseError):
-    """An unexpected response was received."""
-
-    def __str__(self):
-        return '%s: %s' % (self.response.status, self.response.reason)
-
-
-class HTTPError(ResponseError):
-    """An HTTP non-2xx response code was received."""
-
-    def __str__(self):
-        return 'HTTP Error %s: %s' % (
-            self.response.status, self.response.reason)
+
+"""Reimport errors from restfulclient for convenience's sake."""
+
+from launchpadlib.restfulclient.errors import *

=== modified file 'src/launchpadlib/launchpad.py'
--- src/launchpadlib/launchpad.py	2009-03-23 21:50:35 +0000
+++ src/launchpadlib/launchpad.py	2009-03-26 19:26:13 +0000
@@ -21,32 +21,64 @@
     'Launchpad',
     ]
 
-import os
-import shutil
-import simplejson
-import stat
 import sys
-import tempfile
-import urlparse
 import webbrowser
 
-from wadllib.application import Resource as WadlResource
 from lazr.uri import URI
-
-from launchpadlib._browser import Browser
-from launchpadlib.resource import Resource
+from launchpadlib.restfulclient.resource import (
+    CollectionWithKeyBasedLookup, HostedFile, ServiceRoot)
 from launchpadlib.credentials import AccessToken, Credentials
+from oauth.oauth import OAuthRequest, OAuthSignatureMethod_PLAINTEXT
+from launchpadlib.restfulclient._browser import RestfulHttp
 
+OAUTH_REALM = 'https://api.launchpad.net'
 STAGING_SERVICE_ROOT = 'https://api.staging.launchpad.net/beta/'
 EDGE_SERVICE_ROOT = 'https://api.edge.launchpad.net/beta/'
 
-class Launchpad(Resource):
+
+class PersonSet(CollectionWithKeyBasedLookup):
+    """A custom subclass capable of person lookup by username."""
+
+    def _get_url_from_id(self, key):
+        """Transform a username into the URL to a person resource."""
+        return str(self._root._root_uri.ensureSlash()) + '~' + str(key)
+
+
+class BugSet(CollectionWithKeyBasedLookup):
+    """A custom subclass capable of bug lookup by bug ID."""
+
+    def _get_url_from_id(self, key):
+        """Transform a bug ID into the URL to a bug resource."""
+        return str(self._root._root_uri.ensureSlash()) + 'bugs/' + str(key)
+
+
+class PillarSet(CollectionWithKeyBasedLookup):
+    """A custom subclass capable of lookup by pillar name.
+
+    Projects, project groups, and distributions are all pillars.
+    """
+
+    def _get_url_from_id(self, key):
+        """Transform a project name into the URL to a project resource."""
+        return str(self._root._root_uri.ensureSlash()) + str(key)
+
+
+class Launchpad(ServiceRoot):
     """Root Launchpad API class.
 
     :ivar credentials: The credentials instance used to access Launchpad.
     :type credentials: `Credentials`
     """
 
+    RESOURCE_TYPE_CLASSES = {
+            'bugs': BugSet,
+            'distributions': PillarSet,
+            'HostedFile': HostedFile,
+            'people': PersonSet,
+            'project_groups': PillarSet,
+            'projects': PillarSet,
+            }
+
     def __init__(self, credentials, service_root=STAGING_SERVICE_ROOT,
                  cache=None, timeout=None, proxy_info=None):
         """Root access to the Launchpad API.
@@ -56,34 +88,11 @@
         :param service_root: The URL to the root of the web service.
         :type service_root: string
         """
-        self._root_uri = URI(service_root)
-        self.credentials = credentials
-        # Get the WADL definition.
-        self._browser = Browser(self.credentials, cache, timeout, proxy_info)
-        self._wadl = self._browser.get_wadl_application(self._root_uri)
-
-        # Get the root resource.
-        root_resource = self._wadl.get_resource_by_path('')
-        bound_root = root_resource.bind(
-            self._browser.get(root_resource), 'application/json')
-        super(Launchpad, self).__init__(None, bound_root)
-
-    def load(self, url):
-        """Load a resource given its URL."""
-        document = self._browser.get(url)
-        try:
-            representation = simplejson.loads(document)
-        except ValueError:
-            raise ValueError("%s doesn't serve a JSON document." % url)
-        type_link = representation.get("resource_type_link")
-        if type_link is None:
-            raise ValueError("Couldn't determine the resource type of %s."
-                             % url)
-        resource_type = self._root._wadl.get_resource_type(type_link)
-        wadl_resource = WadlResource(self._root._wadl, url, resource_type.tag)
-        return self._create_bound_resource(
-            self._root, wadl_resource, representation, 'application/json',
-            representation_needs_processing=False)
+        super(Launchpad, self).__init__(
+            credentials, service_root, cache, timeout, proxy_info)
+
+    def httpFactory(self, credentials, cache, timeout, proxy_info):
+        return OAuthSigningHttp(credentials, cache, timeout, proxy_info)
 
     @classmethod
     def login(cls, consumer_name, token_string, access_secret,
@@ -157,69 +166,27 @@
         credentials.exchange_request_token_for_access_token(web_root)
         return cls(credentials, service_root, cache, timeout, proxy_info)
 
-    @classmethod
-    def login_with(cls, consumer_name,
-                   service_root=STAGING_SERVICE_ROOT,
-                   launchpadlib_dir=None, timeout=None, proxy_info=None):
-        """Log in to Launchpad with possibly cached credentials.
-
-        This is a convenience method for either setting up new login
-        credentials, or re-using existing ones. When a login token is
-        generated using this method, the resulting credentials will be
-        saved in the `launchpadlib_dir` directory. If the same
-        `launchpadlib_dir` is passed in a second time, the credentials
-        in `launchpadlib_dir` for the consumer will be used
-        automatically.
-
-        Each consumer has their own credentials per service root in
-        `launchpadlib_dir`. `launchpadlib_dir` is also used for caching
-        fetched objects. The cache is per service root, and shared by
-        all consumers.
-
-        See `Launchpad.get_token_and_login()` for more information about
-        how new tokens are generated.
-
-        :param consumer_name: The consumer name, as appropriate for the
-            `Consumer` constructor
-        :type consumer_name: string
-        :param service_root: The URL to the root of the web service.
-        :type service_root: string
-        :param launchpadlib_dir: The directory where the cache and
-            credentials are stored.
-        :type launchpadlib_dir: string
-        :return: The web service root
-        :rtype: `Launchpad`
-
-        """
-        if launchpadlib_dir is None:
-            home_dir = os.environ['HOME']
-            launchpadlib_dir = os.path.join(home_dir, '.launchpadlib')
-        launchpadlib_dir = os.path.expanduser(launchpadlib_dir)
-        # Each service root has its own cache and credential dirs.
-        scheme, host_name, path, query, fragment = urlparse.urlsplit(
-            service_root)
-        service_root_dir = os.path.join(launchpadlib_dir, host_name)
-        cache_path = os.path.join(service_root_dir, 'cache')
-        if not os.path.exists(cache_path):
-            os.makedirs(cache_path)
-        credentials_path = os.path.join(service_root_dir, 'credentials')
-        if not os.path.exists(credentials_path):
-            os.makedirs(credentials_path)
-        consumer_credentials_path = os.path.join(
-            credentials_path, consumer_name)
-        if os.path.exists(consumer_credentials_path):
-            credentials = Credentials.load_from_path(
-                consumer_credentials_path)
-            launchpad = cls(
-                credentials, service_root=service_root, cache=cache_path,
-                timeout=timeout, proxy_info=proxy_info)
-        else:
-            launchpad = cls.get_token_and_login(
-                consumer_name, service_root=service_root, cache=cache_path,
-                timeout=timeout, proxy_info=proxy_info)
-            launchpad.credentials.save_to_path(
-                os.path.join(credentials_path, consumer_name))
-            os.chmod(
-                os.path.join(credentials_path, consumer_name),
-                stat.S_IREAD | stat.S_IWRITE)
-        return launchpad
+
+class OAuthSigningHttp(RestfulHttp):
+    """A client that signs every outgoing request with OAuth credentials."""
+
+    def _request(self, conn, host, absolute_uri, request_uri, method, body,
+                 headers, redirections, cachekey):
+        """Sign a request with OAuth credentials before sending it."""
+        oauth_request = OAuthRequest.from_consumer_and_token(
+            self.restful_credentials.consumer,
+            self.restful_credentials.access_token,
+            http_url=absolute_uri)
+        oauth_request.sign_request(
+            OAuthSignatureMethod_PLAINTEXT(),
+            self.restful_credentials.consumer,
+            self.restful_credentials.access_token)
+        if headers.has_key('authorization'):
+            # There's an authorization header left over from a
+            # previous request that resulted in a redirect. Remove it
+            # and start again.
+            del headers['authorization']
+        headers.update(oauth_request.to_header(OAUTH_REALM))
+        return super(OAuthSigningHttp, self)._request(
+            conn, host, absolute_uri, request_uri, method, body, headers,
+            redirections, cachekey)

=== removed file 'src/launchpadlib/resource.py'
--- src/launchpadlib/resource.py	2009-03-20 20:46:06 +0000
+++ src/launchpadlib/resource.py	1970-01-01 00:00:00 +0000
@@ -1,830 +0,0 @@
-# Copyright 2008 Canonical Ltd.
-
-# This file is part of launchpadlib.
-#
-# launchpadlib is free software: you can redistribute it and/or modify it
-# under the terms of the GNU Lesser General Public License as published by the
-# Free Software Foundation, version 3 of the License.
-#
-# launchpadlib is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
-# for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with launchpadlib. If not, see <http://www.gnu.org/licenses/>.
-
-"""Common support for web service resources."""
-
-__metaclass__ = type
-__all__ = [
-    'Collection',
-    'Entry',
-    'NamedOperation',
-    'Resource',
-    ]
-
-
-import cgi
-import simplejson
-from StringIO import StringIO
-import urllib
-from urlparse import urlparse
-from lazr.uri import URI
-
-from launchpadlib._json import DatetimeJSONEncoder
-from launchpadlib.errors import HTTPError
-from wadllib.application import Resource as WadlResource
-
-
-class HeaderDictionary:
-    """A dictionary that bridges httplib2's and wadllib's expectations.
-
-    httplib2 expects all header dictionary access to give lowercase
-    header names. wadllib expects to access the header exactly as it's
-    specified in the WADL file, which means the official HTTP header name.
-
-    This class transforms keys to lowercase before doing a lookup on
-    the underlying dictionary. That way wadllib can pass in the
-    official header name and httplib2 will get the lowercased name.
-    """
-    def __init__(self, wrapped_dictionary):
-        self.wrapped_dictionary = wrapped_dictionary
-
-    def get(self, key, default=None):
-        """Retrieve a value, converting the key to lowercase."""
-        return self.wrapped_dictionary.get(key.lower())
-
-    def __getitem__(self, key):
-        """Retrieve a value, converting the key to lowercase."""
-        missing = object()
-        value = self.get(key, missing)
-        if value is missing:
-            raise KeyError(key)
-        return value
-
-
-class LaunchpadBase:
-    """Base class for classes that know about Launchpad."""
-
-    JSON_MEDIA_TYPE = 'application/json'
-
-    def _transform_resources_to_links(self, dictionary):
-        new_dictionary = {}
-        for key, value in dictionary.items():
-            if isinstance(value, Resource):
-                value = value.self_link
-            new_dictionary[self._get_external_param_name(key)] = value
-        return new_dictionary
-
-    def _get_external_param_name(self, param_name):
-        """Turn a launchpadlib name into something to be sent over HTTP.
-
-        For resources this may involve sticking '_link' or
-        '_collection_link' on the end of the parameter name. For
-        arguments to named operations, the parameter name is returned
-        as is.
-        """
-        return param_name
-
-
-class Resource(LaunchpadBase):
-    """Base class for Launchpad's HTTP resources."""
-
-    def __init__(self, root, wadl_resource):
-        """Initialize with respect to a wadllib Resource object."""
-        if root is None:
-            # This _is_ the root.
-            root = self
-        # These values need to be put directly into __dict__ to avoid
-        # calling __setattr__, which would cause an infinite recursion.
-        self.__dict__['_root'] = root
-        self.__dict__['_wadl_resource'] = wadl_resource
-
-    FIND_COLLECTIONS = object()
-    FIND_ENTRIES = object()
-    FIND_ATTRIBUTES = object()
-
-    @property
-    def lp_collections(self):
-        """Name the collections this resource links to."""
-        return self._get_parameter_names(self.FIND_COLLECTIONS)
-
-    @property
-    def lp_entries(self):
-        """Name the entries this resource links to."""
-        return self._get_parameter_names(self.FIND_ENTRIES)
-
-    @property
-    def lp_attributes(self):
-        """Name this resource's scalar attributes."""
-        return self._get_parameter_names(self.FIND_ATTRIBUTES)
-
-    @property
-    def lp_operations(self):
-        """Name all of this resource's custom operations."""
-        # This library distinguishes between named operations by the
-        # value they give for ws.op, not by their WADL names or IDs.
-        names = []
-        form_encoded_type = 'application/x-www-form-urlencoded'
-        for method in self._wadl_resource.method_iter:
-            name = method.name.lower()
-            if name == 'get':
-                params = method.request.params(['query', 'plain'])
-            elif name == 'post':
-                definition = method.request.representation_definition(
-                    form_encoded_type).resolve_definition()
-                params = definition.params(self._wadl_resource)
-            for param in params:
-                if param.name == 'ws.op':
-                    names.append(param.fixed_value)
-                    break
-        return names
-
-    @property
-    def __members__(self):
-        """A hook into dir() that returns web service-derived members."""
-        return self._get_parameter_names(
-            self.FIND_COLLECTIONS, self.FIND_ENTRIES, self.FIND_ATTRIBUTES)
-
-    __methods__ = lp_operations
-
-    def _get_parameter_names(self, *kinds):
-        """Retrieve some subset of the resource's parameters."""
-        names = []
-        for name in self._wadl_resource.parameter_names(
-            self.JSON_MEDIA_TYPE):
-            if name.endswith('_collection_link'):
-                if self.FIND_COLLECTIONS in kinds:
-                    names.append(name[:-16])
-            elif (name.endswith('_link')
-                  and name not in ('self_link', 'resource_type_link')):
-                # launchpadlib_obj.self will work, but is never
-                # necessary. launchpadlib_obj.resource_type is also
-                # unneccessary, and won't work anyway because
-                # resource_type_link points to a WADL description,
-                # not a normal Launchpad resource.
-                if self.FIND_ENTRIES in kinds:
-                    names.append(name[:-5])
-            elif self.FIND_ATTRIBUTES in kinds:
-                names.append(name)
-        return names
-
-    def lp_has_parameter(self, param_name):
-        """Does this resource have a parameter with the given name?"""
-        return self._get_external_param_name(param_name) is not None
-
-    def lp_get_parameter(self, param_name):
-        """Get the value of one of the resource's parameters.
-
-        :return: A scalar value if the parameter is not a link. A new
-                 Resource object, whose resource is bound to a
-                 representation, if the parameter is a link.
-        """
-        self._ensure_representation()
-        for suffix in ['_link', '_collection_link']:
-            param = self._wadl_resource.get_parameter(
-                param_name + suffix, self.JSON_MEDIA_TYPE)
-            if param is not None:
-                if param.get_value() is None:
-                    # This parameter is a link to another object, but
-                    # there's no other object. Return None rather than
-                    # chasing down the nonexistent other object.
-                    return None
-                linked_resource = param.linked_resource
-                return self._create_bound_resource(
-                    self._root, linked_resource, param_name=param.name)
-        param = self._wadl_resource.get_parameter(param_name)
-        if param is None:
-            raise KeyError("No such parameter: %s" % param_name)
-        return param.get_value()
-
-    def lp_get_named_operation(self, operation_name):
-        """Get a custom operation with the given name.
-
-        :return: A NamedOperation instance that can be called with
-                 appropriate arguments to invoke the operation.
-        """
-        params = { 'ws.op' : operation_name }
-        method = self._wadl_resource.get_method('get', query_params=params)
-        if method is None:
-            method = self._wadl_resource.get_method(
-                'post', representation_params=params)
-        if method is None:
-            raise KeyError("No operation with name: %s" % operation_name)
-        return NamedOperation(self._root, self, method)
-
-    @classmethod
-    def _create_bound_resource(
-        cls, root, resource, representation=None,
-        representation_media_type='application/json',
-        representation_needs_processing=True, representation_definition=None,
-        param_name=None):
-        """Create a launchpadlib Resource subclass from a wadllib Resource.
-
-        :param resource: The wadllib Resource to wrap.
-        :param representation: A previously fetched representation of
-            this resource, to be reused. If not provided, this method
-            will act just like the Resource constructor.
-        :param representation_media_type: The media type of any previously
-            fetched representation.
-        :param representation_needs_processing: Set to False if the
-            'representation' parameter should be used as
-            is.
-        :param representation_definition: A wadllib
-            RepresentationDefinition object describing the structure
-            of this representation. Used in cases when the representation
-            isn't the result of sending a standard GET to the resource.
-        :param param_name: The name of the link that was followed to get
-            to this resource.
-        :return: An instance of the appropriate launchpadlib Resource
-            subclass.
-        """
-        # We happen to know that all Launchpad resource types are
-        # defined in a single document. Turn the resource's type_url
-        # into an anchor into that document: this is its resource
-        # type. Then look up a client-side class that corresponds to
-        # the resource type.
-        type_url = resource.type_url
-        resource_type = urlparse(type_url)[-1]
-        default = Entry
-        if (type_url.endswith('-page')
-            or (param_name is not None
-                and param_name.endswith('_collection_link'))):
-            default = Collection
-        r_class = RESOURCE_TYPE_CLASSES.get(resource_type, default)
-        if representation is not None:
-            # We've been given a representation. Bind the resource
-            # immediately.
-            resource = resource.bind(
-                representation, representation_media_type,
-                representation_needs_processing,
-                representation_definition=representation_definition)
-        else:
-            # We'll fetch a representation and bind the resource when
-            # necessary.
-            pass
-        return r_class(root, resource)
-
-    def lp_refresh(self, new_url=None, etag=None):
-        """Update this resource's representation."""
-        if new_url is not None:
-            self._wadl_resource._url = new_url
-        headers = {}
-        if etag is not None:
-            headers['If-None-Match'] = etag
-        try:
-            representation = self._root._browser.get(
-                self._wadl_resource, headers=headers)
-        except HTTPError, e:
-            if e.response['status'] == '304':
-                # The entry wasn't modified. No need to do anything.
-                return
-            else:
-                raise e
-        # __setattr__ assumes we're setting an attribute of the resource,
-        # so we manipulate __dict__ directly.
-        self.__dict__['_wadl_resource'] = self._wadl_resource.bind(
-            representation, self.JSON_MEDIA_TYPE)
-
-    def __getattr__(self, attr):
-        """Try to retrive a named operation or parameter of the given name."""
-        try:
-            return self.lp_get_parameter(attr)
-        except KeyError:
-            pass
-        try:
-            return self.lp_get_named_operation(attr)
-        except KeyError:
-            raise AttributeError("'%s' object has no attribute '%s'"
-                                 % (self.__class__.__name__, attr))
-
-    def _get_external_param_name(self, param_name):
-        """What's this parameter's name in the underlying representation?"""
-        for suffix in ['_link', '_collection_link', '']:
-            name = param_name + suffix
-            if self._wadl_resource.get_parameter(name):
-                return name
-        return None
-
-    def _ensure_representation(self):
-        """Make sure this resource has a representation fetched."""
-        if self._wadl_resource.representation is None:
-            # Get a representation of the linked resource.
-            representation = self._root._browser.get(self._wadl_resource)
-            self.__dict__['_wadl_resource'] = self._wadl_resource.bind(
-                representation, self.JSON_MEDIA_TYPE)
-
-
-class NamedOperation(LaunchpadBase):
-    """A class for a named operation to be invoked with GET or POST."""
-
-    def __init__(self, root, resource, wadl_method):
-        """Initialize with respect to a WADL Method object"""
-        self.root = root
-        self.resource = resource
-        self.wadl_method = wadl_method
-
-    def __call__(self, *args, **kwargs):
-        """Invoke the method and process the result."""
-        if len(args) > 0:
-            raise TypeError('Method must be called with keyword args.')
-        http_method = self.wadl_method.name
-        args = self._transform_resources_to_links(kwargs)
-        for key, value in args.items():
-            args[key] = simplejson.dumps(value, cls=DatetimeJSONEncoder)
-        if http_method in ('get', 'head', 'delete'):
-            url = self.wadl_method.build_request_url(**args)
-            in_representation = ''
-            extra_headers = {}
-        else:
-            url = self.wadl_method.build_request_url()
-            (media_type,
-             in_representation) = self.wadl_method.build_representation(
-                **args)
-            extra_headers = { 'Content-type' : media_type }
-        response, content = self.root._browser._request(
-            url, in_representation, http_method, extra_headers=extra_headers)
-
-        if response.status == 201:
-            return self._handle_201_response(url, response, content)
-        else:
-            if http_method == 'post':
-                # The method call probably modified this resource in
-                # an unknown way. Refresh its representation.
-                self.resource.lp_refresh()
-            return self._handle_200_response(url, response, content)
-
-    def _handle_201_response(self, url, response, content):
-        """Handle the creation of a new resource by fetching it."""
-        wadl_response = self.wadl_method.response.bind(
-            HeaderDictionary(response))
-        wadl_parameter = wadl_response.get_parameter('Location')
-        wadl_resource = wadl_parameter.linked_resource
-            # Fetch a representation of the new resource.
-        response, content = self.root._browser._request(
-            wadl_resource.url)
-        # Return an instance of the appropriate launchpadlib
-        # Resource subclass.
-        return Resource._create_bound_resource(
-            self.root, wadl_resource, content, response['content-type'])
-
-    def _handle_200_response(self, url, response, content):
-        """Process the return value of an operation."""
-        content_type = response['content-type']
-        # Process the returned content, assuming we know how.
-        response_definition = self.wadl_method.response
-        representation_definition = (
-            response_definition.get_representation_definition(
-                content_type))
-
-        if representation_definition is None:
-            # The operation returned a document with nothing
-            # special about it.
-            if content_type == self.JSON_MEDIA_TYPE:
-                return simplejson.loads(content)
-            # We don't know how to process the content.
-            return content
-
-        # The operation returned a representation of some
-        # resource. Instantiate a Resource object for it.
-        document = simplejson.loads(content)
-        if "self_link" in document and "resource_type_link" in document:
-            # The operation returned an entry. Use the self_link and
-            # resource_type_link of the entry representation to build
-            # a Resource object of the appropriate type. That way this
-            # object will support all of the right named operations.
-            url = document["self_link"]
-            resource_type = self.root._wadl.get_resource_type(
-                document["resource_type_link"])
-            wadl_resource = WadlResource(self.root._wadl, url,
-                                         resource_type.tag)
-        else:
-            # The operation returned a collection. It's probably an ad
-            # hoc collection that doesn't correspond to any resource
-            # type.  Instantiate it as a resource backed by the
-            # representation type defined in the return value, instead
-            # of a resource type tag.
-            representation_definition = (
-                representation_definition.resolve_definition())
-            wadl_resource = WadlResource(
-                self.root._wadl, url, representation_definition.tag)
-
-        return Resource._create_bound_resource(
-            self.root, wadl_resource, document, content_type,
-            representation_needs_processing=False,
-            representation_definition=representation_definition)
-
-    def _get_external_param_name(self, param_name):
-        """Named operation parameter names are sent as is."""
-        return param_name
-
-
-class Entry(Resource):
-    """A class for an entry-type resource that can be updated with PATCH."""
-
-    def __init__(self, root, wadl_resource):
-        super(Entry, self).__init__(root, wadl_resource)
-        # Initialize this here in a semi-magical way so as to stop a
-        # particular infinite loop that would follow.  Setting
-        # self._dirty_attributes would call __setattr__(), which would
-        # turn around immediately and get self._dirty_attributes.  If
-        # this latter was not in the instance dictionary, that would
-        # end up calling __getattr__(), which would again reference
-        # self._dirty_attributes.  This is where the infloop would
-        # occur.  Poking this directly into self.__dict__ means that
-        # the check for self._dirty_attributes won't call __getattr__(),
-        # breaking the cycle.
-        self.__dict__['_dirty_attributes'] = {}
-        super(Entry, self).__init__(root, wadl_resource)
-
-    def __repr__(self):
-        """Return the WADL resource type and the URL to the resource."""
-        return '<%s at %s>' % (
-            URI(self.resource_type_link).fragment, self.self_link)
-
-    def __str__(self):
-        """Return the URL to the resource."""
-        return self.self_link
-
-    def __getattr__(self, name):
-        """Try to retrive a parameter of the given name."""
-        if name != '_dirty_attributes':
-            if name in self._dirty_attributes:
-                return self._dirty_attributes[name]
-        return super(Entry, self).__getattr__(name)
-
-    def __setattr__(self, name, value):
-        """Set the parameter of the given name."""
-        if not self.lp_has_parameter(name):
-            raise AttributeError("'%s' object has no attribute '%s'" %
-                                 (self.__class__.__name__, name))
-        self._dirty_attributes[name] = value
-
-    def lp_refresh(self, new_url=None):
-        """Update this resource's representation."""
-        etag = getattr(self, 'http_etag', None)
-        super(Entry, self).lp_refresh(new_url, etag)
-        self._dirty_attributes.clear()
-
-    def lp_save(self):
-        """Save changes to the entry."""
-        representation = self._transform_resources_to_links(
-            self._dirty_attributes)
-
-        # If the entry contains an ETag, set the If-Match header
-        # to that value.
-        headers = {}
-        etag = getattr(self, 'http_etag', None)
-        if etag is not None:
-            headers['If-Match'] = etag
-
-        # PATCH the new representation to the 'self' link.  It's possible that
-        # this will cause the object to be permanently moved.  Catch that
-        # exception and refresh our representation.
-        try:
-            response, content = self._root._browser.patch(
-                URI(self.self_link), representation, headers)
-        except HTTPError, error:
-            if error.response.status == 301:
-                response = error.response
-                self.lp_refresh(error.response['location'])
-            else:
-                raise
-        self._dirty_attributes.clear()
-
-        content_type = response['content-type']
-        if response.status == 209 and content_type == self.JSON_MEDIA_TYPE:
-            # The server sent back a new representation of the object.
-            # Use it in preference to the existing representation.
-            new_representation = simplejson.loads(content)
-            self._wadl_resource.representation = new_representation
-            self._wadl_resource.media_type = content_type
-
-
-class Collection(Resource):
-    """A collection-type resource that supports pagination."""
-
-    def __init__(self, root, wadl_resource):
-        """Create a collection object."""
-        super(Collection, self).__init__(root, wadl_resource)
-
-    def __len__(self):
-        """The number of items in the collection.
-
-        :return: length of the collection
-        :rtype: int
-        """
-        try:
-            return int(self.total_size)
-        except AttributeError:
-            raise TypeError('collection size is not available')
-
-    def __iter__(self):
-        """Iterate over the items in the collection.
-
-        :return: iterator
-        :rtype: sequence of `Entry`
-        """
-        self._ensure_representation()
-        current_page = self._wadl_resource.representation
-        while True:
-            for resource in self._convert_dicts_to_entries(
-                current_page.get('entries', {})):
-                yield resource
-            next_link = current_page.get('next_collection_link')
-            if next_link is None:
-                break
-            current_page = simplejson.loads(
-                self._root._browser.get(URI(next_link)))
-
-    def __getitem__(self, key):
-        """Look up a slice, or a subordinate resource by index.
-
-        To discourage situations where a launchpadlib client fetches
-        all of an enormous list, all collection slices must have a
-        definitive end point. For performance reasons, all collection
-        slices must be indexed from the start of the list rather than
-        the end.
-        """
-        if isinstance(key, slice):
-            return self._get_slice(key)
-        else:
-            # Look up a single item by its position in the list.
-            found_slice = self._get_slice(slice(key, key+1))
-            if len(found_slice) != 1:
-                raise IndexError("list index out of range")
-            return found_slice[0]
-
-    def _get_slice(self, slice):
-        """Retrieve a slice of a collection."""
-        start = slice.start or 0
-        stop = slice.stop
-
-        if start < 0:
-            raise ValueError("Collection slices must have a nonnegative "
-                             "start point.")
-        if stop < 0:
-            raise ValueError("Collection slices must have a definite, "
-                             "nonnegative end point.")
-
-        existing_representation = self._wadl_resource.representation
-        if (existing_representation is not None
-            and start < len(existing_representation['entries'])):
-            # An optimization: the first page of entries has already
-            # been loaded. This can happen if this collection is the
-            # return value of a named operation, or if the client did
-            # something like check the length of the collection.
-            #
-            # Either way, we've already made an HTTP request and
-            # gotten some entries back. The client has requested a
-            # slice that includes some of the entries we already have.
-            # In the best case, we can fulfil the slice immediately,
-            # without making another HTTP request.
-            #
-            # Even if we can't fulfil the entire slice, we can get one
-            # or more objects from the first page and then have fewer
-            # objects to retrieve from the server later. This saves us
-            # time and bandwidth, and it might let us save a whole
-            # HTTP request.
-            entry_page = existing_representation['entries']
-
-            first_page_size = len(entry_page)
-            entry_dicts = entry_page[start:stop]
-            page_url = existing_representation.get('next_collection_link')
-        else:
-            # No part of this collection has been loaded yet, or the
-            # slice starts beyond the part that has been loaded. We'll
-            # use our secret knowledge of Launchpad to set a value for
-            # the ws.start variable. That way we start reading entries
-            # from the first one we want.
-            first_page_size = None
-            entry_dicts = []
-            page_url = self._with_url_query_variable_set(
-                self._wadl_resource.url, 'ws.start', start)
-
-        desired_size = stop-start
-        more_needed = desired_size - len(entry_dicts)
-
-        # Iterate over pages until we have the correct number of entries.
-        while more_needed > 0 and page_url is not None:
-            representation = simplejson.loads(
-                self._root._browser.get(page_url))
-            current_page_entries = representation['entries']
-            entry_dicts += current_page_entries[:more_needed]
-            more_needed = desired_size - len(entry_dicts)
-
-            page_url = representation.get('next_collection_link')
-            if page_url is None:
-                # We've gotten the entire collection; there are no
-                # more entries.
-                break
-            if first_page_size is None:
-                first_page_size = len(current_page_entries)
-            if more_needed > 0 and more_needed < first_page_size:
-                # An optimization: it's likely that we need less than
-                # a full page of entries, because the number we need
-                # is less than the size of the first page we got.
-                # Instead of requesting a full-sized page, we'll
-                # request only the number of entries we think we'll
-                # need. If we're wrong, there's no problem; we'll just
-                # keep looping.
-                page_url = self._with_url_query_variable_set(
-                    page_url, 'ws.size', more_needed)
-
-        if slice.step is not None:
-            entry_dicts = entry_dicts[::slice.step]
-
-        # Convert entry_dicts into a list of Entry objects.
-        return [resource for resource
-                in self._convert_dicts_to_entries(entry_dicts)]
-
-    def _convert_dicts_to_entries(self, entries):
-        """Convert dictionaries describing entries to Entry objects.
-
-        The dictionaries come from the 'entries' field of the JSON
-        dictionary you get when you GET a page of a collection. Each
-        dictionary is the same as you'd get if you sent a GET request
-        to the corresponding entry resource. So each of these
-        dictionaries can be treated as a preprocessed representation
-        of an entry resource, and turned into an Entry instance.
-
-        :yield: A sequence of Entry instances.
-        """
-        for entry_dict in entries:
-            resource_url = entry_dict['self_link']
-            resource_type_link = entry_dict['resource_type_link']
-            wadl_application = self._wadl_resource.application
-            resource_type = wadl_application.get_resource_type(
-                resource_type_link)
-            resource = WadlResource(
-                self._wadl_resource.application, resource_url,
-                resource_type.tag)
-            yield Resource._create_bound_resource(
-                self._root, resource, entry_dict, self.JSON_MEDIA_TYPE,
-                False)
-
-    def _with_url_query_variable_set(self, url, variable, new_value):
-        """A helper method to set a query variable in a URL."""
-        uri = URI(url)
-        if uri.query is None:
-            params = {}
-        else:
-            params = cgi.parse_qs(uri.query)
-        params[variable] = str(new_value)
-        uri.query = urllib.urlencode(params, True)
-        return str(uri)
-
-
-class CollectionWithKeyBasedLookup(Collection):
-    """A collection-type resource that supports key-based lookup.
-
-    This collection can be sliced, but any single index passed into
-    __getitem__ will be treated as a custom lookup key.
-    """
-
-    def __getitem__(self, key):
-        """Look up a slice, or a subordinate resource by unique ID."""
-        if isinstance(key, slice):
-            return super(CollectionWithKeyBasedLookup, self).__getitem__(key)
-        try:
-            url = self._get_url_from_id(key)
-        except NotImplementedError:
-            raise TypeError("unsubscriptable object")
-        if url is None:
-            raise KeyError(key)
-
-        # We don't know what kind of resource this is. Even the
-        # subclass doesn't necessarily know, because some resources
-        # (the person list) are gateways to more than one kind of
-        # resource (people, and teams). The only way to know for sure
-        # is to retrieve a representation of the resource and see how
-        # the resource describes itself.
-        try:
-            representation = simplejson.loads(self._root._browser.get(url))
-        except HTTPError, error:
-            # There's no resource corresponding to the given ID.
-            if error.response.status == 404:
-                raise KeyError(key)
-            raise
-        # We know that every Launchpad resource has a 'resource_type_link'
-        # in its representation.
-        resource_type_link = representation['resource_type_link']
-        resource = WadlResource(self._root._wadl, url, resource_type_link)
-        return self._create_bound_resource(
-            self._root, resource, representation=representation,
-            representation_needs_processing=False)
-
-
-    def _get_url_from_id(self, key):
-        """Transform the unique ID of an object into its URL."""
-        raise NotImplementedError()
-
-
-class HostedFile(Resource):
-    """A resource represnting a file hosted on Launchpad's server."""
-
-    def open(self, mode='r', content_type=None, filename=None):
-        """Open the file on the server for read or write access."""
-        if mode in ('r', 'w'):
-            return HostedFileBuffer(self, mode, content_type, filename)
-        else:
-            raise ValueError("Invalid mode. Supported modes are: r, w")
-
-    def delete(self):
-        """Delete the file from the server."""
-        self._root._browser.delete(self._wadl_resource.url)
-
-    def _get_parameter_names(self, *kinds):
-        """HostedFile objects define no web service parameters."""
-        return []
-
-
-class HostedFileBuffer(StringIO):
-    """The contents of a file hosted on Launchpad's server."""
-    def __init__(self, hosted_file, mode, content_type=None, filename=None):
-        self.url = hosted_file._wadl_resource.url
-        if mode == 'r':
-            if content_type is not None:
-                raise ValueError("Files opened for read access can't "
-                                 "specify content_type.")
-            if filename is not None:
-                raise ValueError("Files opened for read access can't "
-                                 "specify filename.")
-            response, value = hosted_file._root._browser.get(
-                self.url, return_response=True)
-            content_type = response['content-type']
-            last_modified = response['last-modified']
-
-            # The Content-Location header contains the URL of the file
-            # in the Launchpad library. We happen to know that the
-            # final component of the URL is the name of the uploaded
-            # file.
-            content_location = response['content-location']
-            path = urlparse(content_location)[2]
-            filename = urllib.unquote(path.split("/")[-1])
-        elif mode == 'w':
-            value = ''
-            if content_type is None:
-                raise ValueError("Files opened for write access must "
-                                 "specify content_type.")
-            if filename is None:
-                raise ValueError("Files opened for write access must "
-                                 "specify filename.")
-            last_modified = None
-        else:
-            raise ValueError("Invalid mode. Supported modes are: r, w")
-
-        self.hosted_file = hosted_file
-        self.mode = mode
-        self.content_type = content_type
-        self.filename = filename
-        self.last_modified = last_modified
-        StringIO.__init__(self, value)
-
-    def close(self):
-        if self.mode == 'w':
-            disposition = 'attachment; filename="%s"' % self.filename
-            self.hosted_file._root._browser.put(
-                self.url, self.getvalue(),
-                self.content_type, {'Content-Disposition' : disposition})
-        StringIO.close(self)
-
-
-class PersonSet(CollectionWithKeyBasedLookup):
-    """A custom subclass capable of person lookup by username."""
-
-    def _get_url_from_id(self, key):
-        """Transform a username into the URL to a person resource."""
-        return str(self._root._root_uri.ensureSlash()) + '~' + str(key)
-
-
-class BugSet(CollectionWithKeyBasedLookup):
-    """A custom subclass capable of bug lookup by bug ID."""
-
-    def _get_url_from_id(self, key):
-        """Transform a bug ID into the URL to a bug resource."""
-        return str(self._root._root_uri.ensureSlash()) + 'bugs/' + str(key)
-
-
-class PillarSet(CollectionWithKeyBasedLookup):
-    """A custom subclass capable of lookup by pillar name.
-
-    Projects, project groups, and distributions are all pillars.
-    """
-
-    def _get_url_from_id(self, key):
-        """Transform a project name into the URL to a project resource."""
-        return str(self._root._root_uri.ensureSlash()) + str(key)
-
-
-# A mapping of resource type IDs to the client-side classes that handle
-# those resource types.
-RESOURCE_TYPE_CLASSES = {
-    'bugs': BugSet,
-    'distributions': PillarSet,
-    'HostedFile': HostedFile,
-    'people': PersonSet,
-    'project_groups': PillarSet,
-    'projects': PillarSet,
-    }

=== added directory 'src/launchpadlib/restfulclient'
=== added file 'src/launchpadlib/restfulclient/__init__.py'
--- src/launchpadlib/restfulclient/__init__.py	1970-01-01 00:00:00 +0000
+++ src/launchpadlib/restfulclient/__init__.py	2009-03-26 18:40:36 +0000
@@ -0,0 +1,19 @@
+# Copyright 2008 Canonical Ltd.
+
+# This file is part of lazr.restfulclient.
+#
+# lazr.restfulclient is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# lazr.restfulclient is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with lazr.restfulclient.  If not, see
+# <http://www.gnu.org/licenses/>.
+
+__version__ = '1.0'

=== added file 'src/launchpadlib/restfulclient/_browser.py'
--- src/launchpadlib/restfulclient/_browser.py	1970-01-01 00:00:00 +0000
+++ src/launchpadlib/restfulclient/_browser.py	2009-03-26 19:26:13 +0000
@@ -0,0 +1,258 @@
+# Copyright 2008 Canonical Ltd.
+
+# This file is part of lazr.restfulclient.
+#
+# lazr.restfulclient is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# lazr.restfulclient is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with lazr.restfulclient.  If not, see
+# <http://www.gnu.org/licenses/>.
+
+"""Browser object to make requests of lazr.restful web services.
+
+The `Browser` class does some massage of HTTP requests and responses,
+and handles custom caches. It is not part of the public
+lazr.restfulclient API. (But maybe it should be?)
+"""
+
+__metaclass__ = type
+__all__ = [
+    'Browser',
+    'RestfulHttp',
+    ]
+
+
+import atexit
+import gzip
+import shutil
+import tempfile
+from httplib2 import (
+    FailedToDecompressContent, FileCache, Http, safename, urlnorm)
+import simplejson
+from cStringIO import StringIO
+import zlib
+
+from urllib import urlencode
+from wadllib.application import Application
+from lazr.uri import URI
+from errors import HTTPError
+from _json import DatetimeJSONEncoder
+
+# A drop-in replacement for httplib2's _decompressContent, which looks
+# in the Transfer-Encoding header instead of in Content-Encoding.
+def _decompressContent(response, new_content):
+    content = new_content
+    try:
+        encoding = response.get('transfer-encoding', None)
+        if encoding in ['gzip', 'deflate']:
+            if encoding == 'gzip':
+                content = gzip.GzipFile(
+                    fileobj=StringIO.StringIO(new_content)).read()
+            if encoding == 'deflate':
+                content = zlib.decompress(content)
+            response['content-length'] = str(len(content))
+            del response['transfer-encoding']
+    except IOError:
+        content = ""
+        raise FailedToDecompressContent(
+            ("Content purported to be compressed with %s but failed "
+             "to decompress." % response.get('transfer-encoding')),
+            response, content)
+    return content
+
+
+class RestfulHttp(Http):
+    """An Http subclass with some custom behavior.
+
+    This Http client uses the TE header instead of the Accept-Encoding
+    header to ask for compressed representations. It also knows how to
+    react when its cache is a MultipleRepresentationCache.
+    """
+
+    def __init__(self, credentials, cache=None, timeout=None,
+                 proxy_info=None):
+        super(RestfulHttp, self).__init__(cache, timeout, proxy_info)
+        # The credentials are not used in this class, but you can
+        # use them in a subclass.
+        self.restful_credentials = credentials
+
+
+    def _request(self, conn, host, absolute_uri, request_uri, method, body,
+                 headers, redirections, cachekey):
+        """Manipulate Transfer-Encoding header before sending the request.
+
+        httplib2 asks for compressed representations in
+        Accept-Encoding.  But a different content-encoding means a
+        different ETag, which can cause problems later when we make
+        a conditional request. We don't want to treat a
+        representation differently based on whether or not we asked
+        for a compressed version of it.
+
+        So we move the compression request from Accept-Encoding to
+        TE. Transfer-encoding compression can be handled
+        transparently, without affecting the ETag.
+        """
+        if 'accept-encoding' in headers:
+            headers['te'] = 'deflate, gzip'
+            del headers['accept-encoding']
+        return super(RestfulHttp, self)._request(
+            conn, host, absolute_uri, request_uri, method, body, headers,
+            redirections, cachekey)
+
+    def _conn_request(self, conn, request_uri, method, body, headers):
+        """Decompress content using our version of _decompressContent."""
+        response, content = super(RestfulHttp, self)._conn_request(
+            conn, request_uri, method, body, headers)
+        # Decompress the response, if it was compressed.
+        if method != "HEAD":
+            content = _decompressContent(response, content)
+        return (response, content)
+
+    def _getCachedHeader(self, uri, header):
+        """Retrieve a cached value for an HTTP header."""
+        if isinstance(self.cache, MultipleRepresentationCache):
+            return self.cache._getCachedHeader(uri, header)
+        return None
+
+
+class MultipleRepresentationCache(FileCache):
+    """A cache that can hold different representations of the same resource.
+
+    If a resource has two representations with two media types,
+    FileCache will only store the most recently fetched
+    representation. This cache can keep track of multiple
+    representations of the same resource.
+
+    This class works on the assumption that outside calling code sets
+    an instance's request_media_type attribute to the value of the
+    'Accept' header before initiating the request.
+
+    This class is very much not thread-safe, but FileCache isn't
+    thread-safe anyway.
+    """
+    def __init__(self, cache):
+        """Tell FileCache to call append_media_type when generating keys."""
+        super(MultipleRepresentationCache, self).__init__(
+            cache, self.append_media_type)
+        self.request_media_type = None
+
+    def append_media_type(self, key):
+        """Append the request media type to the cache key.
+
+        This ensures that representations of the same resource will be
+        cached separately, so long as they're served as different
+        media types.
+        """
+        if self.request_media_type is not None:
+            key = key + '-' + self.request_media_type
+        return safename(key)
+
+
+    def _getCachedHeader(self, uri, header):
+        """Retrieve a cached value for an HTTP header."""
+        (scheme, authority, request_uri, cachekey) = urlnorm(uri)
+        cached_value = self.get(cachekey)
+        header_start = header + ':'
+        if cached_value is not None:
+            for line in StringIO(cached_value):
+                if line.startswith(header_start):
+                    return line[len(header_start):].strip()
+        return None
+
+
+class Browser:
+    """A class for making calls to lazr.restful web services."""
+
+    def __init__(self, service_root, credentials, cache=None, timeout=None,
+                 proxy_info=None):
+        """Initialize, possibly creating a cache.
+
+        If no cache is provided, a temporary directory will be used as
+        a cache. The temporary directory will be automatically removed
+        when the Python process exits.
+        """
+        if cache is None:
+            cache = tempfile.mkdtemp()
+            atexit.register(shutil.rmtree, cache)
+        if isinstance(cache, str):
+            cache = MultipleRepresentationCache(cache)
+        self._connection = service_root.httpFactory(
+            credentials, cache, timeout, proxy_info)
+
+    def _request(self, url, data=None, method='GET',
+                 media_type='application/json', extra_headers=None):
+        """Create an authenticated request object."""
+        # Add extra headers for the request.
+        headers = {'Accept' : media_type}
+        if isinstance(self._connection.cache, MultipleRepresentationCache):
+            self._connection.cache.request_media_type = media_type
+        if extra_headers is not None:
+            headers.update(extra_headers)
+        # Make the request.
+        response, content = self._connection.request(
+            str(url), method=method, body=data, headers=headers)
+        # Turn non-2xx responses into exceptions.
+        if response.status // 100 != 2:
+            raise HTTPError(response, content)
+        return response, content
+
+    def get(self, resource_or_uri, headers=None, return_response=False):
+        """GET a representation of the given resource or URI."""
+        if isinstance(resource_or_uri, (basestring, URI)):
+            url = resource_or_uri
+        else:
+            method = resource_or_uri.get_method('get')
+            url = method.build_request_url()
+        response, content = self._request(url, extra_headers=headers)
+        if return_response:
+            return (response, content)
+        return content
+
+    def get_wadl_application(self, url):
+        """GET a WADL representation of the resource at the requested url."""
+        response, content = self._request(
+            url, media_type='application/vd.sun.wadl+xml')
+        return Application(str(url), content)
+
+    def post(self, url, method_name, **kws):
+        """POST a request to the web service."""
+        kws['ws.op'] = method_name
+        data = urlencode(kws)
+        return self._request(url, data, 'POST')
+
+    def put(self, url, representation, media_type, headers=None):
+        """PUT the given representation to the URL."""
+        extra_headers = {'Content-Type': media_type}
+        if headers is not None:
+            extra_headers.update(headers)
+        return self._request(
+            url, representation, 'PUT', extra_headers=extra_headers)
+
+    def delete(self, url):
+        """DELETE the resource at the given URL."""
+        self._request(url, method='DELETE')
+
+    def patch(self, url, representation, headers=None):
+        """PATCH the object at url with the updated representation."""
+        extra_headers = {'Content-Type': 'application/json'}
+        if headers is not None:
+            extra_headers.update(headers)
+        # httplib2 doesn't know about the PATCH method, so we need to
+        # do some work ourselves. Pull any cached value of "ETag" out
+        # and use it as the value for "If-Match".
+        cached_etag = self._connection._getCachedHeader(str(url), 'etag')
+        if cached_etag is not None and not self._connection.ignore_etag:
+            # http://www.w3.org/1999/04/Editing/
+            headers['If-Match'] = cached_etag
+
+        return self._request(
+            url, simplejson.dumps(representation, cls=DatetimeJSONEncoder),
+            'PATCH', extra_headers=extra_headers)

=== renamed file 'src/launchpadlib/_json.py' => 'src/launchpadlib/restfulclient/_json.py'
--- src/launchpadlib/_json.py	2009-03-20 20:46:06 +0000
+++ src/launchpadlib/restfulclient/_json.py	2009-03-26 18:40:36 +0000
@@ -1,18 +1,20 @@
 # Copyright 2009 Canonical Ltd.
 
-# This file is part of launchpadlib.
-#
-# launchpadlib is free software: you can redistribute it and/or modify it
-# under the terms of the GNU Lesser General Public License as published by the
-# Free Software Foundation, version 3 of the License.
-#
-# launchpadlib is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
-# for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with launchpadlib. If not, see <http://www.gnu.org/licenses/>.
+# This file is part of lazr.restfulclient.
+#
+# lazr.restfulclient is free software: you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public License
+# as published by the Free Software Foundation, version 3 of the
+# License.
+#
+# lazr.restfulclient is distributed in the hope that it will be
+# useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with lazr.restfulclient. If not, see
+# <http://www.gnu.org/licenses/>.
 
 """Classes for working with JSON."""
 
@@ -22,6 +24,7 @@
 import datetime
 import simplejson
 
+
 class DatetimeJSONEncoder(simplejson.JSONEncoder):
     """A JSON encoder that understands datetime objects.
 

=== added file 'src/launchpadlib/restfulclient/errors.py'
--- src/launchpadlib/restfulclient/errors.py	1970-01-01 00:00:00 +0000
+++ src/launchpadlib/restfulclient/errors.py	2009-03-26 19:08:48 +0000
@@ -0,0 +1,65 @@
+# Copyright 2008 Canonical Ltd.
+
+# This file is part of lazr.restfulclient.
+#
+# lazr.restfulclient is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# lazr.restfulclient is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with lazr.restfulclient.  If not, see
+# <http://www.gnu.org/licenses/>.
+
+"""lazr.restfulclient errors."""
+
+__metaclass__ = type
+__all__ = [
+    'CredentialsError',
+    'CredentialsFileError',
+    'HTTPError',
+    'RestfulError',
+    'ResponseError',
+    'UnexpectedResponseError',
+    ]
+
+
+class RestfulError(Exception):
+    """Base error for the lazr.restfulclient API library."""
+
+
+class CredentialsError(RestfulError):
+    """Base credentials/authentication error."""
+
+
+class CredentialsFileError(CredentialsError):
+    """Error in credentials file."""
+
+
+class ResponseError(RestfulError):
+    """Error in response."""
+
+    def __init__(self, response, content):
+        RestfulError.__init__(self)
+        self.response = response
+        self.content = content
+
+
+class UnexpectedResponseError(ResponseError):
+    """An unexpected response was received."""
+
+    def __str__(self):
+        return '%s: %s' % (self.response.status, self.response.reason)
+
+
+class HTTPError(ResponseError):
+    """An HTTP non-2xx response code was received."""
+
+    def __str__(self):
+        return 'HTTP Error %s: %s' % (
+            self.response.status, self.response.reason)

=== added file 'src/launchpadlib/restfulclient/resource.py'
--- src/launchpadlib/restfulclient/resource.py	1970-01-01 00:00:00 +0000
+++ src/launchpadlib/restfulclient/resource.py	2009-03-26 18:40:36 +0000
@@ -0,0 +1,846 @@
+# Copyright 2008 Canonical Ltd.
+
+# This file is part of lazr.restfulclient.
+#
+# lazr.restfulclient is free software: you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public License
+# as published by the Free Software Foundation, either version 3 of
+# the License, or (at your option) any later version.
+#
+# lazr.restfulclient is distributed in the hope that it will be
+# useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with lazr.restfulclient.  If not, see
+# <http://www.gnu.org/licenses/>.
+
+"""Common support for web service resources."""
+
+__metaclass__ = type
+__all__ = [
+    'Collection',
+    'Entry',
+    'NamedOperation',
+    'Resource',
+    ]
+
+
+import cgi
+import simplejson
+from StringIO import StringIO
+import urllib
+from urlparse import urlparse
+
+from lazr.uri import URI
+from wadllib.application import Resource as WadlResource
+from _browser import Browser, RestfulHttp
+from _json import DatetimeJSONEncoder
+from errors import HTTPError
+
+
+class HeaderDictionary:
+    """A dictionary that bridges httplib2's and wadllib's expectations.
+
+    httplib2 expects all header dictionary access to give lowercase
+    header names. wadllib expects to access the header exactly as it's
+    specified in the WADL file, which means the official HTTP header name.
+
+    This class transforms keys to lowercase before doing a lookup on
+    the underlying dictionary. That way wadllib can pass in the
+    official header name and httplib2 will get the lowercased name.
+    """
+    def __init__(self, wrapped_dictionary):
+        self.wrapped_dictionary = wrapped_dictionary
+
+    def get(self, key, default=None):
+        """Retrieve a value, converting the key to lowercase."""
+        return self.wrapped_dictionary.get(key.lower())
+
+    def __getitem__(self, key):
+        """Retrieve a value, converting the key to lowercase."""
+        missing = object()
+        value = self.get(key, missing)
+        if value is missing:
+            raise KeyError(key)
+        return value
+
+
+class RestfulBase:
+    """Base class for classes that know about lazr.restful services."""
+
+    JSON_MEDIA_TYPE = 'application/json'
+
+    def _transform_resources_to_links(self, dictionary):
+        new_dictionary = {}
+        for key, value in dictionary.items():
+            if isinstance(value, Resource):
+                value = value.self_link
+            new_dictionary[self._get_external_param_name(key)] = value
+        return new_dictionary
+
+    def _get_external_param_name(self, param_name):
+        """Turn a lazr.restful name into something to be sent over HTTP.
+
+        For resources this may involve sticking '_link' or
+        '_collection_link' on the end of the parameter name. For
+        arguments to named operations, the parameter name is returned
+        as is.
+        """
+        return param_name
+
+
+class Resource(RestfulBase):
+    """Base class for lazr.restful HTTP resources."""
+
+    def __init__(self, root, wadl_resource):
+        """Initialize with respect to a wadllib Resource object."""
+        if root is None:
+            # This _is_ the root.
+            root = self
+        # These values need to be put directly into __dict__ to avoid
+        # calling __setattr__, which would cause an infinite recursion.
+        self.__dict__['_root'] = root
+        self.__dict__['_wadl_resource'] = wadl_resource
+
+    FIND_COLLECTIONS = object()
+    FIND_ENTRIES = object()
+    FIND_ATTRIBUTES = object()
+
+    @property
+    def lp_collections(self):
+        """Name the collections this resource links to."""
+        return self._get_parameter_names(self.FIND_COLLECTIONS)
+
+    @property
+    def lp_entries(self):
+        """Name the entries this resource links to."""
+        return self._get_parameter_names(self.FIND_ENTRIES)
+
+    @property
+    def lp_attributes(self):
+        """Name this resource's scalar attributes."""
+        return self._get_parameter_names(self.FIND_ATTRIBUTES)
+
+    @property
+    def lp_operations(self):
+        """Name all of this resource's custom operations."""
+        # This library distinguishes between named operations by the
+        # value they give for ws.op, not by their WADL names or IDs.
+        names = []
+        form_encoded_type = 'application/x-www-form-urlencoded'
+        for method in self._wadl_resource.method_iter:
+            name = method.name.lower()
+            if name == 'get':
+                params = method.request.params(['query', 'plain'])
+            elif name == 'post':
+                definition = method.request.representation_definition(
+                    form_encoded_type).resolve_definition()
+                params = definition.params(self._wadl_resource)
+            for param in params:
+                if param.name == 'ws.op':
+                    names.append(param.fixed_value)
+                    break
+        return names
+
+    @property
+    def __members__(self):
+        """A hook into dir() that returns web service-derived members."""
+        return self._get_parameter_names(
+            self.FIND_COLLECTIONS, self.FIND_ENTRIES, self.FIND_ATTRIBUTES)
+
+    __methods__ = lp_operations
+
+    def _get_parameter_names(self, *kinds):
+        """Retrieve some subset of the resource's parameters."""
+        names = []
+        for name in self._wadl_resource.parameter_names(
+            self.JSON_MEDIA_TYPE):
+            if name.endswith('_collection_link'):
+                if self.FIND_COLLECTIONS in kinds:
+                    names.append(name[:-16])
+            elif (name.endswith('_link')
+                  and name not in ('self_link', 'resource_type_link')):
+                # lazr.restful_obj.self will work, but is never
+                # necessary. lazr.restful_obj.resource_type is also
+                # unneccessary, and won't work anyway because
+                # resource_type_link points to a WADL description,
+                # not a normal lazr.restful resource.
+                if self.FIND_ENTRIES in kinds:
+                    names.append(name[:-5])
+            elif self.FIND_ATTRIBUTES in kinds:
+                names.append(name)
+        return names
+
+    def lp_has_parameter(self, param_name):
+        """Does this resource have a parameter with the given name?"""
+        return self._get_external_param_name(param_name) is not None
+
+    def lp_get_parameter(self, param_name):
+        """Get the value of one of the resource's parameters.
+
+        :return: A scalar value if the parameter is not a link. A new
+                 Resource object, whose resource is bound to a
+                 representation, if the parameter is a link.
+        """
+        self._ensure_representation()
+        for suffix in ['_link', '_collection_link']:
+            param = self._wadl_resource.get_parameter(
+                param_name + suffix, self.JSON_MEDIA_TYPE)
+            if param is not None:
+                if param.get_value() is None:
+                    # This parameter is a link to another object, but
+                    # there's no other object. Return None rather than
+                    # chasing down the nonexistent other object.
+                    return None
+                linked_resource = param.linked_resource
+                return self._create_bound_resource(
+                    self._root, linked_resource, param_name=param.name)
+        param = self._wadl_resource.get_parameter(param_name)
+        if param is None:
+            raise KeyError("No such parameter: %s" % param_name)
+        return param.get_value()
+
+    def lp_get_named_operation(self, operation_name):
+        """Get a custom operation with the given name.
+
+        :return: A NamedOperation instance that can be called with
+                 appropriate arguments to invoke the operation.
+        """
+        params = { 'ws.op' : operation_name }
+        method = self._wadl_resource.get_method('get', query_params=params)
+        if method is None:
+            method = self._wadl_resource.get_method(
+                'post', representation_params=params)
+        if method is None:
+            raise KeyError("No operation with name: %s" % operation_name)
+        return NamedOperation(self._root, self, method)
+
+    @classmethod
+    def _create_bound_resource(
+        cls, root, resource, representation=None,
+        representation_media_type='application/json',
+        representation_needs_processing=True, representation_definition=None,
+        param_name=None):
+        """Create a lazr.restful Resource subclass from a wadllib Resource.
+
+        :param resource: The wadllib Resource to wrap.
+        :param representation: A previously fetched representation of
+            this resource, to be reused. If not provided, this method
+            will act just like the Resource constructor.
+        :param representation_media_type: The media type of any previously
+            fetched representation.
+        :param representation_needs_processing: Set to False if the
+            'representation' parameter should be used as
+            is.
+        :param representation_definition: A wadllib
+            RepresentationDefinition object describing the structure
+            of this representation. Used in cases when the representation
+            isn't the result of sending a standard GET to the resource.
+        :param param_name: The name of the link that was followed to get
+            to this resource.
+        :return: An instance of the appropriate lazr.restful Resource
+            subclass.
+        """
+        # We happen to know that all lazr.restful resource types are
+        # defined in a single document. Turn the resource's type_url
+        # into an anchor into that document: this is its resource
+        # type. Then look up a client-side class that corresponds to
+        # the resource type.
+        type_url = resource.type_url
+        resource_type = urlparse(type_url)[-1]
+        default = Entry
+        if (type_url.endswith('-page')
+            or (param_name is not None
+                and param_name.endswith('_collection_link'))):
+            default = Collection
+        r_class = root.RESOURCE_TYPE_CLASSES.get(resource_type, default)
+        if representation is not None:
+            # We've been given a representation. Bind the resource
+            # immediately.
+            resource = resource.bind(
+                representation, representation_media_type,
+                representation_needs_processing,
+                representation_definition=representation_definition)
+        else:
+            # We'll fetch a representation and bind the resource when
+            # necessary.
+            pass
+        return r_class(root, resource)
+
+    def lp_refresh(self, new_url=None, etag=None):
+        """Update this resource's representation."""
+        if new_url is not None:
+            self._wadl_resource._url = new_url
+        headers = {}
+        if etag is not None:
+            headers['If-None-Match'] = etag
+        try:
+            representation = self._root._browser.get(
+                self._wadl_resource, headers=headers)
+        except HTTPError, e:
+            if e.response['status'] == '304':
+                # The entry wasn't modified. No need to do anything.
+                return
+            else:
+                raise e
+        # __setattr__ assumes we're setting an attribute of the resource,
+        # so we manipulate __dict__ directly.
+        self.__dict__['_wadl_resource'] = self._wadl_resource.bind(
+            representation, self.JSON_MEDIA_TYPE)
+
+    def __getattr__(self, attr):
+        """Try to retrive a named operation or parameter of the given name."""
+        try:
+            return self.lp_get_parameter(attr)
+        except KeyError:
+            pass
+        try:
+            return self.lp_get_named_operation(attr)
+        except KeyError:
+            raise AttributeError("'%s' object has no attribute '%s'"
+                                 % (self.__class__.__name__, attr))
+
+    def _get_external_param_name(self, param_name):
+        """What's this parameter's name in the underlying representation?"""
+        for suffix in ['_link', '_collection_link', '']:
+            name = param_name + suffix
+            if self._wadl_resource.get_parameter(name):
+                return name
+        return None
+
+    def _ensure_representation(self):
+        """Make sure this resource has a representation fetched."""
+        if self._wadl_resource.representation is None:
+            # Get a representation of the linked resource.
+            representation = self._root._browser.get(self._wadl_resource)
+            self.__dict__['_wadl_resource'] = self._wadl_resource.bind(
+                representation, self.JSON_MEDIA_TYPE)
+
+
+class HostedFile(Resource):
+    """A resource representing a file managed by a lazr.restful service."""
+
+    def open(self, mode='r', content_type=None, filename=None):
+        """Open the file on the server for read or write access."""
+        if mode in ('r', 'w'):
+            return HostedFileBuffer(self, mode, content_type, filename)
+        else:
+            raise ValueError("Invalid mode. Supported modes are: r, w")
+
+    def delete(self):
+        """Delete the file from the server."""
+        self._root._browser.delete(self._wadl_resource.url)
+
+    def _get_parameter_names(self, *kinds):
+        """HostedFile objects define no web service parameters."""
+        return []
+
+
+class ServiceRoot(Resource):
+    """Entry point to the service. Subclass this for a service-specific client.
+
+    :ivar credentials: The credentials instance used to access Launchpad.
+    """
+
+    # Custom subclasses of Entry or Collection to use when
+    # instantiating resources of a certain WADL type.
+    RESOURCE_TYPE_CLASSES = {'HostedFile': HostedFile}
+
+    def __init__(self, credentials, service_root, cache=None,
+                 timeout=None, proxy_info=None):
+        """Root access to a lazr.restful API.
+
+        :param credentials: The credentials used to access the service.
+        :param service_root: The URL to the root of the web service.
+        :type service_root: string
+        """
+        self._root_uri = URI(service_root)
+        self.credentials = credentials
+        # Get the WADL definition.
+        self._browser = Browser(
+            self, self.credentials, cache, timeout, proxy_info)
+        self._wadl = self._browser.get_wadl_application(self._root_uri)
+
+        # Get the root resource.
+        root_resource = self._wadl.get_resource_by_path('')
+        bound_root = root_resource.bind(
+            self._browser.get(root_resource), 'application/json')
+        super(ServiceRoot, self).__init__(None, bound_root)
+
+    def httpFactory(self, credentials, cache, timeout, proxy_info):
+        return RestfulHttp(credentials, cache, timeout, proxy_info)
+
+    def load(self, url):
+        """Load a resource given its URL."""
+        document = self._browser.get(url)
+        try:
+            representation = simplejson.loads(document)
+        except ValueError:
+            raise ValueError("%s doesn't serve a JSON document." % url)
+        type_link = representation.get("resource_type_link")
+        if type_link is None:
+            raise ValueError("Couldn't determine the resource type of %s."
+                             % url)
+        resource_type = self._root._wadl.get_resource_type(type_link)
+        wadl_resource = WadlResource(self._root._wadl, url, resource_type.tag)
+        return self._create_bound_resource(
+            self._root, wadl_resource, representation, 'application/json',
+            representation_needs_processing=False)
+
+
+class NamedOperation(RestfulBase):
+    """A class for a named operation to be invoked with GET or POST."""
+
+    def __init__(self, root, resource, wadl_method):
+        """Initialize with respect to a WADL Method object"""
+        self.root = root
+        self.resource = resource
+        self.wadl_method = wadl_method
+
+    def __call__(self, *args, **kwargs):
+        """Invoke the method and process the result."""
+        if len(args) > 0:
+            raise TypeError('Method must be called with keyword args.')
+        http_method = self.wadl_method.name
+        args = self._transform_resources_to_links(kwargs)
+        for key, value in args.items():
+            args[key] = simplejson.dumps(value, cls=DatetimeJSONEncoder)
+        if http_method in ('get', 'head', 'delete'):
+            url = self.wadl_method.build_request_url(**args)
+            in_representation = ''
+            extra_headers = {}
+        else:
+            url = self.wadl_method.build_request_url()
+            (media_type,
+             in_representation) = self.wadl_method.build_representation(
+                **args)
+            extra_headers = { 'Content-type' : media_type }
+        response, content = self.root._browser._request(
+            url, in_representation, http_method, extra_headers=extra_headers)
+
+        if response.status == 201:
+            return self._handle_201_response(url, response, content)
+        else:
+            if http_method == 'post':
+                # The method call probably modified this resource in
+                # an unknown way. Refresh its representation.
+                self.resource.lp_refresh()
+            return self._handle_200_response(url, response, content)
+
+    def _handle_201_response(self, url, response, content):
+        """Handle the creation of a new resource by fetching it."""
+        wadl_response = self.wadl_method.response.bind(
+            HeaderDictionary(response))
+        wadl_parameter = wadl_response.get_parameter('Location')
+        wadl_resource = wadl_parameter.linked_resource
+            # Fetch a representation of the new resource.
+        response, content = self.root._browser._request(
+            wadl_resource.url)
+        # Return an instance of the appropriate lazr.restful
+        # Resource subclass.
+        return Resource._create_bound_resource(
+            self.root, wadl_resource, content, response['content-type'])
+
+    def _handle_200_response(self, url, response, content):
+        """Process the return value of an operation."""
+        content_type = response['content-type']
+        # Process the returned content, assuming we know how.
+        response_definition = self.wadl_method.response
+        representation_definition = (
+            response_definition.get_representation_definition(
+                content_type))
+
+        if representation_definition is None:
+            # The operation returned a document with nothing
+            # special about it.
+            if content_type == self.JSON_MEDIA_TYPE:
+                return simplejson.loads(content)
+            # We don't know how to process the content.
+            return content
+
+        # The operation returned a representation of some
+        # resource. Instantiate a Resource object for it.
+        document = simplejson.loads(content)
+        if "self_link" in document and "resource_type_link" in document:
+            # The operation returned an entry. Use the self_link and
+            # resource_type_link of the entry representation to build
+            # a Resource object of the appropriate type. That way this
+            # object will support all of the right named operations.
+            url = document["self_link"]
+            resource_type = self.root._wadl.get_resource_type(
+                document["resource_type_link"])
+            wadl_resource = WadlResource(self.root._wadl, url,
+                                         resource_type.tag)
+        else:
+            # The operation returned a collection. It's probably an ad
+            # hoc collection that doesn't correspond to any resource
+            # type.  Instantiate it as a resource backed by the
+            # representation type defined in the return value, instead
+            # of a resource type tag.
+            representation_definition = (
+                representation_definition.resolve_definition())
+            wadl_resource = WadlResource(
+                self.root._wadl, url, representation_definition.tag)
+
+        return Resource._create_bound_resource(
+            self.root, wadl_resource, document, content_type,
+            representation_needs_processing=False,
+            representation_definition=representation_definition)
+
+    def _get_external_param_name(self, param_name):
+        """Named operation parameter names are sent as is."""
+        return param_name
+
+
+class Entry(Resource):
+    """A class for an entry-type resource that can be updated with PATCH."""
+
+    def __init__(self, root, wadl_resource):
+        super(Entry, self).__init__(root, wadl_resource)
+        # Initialize this here in a semi-magical way so as to stop a
+        # particular infinite loop that would follow.  Setting
+        # self._dirty_attributes would call __setattr__(), which would
+        # turn around immediately and get self._dirty_attributes.  If
+        # this latter was not in the instance dictionary, that would
+        # end up calling __getattr__(), which would again reference
+        # self._dirty_attributes.  This is where the infloop would
+        # occur.  Poking this directly into self.__dict__ means that
+        # the check for self._dirty_attributes won't call __getattr__(),
+        # breaking the cycle.
+        self.__dict__['_dirty_attributes'] = {}
+        super(Entry, self).__init__(root, wadl_resource)
+
+    def __repr__(self):
+        """Return the WADL resource type and the URL to the resource."""
+        return '<%s at %s>' % (
+            URI(self.resource_type_link).fragment, self.self_link)
+
+    def __str__(self):
+        """Return the URL to the resource."""
+        return self.self_link
+
+    def __getattr__(self, name):
+        """Try to retrive a parameter of the given name."""
+        if name != '_dirty_attributes':
+            if name in self._dirty_attributes:
+                return self._dirty_attributes[name]
+        return super(Entry, self).__getattr__(name)
+
+    def __setattr__(self, name, value):
+        """Set the parameter of the given name."""
+        if not self.lp_has_parameter(name):
+            raise AttributeError("'%s' object has no attribute '%s'" %
+                                 (self.__class__.__name__, name))
+        self._dirty_attributes[name] = value
+
+    def lp_refresh(self, new_url=None):
+        """Update this resource's representation."""
+        etag = getattr(self, 'http_etag', None)
+        super(Entry, self).lp_refresh(new_url, etag)
+        self._dirty_attributes.clear()
+
+    def lp_save(self):
+        """Save changes to the entry."""
+        representation = self._transform_resources_to_links(
+            self._dirty_attributes)
+
+        # If the entry contains an ETag, set the If-Match header
+        # to that value.
+        headers = {}
+        etag = getattr(self, 'http_etag', None)
+        if etag is not None:
+            headers['If-Match'] = etag
+
+        # PATCH the new representation to the 'self' link.  It's possible that
+        # this will cause the object to be permanently moved.  Catch that
+        # exception and refresh our representation.
+        try:
+            response, content = self._root._browser.patch(
+                URI(self.self_link), representation, headers)
+        except HTTPError, error:
+            if error.response.status == 301:
+                response = error.response
+                self.lp_refresh(error.response['location'])
+            else:
+                raise
+        self._dirty_attributes.clear()
+
+        content_type = response['content-type']
+        if response.status == 209 and content_type == self.JSON_MEDIA_TYPE:
+            # The server sent back a new representation of the object.
+            # Use it in preference to the existing representation.
+            new_representation = simplejson.loads(content)
+            self._wadl_resource.representation = new_representation
+            self._wadl_resource.media_type = content_type
+
+
+class Collection(Resource):
+    """A collection-type resource that supports pagination."""
+
+    def __init__(self, root, wadl_resource):
+        """Create a collection object."""
+        super(Collection, self).__init__(root, wadl_resource)
+
+    def __len__(self):
+        """The number of items in the collection.
+
+        :return: length of the collection
+        :rtype: int
+        """
+        try:
+            return int(self.total_size)
+        except AttributeError:
+            raise TypeError('collection size is not available')
+
+    def __iter__(self):
+        """Iterate over the items in the collection.
+
+        :return: iterator
+        :rtype: sequence of `Entry`
+        """
+        self._ensure_representation()
+        current_page = self._wadl_resource.representation
+        while True:
+            for resource in self._convert_dicts_to_entries(
+                current_page.get('entries', {})):
+                yield resource
+            next_link = current_page.get('next_collection_link')
+            if next_link is None:
+                break
+            current_page = simplejson.loads(
+                self._root._browser.get(URI(next_link)))
+
+    def __getitem__(self, key):
+        """Look up a slice, or a subordinate resource by index.
+
+        To discourage situations where a lazr.restful client fetches
+        all of an enormous list, all collection slices must have a
+        definitive end point. For performance reasons, all collection
+        slices must be indexed from the start of the list rather than
+        the end.
+        """
+        if isinstance(key, slice):
+            return self._get_slice(key)
+        else:
+            # Look up a single item by its position in the list.
+            found_slice = self._get_slice(slice(key, key+1))
+            if len(found_slice) != 1:
+                raise IndexError("list index out of range")
+            return found_slice[0]
+
+    def _get_slice(self, slice):
+        """Retrieve a slice of a collection."""
+        start = slice.start or 0
+        stop = slice.stop
+
+        if start < 0:
+            raise ValueError("Collection slices must have a nonnegative "
+                             "start point.")
+        if stop < 0:
+            raise ValueError("Collection slices must have a definite, "
+                             "nonnegative end point.")
+
+        existing_representation = self._wadl_resource.representation
+        if (existing_representation is not None
+            and start < len(existing_representation['entries'])):
+            # An optimization: the first page of entries has already
+            # been loaded. This can happen if this collection is the
+            # return value of a named operation, or if the client did
+            # something like check the length of the collection.
+            #
+            # Either way, we've already made an HTTP request and
+            # gotten some entries back. The client has requested a
+            # slice that includes some of the entries we already have.
+            # In the best case, we can fulfil the slice immediately,
+            # without making another HTTP request.
+            #
+            # Even if we can't fulfil the entire slice, we can get one
+            # or more objects from the first page and then have fewer
+            # objects to retrieve from the server later. This saves us
+            # time and bandwidth, and it might let us save a whole
+            # HTTP request.
+            entry_page = existing_representation['entries']
+
+            first_page_size = len(entry_page)
+            entry_dicts = entry_page[start:stop]
+            page_url = existing_representation.get('next_collection_link')
+        else:
+            # No part of this collection has been loaded yet, or the
+            # slice starts beyond the part that has been loaded. We'll
+            # use our secret knowledge of lazr.restful to set a value for
+            # the ws.start variable. That way we start reading entries
+            # from the first one we want.
+            first_page_size = None
+            entry_dicts = []
+            page_url = self._with_url_query_variable_set(
+                self._wadl_resource.url, 'ws.start', start)
+
+        desired_size = stop-start
+        more_needed = desired_size - len(entry_dicts)
+
+        # Iterate over pages until we have the correct number of entries.
+        while more_needed > 0 and page_url is not None:
+            representation = simplejson.loads(
+                self._root._browser.get(page_url))
+            current_page_entries = representation['entries']
+            entry_dicts += current_page_entries[:more_needed]
+            more_needed = desired_size - len(entry_dicts)
+
+            page_url = representation.get('next_collection_link')
+            if page_url is None:
+                # We've gotten the entire collection; there are no
+                # more entries.
+                break
+            if first_page_size is None:
+                first_page_size = len(current_page_entries)
+            if more_needed > 0 and more_needed < first_page_size:
+                # An optimization: it's likely that we need less than
+                # a full page of entries, because the number we need
+                # is less than the size of the first page we got.
+                # Instead of requesting a full-sized page, we'll
+                # request only the number of entries we think we'll
+                # need. If we're wrong, there's no problem; we'll just
+                # keep looping.
+                page_url = self._with_url_query_variable_set(
+                    page_url, 'ws.size', more_needed)
+
+        if slice.step is not None:
+            entry_dicts = entry_dicts[::slice.step]
+
+        # Convert entry_dicts into a list of Entry objects.
+        return [resource for resource
+                in self._convert_dicts_to_entries(entry_dicts)]
+
+    def _convert_dicts_to_entries(self, entries):
+        """Convert dictionaries describing entries to Entry objects.
+
+        The dictionaries come from the 'entries' field of the JSON
+        dictionary you get when you GET a page of a collection. Each
+        dictionary is the same as you'd get if you sent a GET request
+        to the corresponding entry resource. So each of these
+        dictionaries can be treated as a preprocessed representation
+        of an entry resource, and turned into an Entry instance.
+
+        :yield: A sequence of Entry instances.
+        """
+        for entry_dict in entries:
+            resource_url = entry_dict['self_link']
+            resource_type_link = entry_dict['resource_type_link']
+            wadl_application = self._wadl_resource.application
+            resource_type = wadl_application.get_resource_type(
+                resource_type_link)
+            resource = WadlResource(
+                self._wadl_resource.application, resource_url,
+                resource_type.tag)
+            yield Resource._create_bound_resource(
+                self._root, resource, entry_dict, self.JSON_MEDIA_TYPE,
+                False)
+
+    def _with_url_query_variable_set(self, url, variable, new_value):
+        """A helper method to set a query variable in a URL."""
+        uri = URI(url)
+        if uri.query is None:
+            params = {}
+        else:
+            params = cgi.parse_qs(uri.query)
+        params[variable] = str(new_value)
+        uri.query = urllib.urlencode(params, True)
+        return str(uri)
+
+
+class CollectionWithKeyBasedLookup(Collection):
+    """A collection-type resource that supports key-based lookup.
+
+    This collection can be sliced, but any single index passed into
+    __getitem__ will be treated as a custom lookup key.
+    """
+
+    def __getitem__(self, key):
+        """Look up a slice, or a subordinate resource by unique ID."""
+        if isinstance(key, slice):
+            return super(CollectionWithKeyBasedLookup, self).__getitem__(key)
+        try:
+            url = self._get_url_from_id(key)
+        except NotImplementedError:
+            raise TypeError("unsubscriptable object")
+        if url is None:
+            raise KeyError(key)
+
+        # We don't know what kind of resource this is. Even the
+        # subclass doesn't necessarily know, because some resources
+        # (the person list) are gateways to more than one kind of
+        # resource (people, and teams). The only way to know for sure
+        # is to retrieve a representation of the resource and see how
+        # the resource describes itself.
+        try:
+            representation = simplejson.loads(self._root._browser.get(url))
+        except HTTPError, error:
+            # There's no resource corresponding to the given ID.
+            if error.response.status == 404:
+                raise KeyError(key)
+            raise
+        # We know that every lazr.restful resource has a
+        # 'resource_type_link' in its representation.
+        resource_type_link = representation['resource_type_link']
+        resource = WadlResource(self._root._wadl, url, resource_type_link)
+        return self._create_bound_resource(
+            self._root, resource, representation=representation,
+            representation_needs_processing=False)
+
+
+    def _get_url_from_id(self, key):
+        """Transform the unique ID of an object into its URL."""
+        raise NotImplementedError()
+
+
+class HostedFileBuffer(StringIO):
+    """The contents of a file hosted by a lazr.restful service."""
+    def __init__(self, hosted_file, mode, content_type=None, filename=None):
+        self.url = hosted_file._wadl_resource.url
+        if mode == 'r':
+            if content_type is not None:
+                raise ValueError("Files opened for read access can't "
+                                 "specify content_type.")
+            if filename is not None:
+                raise ValueError("Files opened for read access can't "
+                                 "specify filename.")
+            response, value = hosted_file._root._browser.get(
+                self.url, return_response=True)
+            content_type = response['content-type']
+            last_modified = response['last-modified']
+
+            # The Content-Location header contains the URL of the file
+            # hosted by the web service. We happen to know that the
+            # final component of the URL is the name of the uploaded
+            # file.
+            content_location = response['content-location']
+            path = urlparse(content_location)[2]
+            filename = urllib.unquote(path.split("/")[-1])
+        elif mode == 'w':
+            value = ''
+            if content_type is None:
+                raise ValueError("Files opened for write access must "
+                                 "specify content_type.")
+            if filename is None:
+                raise ValueError("Files opened for write access must "
+                                 "specify filename.")
+            last_modified = None
+        else:
+            raise ValueError("Invalid mode. Supported modes are: r, w")
+
+        self.hosted_file = hosted_file
+        self.mode = mode
+        self.content_type = content_type
+        self.filename = filename
+        self.last_modified = last_modified
+        StringIO.__init__(self, value)
+
+    def close(self):
+        if self.mode == 'w':
+            disposition = 'attachment; filename="%s"' % self.filename
+            self.hosted_file._root._browser.put(
+                self.url, self.getvalue(),
+                self.content_type, {'Content-Disposition' : disposition})
+        StringIO.close(self)