Merge lp:~barry/ubuntu/natty/python-launchpadlib/bug-702375 into lp:ubuntu/natty/python-launchpadlib

[Barry Warsaw]

Update to upstream 1.9.5 as requested by Leonard Richardson.

[Didier Roche-Tolomelli (didrocks)]

the change looks good, in any case, you have a better knowledge than I on the subject :)

I just wondered as you get a lot of API break in that upgrade if you tested it through the archives? Maybe as well blog about it before the upload so that people having scripts which will be broken scripts or tools (I'm pretty sure Quickly will break reading the changelog ;)) can take some advanced tests toward it.

As it seems the (long) discussion on bug #686690 found an agreement, if the first case is done, people can sponsor it.

[Barry Warsaw (barry)]

Actually, I think Leonard has the definitive word on API issues, so I'll request a comment from him.

[Francis J. Lacoste (flacoste)]

My understanding was that all changes were backward compatible. You only get the new behavior when you change the API.

[Francis J. Lacoste (flacoste)]

According to Benji, the only backward incompatible change is the removal of the edge root. We could add it back but make it only pointing at production.

But at the same time, this is alpha release, so it's probably a good idea to have any apps pointing at edge be upgraded. Make it a good time to take advantage of the new desktop login possibility.

[Leonard Richardson (leonardr)]

I plan to contact the developers of launchpadlib apps that are in Ubuntu and help them make the upgrade.

This branch contains all the changes I expected.

review: Approve

[Leonard Richardson (leonardr)]

BTW, today launchpadlib stopped working with edge. I have a branch to make existing code work (by giving a deprecation warning to people who use edge, and having them use production instead). It would be great to get this into Natty:
https://code.launchpad.net/~leonardr/launchpadlib/fake-edge/+merge/49651

It would also be great to get my backport of this feature into Maverick:
https://code.launchpad.net/~leonardr/launchpadlib/edge-fakery-for-maverick/+merge/49653

[Barry Warsaw (barry)]

I changed this to a work-in-progress and will obsolete the branch. Instead, I'm going to work through Luca to get 1.9.6 into Debian unstable and then we'll sync it over to Natty.

For backporting to Maverick, we'll have to do an SRU.

https://wiki.ubuntu.com/StableReleaseUpdates

Leonard, if you can do the bookkeeping work on proposing the SRU, I'll prepare a package branch.

Unmerged revisions

18. By Barry Warsaw on 2011-02-08

New upstream release. (LP: #702375)

=== modified file 'PKG-INFO'
--- PKG-INFO	2010-12-07 19:30:29 +0000
+++ PKG-INFO	2011-02-08 19:01:02 +0000
@@ -1,6 +1,6 @@
 Metadata-Version: 1.0
 Name: launchpadlib
-Version: 1.6.2
+Version: 1.9.5
 Summary: Script Launchpad through its web services interfaces.  Officially supported.
 Home-page: https://help.launchpad.net/API/launchpadlib
 Author: LAZR Developers
@@ -31,6 +31,103 @@
         NEWS for launchpadlib
         =====================
         
+        1.9.5 (2010-02-08)
+        ==================
+        
+        - Fixed a bug that prevented the deprecated get_token_and_login code
+          from working, and that required that users of get_token_and_login
+          get a new token on every usage.
+        
+        1.9.4 (2010-01-18)
+        ==================
+        
+        - Removed references to the 'edge' service root, which is being phased out.
+        
+        - Fixed a minor bug in the upload_release_tarball contrib script which
+          was causing tarballs to be uploaded with the wrong media type.
+        
+        - The XSLT stylesheet for converting the Launchpad WADL into HTML
+          documentation has been moved back into Launchpad.
+        
+        1.9.3 (2011-01-10)
+        ==================
+        
+        - The keyring package import is now delayed until the keyring needs to be
+          accessed.  This reduces launchapdlib users' exposure to unintended side
+          effects of importing keyring (KWallet authorization dialogs and the
+          registration of a SIGCHLD handler).
+        
+        1.9.2 (2011-01-07)
+        ==================
+        
+        - Added a missing import.
+        
+        1.9.1 (2011-01-06)
+        ==================
+        
+        - Corrected a test failure.
+        
+        1.9.0 (2011-01-05)
+        ==================
+        
+        - When an authorization token expires or becomes invalid, attempt to
+          acquire a new one, even in the middle of a session, rather than
+          crashing.
+        
+        - The HTML generated by wadl-to-refhtml.xsl now validates.
+        
+        - Most of the helper login methods have been deprecated. There are now
+          only two helper methods:
+        
+          * Launchpad.login_anonymously, for anonymous credential-free access.
+          * Launchpad.login_with, for programs that need a credential.
+        
+        
+        1.8.0 (2010-11-15)
+        ==================
+        
+        - Store authorization tokens in the Gnome keyring or KDE wallet, when
+          available. The credentials_file parameter of Launchpad.login_with() is now
+          ignored.
+        
+        - By default, Launchpad.login_with() now asks Launchpad for
+          desktop-wide integration. This removes the need for each individual
+          application to get its own OAuth token.
+        
+        1.7.0 (2010-09-23)
+        ==================
+        
+        - Removed "fake Launchpad browser" code that didn't work and was
+          misleading developers.
+        
+        - Added support for http://qastaging.launchpad.net by adding
+          astaging to the uris.
+        
+        1.6.5 (2010-08-23)
+        ==================
+        
+        - Make launchpadlib compatible with the latest lazr.restfulclient.
+        
+        1.6.4 (2010-08-18)
+        ==================
+        
+        - Test fixes.
+        
+        1.6.3 (2010-08-12)
+        ==================
+        
+        - Instead of making the end-user hit Enter after authorizing an
+          application to access their Launchpad account, launchpadlib will
+          automatically poll Launchpad until the user makes a decision.
+        
+        - launchpadlib now raises a more helpful exception when the end-user
+          explicitly denies access to a launchpadlib application.
+        
+        - Improved the XSLT stylesheet to reflect Launchpad's more complex
+          top-level structure. [bug=286941]
+        
+        - Test fixes. [bug=488448,616055]
+        
         1.6.2 (2010-06-21)
         ==================
         
 
=== modified file 'README.txt'
--- README.txt	2010-12-07 19:30:29 +0000
+++ README.txt	2011-02-08 19:01:02 +0000
@@ -19,7 +19,7 @@
 
 
 Overview
-********
+========
 
 launchpadlib is a standalone Python library for scripting Launchpad through
 its web services interface.  It is the officially supported bindings to the
@@ -44,3 +44,13 @@
 Please submit bug reports to
 
     https://bugs.launchpad.net/launchpadlib
+
+
+Credential storage
+==================
+
+After authorizing an application to access Launchpad on a user's behalf,
+launchpadlib will attempt to store those credentials in the most
+system-appropriate way.  That is, on Gnome it will store them in the Gnome
+keyring, on KDE it will store them in the KDE wallet and if neither of those
+is available it will store them on disk.
 
=== modified file 'debian/changelog'
--- debian/changelog	2010-12-07 19:30:29 +0000
+++ debian/changelog	2011-02-08 19:01:02 +0000
@@ -1,3 +1,9 @@
+python-launchpadlib (1.9.5-0ubuntu1) natty; urgency=low
+
+  * New upstream release.  (LP: #702375)
+
+ -- Barry Warsaw <[e-mail]>  Tue, 08 Feb 2011 13:53:36 -0500
+
 python-launchpadlib (1.8.0.is.1.6.2-0ubuntu1) natty; urgency=low
 
   * Revert to 1.6.2 for the time being. 1.8.0 completely breaks the login_with
 
=== added file 'setup.cfg'
--- setup.cfg	1970-01-01 00:00:00 +0000
+++ setup.cfg	2011-02-08 19:01:02 +0000
@@ -0,0 +1,5 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+tag_svn_revision = 0
+
 
=== modified file 'setup.py'
--- setup.py	2010-12-07 19:30:29 +0000
+++ setup.py	2011-02-08 19:01:02 +0000
@@ -60,6 +60,7 @@
     license='LGPL v3',
     install_requires=[
         'httplib2',
+        'keyring',
         'lazr.restfulclient>=0.9.19',
         'lazr.uri',
         'oauth',
 
=== added file 'src/launchpadlib.egg-info/PKG-INFO'
--- src/launchpadlib.egg-info/PKG-INFO	1970-01-01 00:00:00 +0000
+++ src/launchpadlib.egg-info/PKG-INFO	2011-02-08 19:01:02 +0000
@@ -0,0 +1,251 @@
+Metadata-Version: 1.0
+Name: launchpadlib
+Version: 1.9.5
+Summary: Script Launchpad through its web services interfaces.  Officially supported.
+Home-page: https://help.launchpad.net/API/launchpadlib
+Author: LAZR Developers
+Author-email: [e-mail]
+License: LGPL v3
+Download-URL: https://launchpad.net/launchpadlib/+download
+Description: ..
+            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/>.
+        
+        launchpadlib
+        ************
+        
+        See https://help.launchpad.net/API/launchpadlib .
+        
+        =====================
+        NEWS for launchpadlib
+        =====================
+        
+        1.9.5 (2010-02-08)
+        ==================
+        
+        - Fixed a bug that prevented the deprecated get_token_and_login code
+          from working, and that required that users of get_token_and_login
+          get a new token on every usage.
+        
+        1.9.4 (2010-01-18)
+        ==================
+        
+        - Removed references to the 'edge' service root, which is being phased out.
+        
+        - Fixed a minor bug in the upload_release_tarball contrib script which
+          was causing tarballs to be uploaded with the wrong media type.
+        
+        - The XSLT stylesheet for converting the Launchpad WADL into HTML
+          documentation has been moved back into Launchpad.
+        
+        1.9.3 (2011-01-10)
+        ==================
+        
+        - The keyring package import is now delayed until the keyring needs to be
+          accessed.  This reduces launchapdlib users' exposure to unintended side
+          effects of importing keyring (KWallet authorization dialogs and the
+          registration of a SIGCHLD handler).
+        
+        1.9.2 (2011-01-07)
+        ==================
+        
+        - Added a missing import.
+        
+        1.9.1 (2011-01-06)
+        ==================
+        
+        - Corrected a test failure.
+        
+        1.9.0 (2011-01-05)
+        ==================
+        
+        - When an authorization token expires or becomes invalid, attempt to
+          acquire a new one, even in the middle of a session, rather than
+          crashing.
+        
+        - The HTML generated by wadl-to-refhtml.xsl now validates.
+        
+        - Most of the helper login methods have been deprecated. There are now
+          only two helper methods:
+        
+          * Launchpad.login_anonymously, for anonymous credential-free access.
+          * Launchpad.login_with, for programs that need a credential.
+        
+        
+        1.8.0 (2010-11-15)
+        ==================
+        
+        - Store authorization tokens in the Gnome keyring or KDE wallet, when
+          available. The credentials_file parameter of Launchpad.login_with() is now
+          ignored.
+        
+        - By default, Launchpad.login_with() now asks Launchpad for
+          desktop-wide integration. This removes the need for each individual
+          application to get its own OAuth token.
+        
+        1.7.0 (2010-09-23)
+        ==================
+        
+        - Removed "fake Launchpad browser" code that didn't work and was
+          misleading developers.
+        
+        - Added support for http://qastaging.launchpad.net by adding
+          astaging to the uris.
+        
+        1.6.5 (2010-08-23)
+        ==================
+        
+        - Make launchpadlib compatible with the latest lazr.restfulclient.
+        
+        1.6.4 (2010-08-18)
+        ==================
+        
+        - Test fixes.
+        
+        1.6.3 (2010-08-12)
+        ==================
+        
+        - Instead of making the end-user hit Enter after authorizing an
+          application to access their Launchpad account, launchpadlib will
+          automatically poll Launchpad until the user makes a decision.
+        
+        - launchpadlib now raises a more helpful exception when the end-user
+          explicitly denies access to a launchpadlib application.
+        
+        - Improved the XSLT stylesheet to reflect Launchpad's more complex
+          top-level structure. [bug=286941]
+        
+        - Test fixes. [bug=488448,616055]
+        
+        1.6.2 (2010-06-21)
+        ==================
+        
+        - Extended the optimization from version 1.6.1 to apply to Launchpad's
+          top-level collection of people.
+        
+        1.6.1 (2010-06-16)
+        ==================
+        
+        - Added an optimization that lets launchpadlib avoid making an HTTP
+          request in some situations.
+        
+        1.6.0 (2010-04-07)
+        ==================
+        
+        - Fixed a test to work against the latest version of Launchpad.
+        
+        1.5.8 (2010-03-25)
+        ==================
+        
+        - Use version 1.0 of the Launchpad web service by default.
+        
+        1.5.7 (2010-03-16)
+        ==================
+        
+        - Send a Referer header whenever making requests to the Launchpad
+          website (as opposed to the web service) to avoid falling afoul of
+          new cross-site-request-forgery countermeasures.
+        
+        1.5.6 (2010-03-04)
+        ==================
+        
+        - Fixed a minor bug when using login_with() to access a version of the
+          Launchpad web service other than the default.
+        
+        - Added a check to catch old client code that would cause newer
+          versions of launchpadlib to make nonsensical requests to
+          https://api.launchpad.dev/beta/beta/, and raise a helpful exception
+          telling the developer how to fix it.
+        
+        1.5.5
+        =====
+        
+        - Added the ability to access different versions of the Launchpad web
+          service.
+        
+        1.5.4 (2009-12-17)
+        ==================
+        
+        - Made it easy to get anonymous access to a Launchpad instance.
+        
+        - Made it easy to plug in different clients that take the user's
+          Launchpad login and password for purposes of authorizing a request
+          token. The most secure technique is still the default: to open the
+          user's web browser to the appropriate Launchpad page.
+        
+        - Introduced a command-line script bin/launchpad-credentials-console,
+          which takes the user's Launchpad login and password, and authorizes
+          a request token on their behalf.
+        
+        - Introduced a command-line script bin/launchpad-request-token, which
+          creates a request token on any Launchpad installation and dumps the
+          JSON description of that token to standard output.
+        
+        - Shorthand service names like 'edge' should now be respected
+          everywhere in launchpadlib.
+        
+        1.5.3 (2009-10-22)
+        ==================
+        
+        - Moved some more code from launchpadlib into the more generic
+          lazr.restfulclient.
+        
+        1.5.2 (2009-10-01)
+        ==================
+        
+        - Added a number of new sample scripts from elsewhere.
+        
+        - Added a reference to the production Launchpad instance.
+        
+        - Made it easier to specify a Launchpad instance to run against.
+        
+        1.5.1 (2009-07-16)
+        ==================
+        
+        - Added a sample script for uploading a release tarball to Launchpad.
+        
+        1.5.0 (2009-07-09)
+        ==================
+        
+        - Most of launchpadlib's code has been moved to the generic
+          lazr.restfulclient library. launchpadlib now contains only code
+          specific to Launchpad. There should be no changes in functionality.
+        
+        - Moved bootstrap.py into the top-level directory. Having it in a
+          subdirectory with a top-level symlink was breaking installation on
+          Windows.
+        
+        - The notice to the end-user (that we're opening their web
+          browser) is now better formatted.
+        
+        1.0.1 (2009-05-30)
+        ==================
+        
+        - Correct tests for new launchpad cache behavior in librarian
+        
+        - Remove build dependency on setuptools_bzr because it was causing bzr to be
+          downloaded during installation of the package, which was unnecessary and
+          annoying.
+        
+        1.0 (2009-03-24)
+        ================
+        
+        - Initial release on PyPI
+        
+Platform: UNKNOWN
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
 
=== modified file 'src/launchpadlib.egg-info/SOURCES.txt'
--- src/launchpadlib.egg-info/SOURCES.txt	2010-12-07 19:30:29 +0000
+++ src/launchpadlib.egg-info/SOURCES.txt	2011-02-08 19:01:02 +0000
@@ -11,22 +11,22 @@
 src/launchpadlib/errors.py
 src/launchpadlib/launchpad.py
 src/launchpadlib/uris.py
-src/launchpadlib/wadl-to-refhtml.xsl
 src/launchpadlib.egg-info/PKG-INFO
 src/launchpadlib.egg-info/SOURCES.txt
 src/launchpadlib.egg-info/dependency_links.txt
 src/launchpadlib.egg-info/not-zip-safe
 src/launchpadlib.egg-info/requires.txt
 src/launchpadlib.egg-info/top_level.txt
-src/launchpadlib/docs/browser.txt
 src/launchpadlib/docs/command-line.txt
 src/launchpadlib/docs/hosted-files.txt
 src/launchpadlib/docs/introduction.txt
+src/launchpadlib/docs/operations.txt
 src/launchpadlib/docs/people.txt
 src/launchpadlib/docs/toplevel.txt
-src/launchpadlib/docs/trusted-client.txt
 src/launchpadlib/docs/files/mugshot.png
 src/launchpadlib/testing/__init__.py
 src/launchpadlib/testing/helpers.py
 src/launchpadlib/tests/__init__.py
+src/launchpadlib/tests/test_credential_store.py
+src/launchpadlib/tests/test_http.py
 src/launchpadlib/tests/test_launchpad.py
 \ No newline at end of file
 
=== added file 'src/launchpadlib.egg-info/not-zip-safe'
--- src/launchpadlib.egg-info/not-zip-safe	1970-01-01 00:00:00 +0000
+++ src/launchpadlib.egg-info/not-zip-safe	2011-02-08 19:01:02 +0000
@@ -0,0 +1,1 @@
+
 
=== modified file 'src/launchpadlib.egg-info/requires.txt'
--- src/launchpadlib.egg-info/requires.txt	2010-12-07 19:30:29 +0000
+++ src/launchpadlib.egg-info/requires.txt	2011-02-08 19:01:02 +0000
@@ -1,5 +1,6 @@
 httplib2
-lazr.restfulclient>=0.9.11
+keyring
+lazr.restfulclient>=0.9.19
 lazr.uri
 oauth
 setuptools
 
=== modified file 'src/launchpadlib/NEWS.txt'
--- src/launchpadlib/NEWS.txt	2010-12-07 19:30:29 +0000
+++ src/launchpadlib/NEWS.txt	2011-02-08 19:01:02 +0000
@@ -2,6 +2,103 @@
 NEWS for launchpadlib
 =====================
 
+1.9.5 (2010-02-08)
+==================
+
+- Fixed a bug that prevented the deprecated get_token_and_login code
+  from working, and that required that users of get_token_and_login
+  get a new token on every usage.
+
+1.9.4 (2010-01-18)
+==================
+
+- Removed references to the 'edge' service root, which is being phased out.
+
+- Fixed a minor bug in the upload_release_tarball contrib script which
+  was causing tarballs to be uploaded with the wrong media type.
+
+- The XSLT stylesheet for converting the Launchpad WADL into HTML
+  documentation has been moved back into Launchpad.
+
+1.9.3 (2011-01-10)
+==================
+
+- The keyring package import is now delayed until the keyring needs to be
+  accessed.  This reduces launchapdlib users' exposure to unintended side
+  effects of importing keyring (KWallet authorization dialogs and the
+  registration of a SIGCHLD handler).
+
+1.9.2 (2011-01-07)
+==================
+
+- Added a missing import.
+
+1.9.1 (2011-01-06)
+==================
+
+- Corrected a test failure.
+
+1.9.0 (2011-01-05)
+==================
+
+- When an authorization token expires or becomes invalid, attempt to
+  acquire a new one, even in the middle of a session, rather than
+  crashing.
+
+- The HTML generated by wadl-to-refhtml.xsl now validates.
+
+- Most of the helper login methods have been deprecated. There are now
+  only two helper methods:
+
+  * Launchpad.login_anonymously, for anonymous credential-free access.
+  * Launchpad.login_with, for programs that need a credential.
+
+
+1.8.0 (2010-11-15)
+==================
+
+- Store authorization tokens in the Gnome keyring or KDE wallet, when
+  available. The credentials_file parameter of Launchpad.login_with() is now
+  ignored.
+
+- By default, Launchpad.login_with() now asks Launchpad for
+  desktop-wide integration. This removes the need for each individual
+  application to get its own OAuth token.
+
+1.7.0 (2010-09-23)
+==================
+
+- Removed "fake Launchpad browser" code that didn't work and was
+  misleading developers.
+
+- Added support for http://qastaging.launchpad.net by adding
+  astaging to the uris.
+
+1.6.5 (2010-08-23)
+==================
+
+- Make launchpadlib compatible with the latest lazr.restfulclient.
+
+1.6.4 (2010-08-18)
+==================
+
+- Test fixes.
+
+1.6.3 (2010-08-12)
+==================
+
+- Instead of making the end-user hit Enter after authorizing an
+  application to access their Launchpad account, launchpadlib will
+  automatically poll Launchpad until the user makes a decision.
+
+- launchpadlib now raises a more helpful exception when the end-user
+  explicitly denies access to a launchpadlib application.
+
+- Improved the XSLT stylesheet to reflect Launchpad's more complex
+  top-level structure. [bug=286941]
+
+- Test fixes. [bug=488448,616055]
+
 1.6.2 (2010-06-21)
 ==================
 
 
=== modified file 'src/launchpadlib/__init__.py'
--- src/launchpadlib/__init__.py	2010-12-07 19:30:29 +0000
+++ src/launchpadlib/__init__.py	2011-02-08 19:01:02 +0000
@@ -14,4 +14,4 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with launchpadlib. If not, see <http://www.gnu.org/licenses/>.
 
-__version__ = '1.6.2'
+__version__ = '1.9.5'
 
=== modified file 'src/launchpadlib/apps.py'
--- src/launchpadlib/apps.py	2010-12-07 19:30:29 +0000
+++ src/launchpadlib/apps.py	2011-02-08 19:01:02 +0000
@@ -52,122 +52,3 @@
         return simplejson.dumps(token)
 
 
-class TrustedTokenAuthorizationConsoleApp(RequestTokenAuthorizationEngine):
-    """An application that authorizes request tokens."""
-
-    def __init__(self, web_root, consumer_name, request_token,
-                 access_levels='', input_method=raw_input):
-        """Constructor.
-
-        :param access_levels: A string of comma-separated access level
-        values.  To get an up-to-date list of access levels, pass
-        token_format=Credentials.DICT_TOKEN_FORMAT into
-        Credentials.get_request_token, load the dict as JSON, and look
-        in 'access_levels'.
-        """
-        access_levels = [level.strip() for level in access_levels.split(',')]
-        super(TrustedTokenAuthorizationConsoleApp, self).__init__(
-            web_root, consumer_name, request_token, access_levels)
-
-        self.input_method = input_method
-
-    def run(self):
-        """Try to authorize a request token from user input."""
-        self.error_code = -1 # Start off assuming failure.
-        start = "Launchpad credential client (console)"
-        self.output(start)
-        self.output("-" * len(start))
-
-        try:
-            self()
-        except TokenAuthorizationException, e:
-            print str(e)
-            self.error_code = -1
-        return self.press_enter_to_exit()
-
-    def exit_with(self, code):
-        """Exit the app with the specified error code."""
-        sys.exit(code)
-
-    def get_single_char_input(self, prompt, valid):
-        """Retrieve a single-character line from the input stream."""
-        valid = valid.upper()
-        input = None
-        while input is None:
-            input = self.input_method(prompt).upper()
-            if len(input) != 1 or input not in valid:
-                input = None
-        return input
-
-    def press_enter_to_exit(self):
-        """Make the user hit enter, and then exit with an error code."""
-        prompt = '\nPress enter to go back to "%s". ' % self.consumer_name
-        self.input_method(prompt)
-        self.exit_with(self.error_code)
-
-    def input_username(self, cached_username, suggested_message):
-        """Collect the Launchpad username from the end-user.
-
-        :param cached_username: A username from a previous entry attempt,
-        to be presented as the default.
-        """
-        if cached_username is not None:
-            extra = " [%s] " % cached_username
-        else:
-            extra = "\n(No Launchpad account? Just hit enter.) "
-        username = self.input_method(suggested_message + extra)
-        if username == '':
-            return cached_username
-        return username
-
-    def input_password(self, suggested_message):
-        """Collect the Launchpad password from the end-user."""
-        if self.input_method is raw_input:
-            password = getpass.getpass(suggested_message + " ")
-        else:
-            password = self.input_method(suggested_message)
-        return password
-
-    def input_access_level(self, available_levels, suggested_message,
-                           only_one_option=None):
-        """Collect the desired level of access from the end-user."""
-        if only_one_option is not None:
-            self.output(suggested_message)
-            prompt = self.message(
-                'Do you want to give "%(app)s" this level of access? [YN] ')
-            allow = self.get_single_char_input(prompt, "YN")
-            if allow == "Y":
-                return only_one_option['value']
-            else:
-                return self.UNAUTHORIZED_ACCESS_LEVEL
-        else:
-            levels_except_unauthorized = [
-                level for level in available_levels
-                if level['value'] != self.UNAUTHORIZED_ACCESS_LEVEL]
-            options = []
-            for i in range(0, len(levels_except_unauthorized)):
-                options.append(
-                    "%d: %s" % (i+1, levels_except_unauthorized[i]['title']))
-            self.output(suggested_message)
-            for option in options:
-                self.output(option)
-            allowed = ("".join(map(str, range(1, i+2)))) + "Q"
-            prompt = self.message(
-                'What should "%(app)s" be allowed to do using your '
-                'Launchpad account? [1-%(max)d or Q] ',
-                extra_variables = {'max' : i+1})
-            allow = self.get_single_char_input(prompt, allowed)
-            if allow == "Q":
-                return self.UNAUTHORIZED_ACCESS_LEVEL
-            else:
-                return levels_except_unauthorized[int(allow)-1]['value']
-
-    def user_refused_to_authorize(self, suggested_message):
-        """The user refused to authorize a request token."""
-        self.output(suggested_message)
-        self.error_code = -2
-
-    def user_authorized(self, access_level, suggested_message):
-        """The user authorized a request token with some access level."""
-        self.output(suggested_message)
-        self.error_code = 0
 
=== modified file 'src/launchpadlib/credentials.py'
--- src/launchpadlib/credentials.py	2010-12-07 19:30:29 +0000
+++ src/launchpadlib/credentials.py	2011-02-08 19:01:02 +0000
@@ -20,17 +20,20 @@
 __all__ = [
     'AccessToken',
     'AnonymousAccessToken',
+    'AuthorizeRequestTokenWithBrowser',
+    'CredentialStore',
     'RequestTokenAuthorizationEngine',
     'Consumer',
     'Credentials',
     ]
 
-import base64
 import cgi
+from cStringIO import StringIO
 import httplib2
-import sys
-import textwrap
-from urllib import urlencode, quote
+import os
+import stat
+import time
+from urllib import urlencode
 from urlparse import urljoin
 import webbrowser
 
@@ -38,13 +41,20 @@
 
 from lazr.restfulclient.errors import HTTPError
 from lazr.restfulclient.authorize.oauth import (
-    AccessToken as _AccessToken, Consumer, OAuthAuthorizer)
+    AccessToken as _AccessToken,
+    Consumer,
+    OAuthAuthorizer,
+    SystemWideConsumer # Not used directly, just re-imported into here.
+    )
 
 from launchpadlib import uris
 
 request_token_page = '+request-token'
 access_token_page = '+access-token'
 authorize_token_page = '+authorize-token'
+access_token_poll_time = 1
+
+EXPLOSIVE_ERRORS = (MemoryError, KeyboardInterrupt, SystemExit)
 
 
 class Credentials(OAuthAuthorizer):
@@ -60,6 +70,25 @@
     URI_TOKEN_FORMAT = "uri"
     DICT_TOKEN_FORMAT = "dict"
 
+    def serialize(self):
+        """Turn this object into a string.
+
+        This should probably be moved into OAuthAuthorizer.
+        """
+        sio = StringIO()
+        self.save(sio)
+        return sio.getvalue()
+
+    @classmethod
+    def from_string(cls, value):
+        """Create a `Credentials` object from a serialized string.
+
+        This should probably be moved into OAuthAuthorizer.
+        """
+        credentials = cls()
+        credentials.load(StringIO(value))
+        return credentials
+
     def get_request_token(self, context=None, web_root=uris.STAGING_WEB_ROOT,
                           token_format=URI_TOKEN_FORMAT):
         """Request an OAuth token to Launchpad.
@@ -182,362 +211,351 @@
         super(AnonymousAccessToken, self).__init__('','')
 
 
-class SimulatedLaunchpadBrowser(object):
-    """A programmable substitute for a human-operated web browser.
-
-    Used by client programs to interact with Launchpad's credential
-    pages, without opening them in the user's actual web browser.
-    """
-
-    def __init__(self, web_root=uris.STAGING_WEB_ROOT):
-        self.web_root = uris.lookup_web_root(web_root)
-        self.http = httplib2.Http()
-
-    def _auth_header(self, username, password):
-        """Utility method to generate a Basic auth header."""
-        auth = base64.encodestring("%s:%s" % (username, password))[:-1]
-        return "Basic " + auth
-
-    def get_token_info(self, username, password, request_token,
-                       access_levels=''):
-        """Retrieve a JSON representation of a request token.
-
-        This is useful for verifying that the end-user gave a valid
-        username and password, and for reconciling the client's
-        allowable access levels with the access levels defined in
-        Launchpad.
-        """
-        if access_levels != '':
-            s = "&allow_permission="
-            access_levels = s + s.join(access_levels)
-        page = "%s?oauth_token=%s%s" % (
-            authorize_token_page, request_token, access_levels)
-        url = urljoin(self.web_root, page)
-        # We can't use httplib2's add_credentials, because Launchpad
-        # doesn't respond to credential-less access with a 401
-        # response code.
-        headers = {'Accept' : 'application/json',
-                   'Referer' : self.web_root}
-        headers['Authorization'] = self._auth_header(username, password)
-        response, content = self.http.request(url, headers=headers)
-        # Detect common error conditions and set the response code
-        # appropriately. This lets code that uses
-        # SimulatedLaunchpadBrowser detect standard response codes
-        # instead of having Launchpad-specific knowledge.
-        location = response.get('content-location')
-        if response.status == 200 and '+login' in location:
-            response.status = 401
-        elif response.get('content-type') != 'application/json':
-            response.status = 500
-        return response, content
-
-    def grant_access(self, username, password, request_token, access_level,
-                     context=None):
-        """Grant a level of access to an application on behalf of a user."""
-        headers = {'Content-type' : 'application/x-www-form-urlencoded',
-                   'Referer' : self.web_root}
-        headers['Authorization'] = self._auth_header(username, password)
-        body = "oauth_token=%s&field.actions.%s=True" % (
-            quote(request_token), quote(access_level))
-        if context is not None:
-            body += "&lp.context=%s" % quote(context)
-        url = urljoin(self.web_root, "+authorize-token")
-        response, content = self.http.request(
-            url, method="POST", headers=headers, body=body)
-        # This would be much less fragile if Launchpad gave us an
-        # error code to work with.
-        if "Unauthenticated user POSTing to page" in content:
-            response.status = 401 # Unauthorized
-        elif 'Request already reviewed' in content:
-            response.status = 409 # Conflict
-        elif 'What level of access' in content:
-            response.status = 400 # Bad Request
-        elif 'Unable to identify application' in content:
-            response.status = 400 # Bad Request
-        elif not 'Almost finished' in content:
-            response.status = 500 # Internal Server Error
-        return response, content
+class CredentialStore(object):
+    """Store OAuth credentials locally.
+
+    This is a generic superclass. To implement a specific way of
+    storing credentials locally you'll need to subclass this class,
+    and implement `do_save` and `do_load`.
+    """
+
+    def __init__(self, credential_save_failed=None):
+        """Constructor.
+
+        :param credential_save_failed: A callback to be invoked if the
+            save to local storage fails. You should never invoke this
+            callback yourself! Instead, you should raise an exception
+            from do_save().
+        """
+        self.credential_save_failed = credential_save_failed
+
+    def save(self, credentials, unique_consumer_id):
+        """Save the credentials and invoke the callback on failure.
+
+        Do not override this method when subclassing. Override
+        do_save() instead.
+        """
+        try:
+            self.do_save(credentials, unique_consumer_id)
+        except EXPLOSIVE_ERRORS:
+            raise
+        except Exception, e:
+            if self.credential_save_failed is None:
+                raise e
+            self.credential_save_failed()
+        return credentials
+
+    def do_save(self, credentials, unique_consumer_id):
+        """Store newly-authorized credentials locally for later use.
+
+        :param credentials: A Credentials object to save.
+        :param unique_consumer_id: A string uniquely identifying an
+            OAuth consumer on a Launchpad instance.
+        """
+        raise NotImplementedError()
+
+    def load(self, unique_key):
+        """Retrieve credentials from a local store.
+
+        This method is the inverse of `save`.
+
+        There's no special behavior in this method--it just calls
+        `do_load`. There _is_ special behavior in `save`, and this
+        way, developers can remember to implement `do_save` and
+        `do_load`, not `do_save` and `load`.
+
+        :param unique_key: A string uniquely identifying an OAuth consumer
+            on a Launchpad instance.
+
+        :return: A `Credentials` object if one is found in the local
+            store, and None otherise.
+        """
+        return self.do_load(unique_key)
+
+    def do_load(self, unique_key):
+        """Retrieve credentials from a local store.
+
+        This method is the inverse of `do_save`.
+
+        :param unique_key: A string uniquely identifying an OAuth consumer
+            on a Launchpad instance.
+
+        :return: A `Credentials` object if one is found in the local
+            store, and None otherise.
+        """
+        raise NotImplementedError()
+
+
+class KeyringCredentialStore(CredentialStore):
+    """Store credentials in the GNOME keyring or KDE wallet.
+
+    This is a good solution for desktop applications and interactive
+    scripts. It doesn't work for non-interactive scripts, or for
+    integrating third-party websites into Launchpad.
+    """
+
+    @staticmethod
+    def _ensure_keyring_imported():
+        """Ensure the keyring module is imported (postponing side effects).
+
+        The keyring module initializes the environment-dependent backend at
+        import time (nasty).  We want to avoid that initialization because it
+        may do things like prompt the user to unlock their password store
+        (e.g., KWallet).
+        """
+        if 'keyring' not in globals():
+            global keyring
+            import keyring
+
+    def do_save(self, credentials, unique_key):
+        """Store newly-authorized credentials in the keyring."""
+        self._ensure_keyring_imported()
+        keyring.set_password(
+            'launchpadlib', unique_key, credentials.serialize())
+
+    def do_load(self, unique_key):
+        """Retrieve credentials from the keyring."""
+        self._ensure_keyring_imported()
+        credential_string = keyring.get_password(
+            'launchpadlib', unique_key)
+        if credential_string is not None:
+            return Credentials.from_string(credential_string)
+        return None
+
+
+class UnencryptedFileCredentialStore(CredentialStore):
+    """Store credentials unencrypted in a file on disk.
+
+    This is a good solution for scripts that need to run without any
+    user interaction.
+    """
+
+    def __init__(self, filename, credential_save_failed=None):
+        super(UnencryptedFileCredentialStore, self).__init__(
+            credential_save_failed)
+        self.filename = filename
+
+    def do_save(self, credentials, unique_key):
+        """Save the credentials to disk."""
+        credentials.save_to_path(self.filename)
+
+    def do_load(self, unique_key):
+        """Load the credentials from disk."""
+        if (os.path.exists(self.filename)
+            and not os.stat(self.filename)[stat.ST_SIZE] == 0):
+            return Credentials.load_from_path(self.filename)
+        return None
 
 
 class RequestTokenAuthorizationEngine(object):
+    """The superclass of all request token authorizers.
+
+    This base class does not implement request token authorization,
+    since that varies depending on how you want the end-user to
+    authorize a request token. You'll need to subclass this class and
+    implement `make_end_user_authorize_token`.
+    """
 
     UNAUTHORIZED_ACCESS_LEVEL = "UNAUTHORIZED"
 
-    # Suggested messages for clients to display in common situations.
-
-    AUTHENTICATION_FAILURE = "I can't log in with the credentials you gave me. Let's try again."
-
-    CHOOSE_ACCESS_LEVEL = """Now it's time for you to decide how much power to give "%(app)s" over your Launchpad account."""
-
-    CHOOSE_ACCESS_LEVEL_ONE = CHOOSE_ACCESS_LEVEL + """
-
-"%(app)s" says it needs the following level of access to your Launchpad account: "%(level)s". It can't work with any other level of access, so denying this level of access means prohibiting "%(app)s" from using your Launchpad account at all."""
-
-    USER_AUTHORIZED = """Okay, I'm telling Launchpad to grant "%(app)s" access to your account."""
-
-    USER_REFUSED_TO_AUTHORIZE = """Okay, I'm going to cancel the request that "%(app)s" made for access to your account. You can always set this up again later."""
-
-    CLIENT_ERROR = """Sorry, but Launchpad is behaving in a way this client doesn't understand. There might be a bug in the client, a bug in the server, or this client might just be out of date."""
-
-    CONSUMER_MISMATCH = """WARNING: The application you're using told me its name was "%(old_consumer)s", but it told Launchpad its name was "%(real_consumer)s". This is probably not a problem, but it's a little suspicious, so you might want to look into this before continuing. I'll refer to the application as "%(real_consumer)s" from this point on."""
-
-    INPUT_USERNAME = "What email address do you use on Launchpad?"
-
-    INPUT_PASSWORD = "What's your Launchpad password? "
-
-    NONEXISTENT_REQUEST_TOKEN = """Launchpad couldn't find an outstanding request for integration between "%(app)s" and your Launchpad account. Either someone (hopefully you) already set up the integration, or else "%(app)s" is simply wrong and didn't actually set this up with Launchpad. If you still can't use "%(app)s" with Launchpad, try this process again from the beginning."""
-
-    REQUEST_TOKEN_ALREADY_AUTHORIZED = """It looks like you already approved this request to grant "%(app)s" access to your Launchpad account. You shouldn't need to do anything more."""
-
-    SERVER_ERROR = """There seems to be something wrong on the Launchpad server side, and I can't continue. Hopefully this is a temporary problem, but if it persists, it's probably because of a bug in Lauchpad or (less likely) a bug in "%(app)s"."""
-
-    STARTUP_MESSAGE = """An application identified as "%(app)s" wants to access Launchpad on your behalf. I'm the Launchpad credential client and I'm here to ask for your Launchpad username and password."""
-
-    STARTUP_MESSAGE_2 = """I'll use your Launchpad password to give "%(app)s" limited access to your Launchpad account. I will not show your password to "%(app)s" itself."""
-
-    SUCCESS = """You're all done! You should now be able to use Launchpad integration features of "%(app)s." """
-
-    SUCCESS_UNAUTHORIZED = """You're all done! "%(app)s" still doesn't have access to your Launchpad account."""
-
-    TOO_MANY_AUTHENTICATION_FAILURES = """You've failed the password entry too many times. I'm going to exit back to "%(app)s." Try again once you've solved the problem with your Launchpad account."""
-
-    YOU_NEED_A_LAUNCHPAD_ACCOUNT = """OK, you'll need to get yourself a Launchpad account before you can integrate Launchpad into "%(app)s."
-
-I'm opening the Launchpad registration page in your web browser so you can create an account. Once you've created an account, you can try this again."""
-
-    def __init__(self, web_root, consumer_name, request_token,
-                 allow_access_levels=[], max_failed_attempts=3):
-        self.web_root = uris.lookup_web_root(web_root)
-        self.consumer_name = consumer_name
-        self.request_token = request_token
-        self.browser = SimulatedLaunchpadBrowser(self.web_root)
-        self.max_failed_attempts = max_failed_attempts
-        self.allow_access_levels = allow_access_levels
-        self.text_wrapper = textwrap.TextWrapper(
-            replace_whitespace=False, width=78)
-
-    def __call__(self):
-
-        self.startup(
-            [self.message(self.STARTUP_MESSAGE),
-             self.message(self.STARTUP_MESSAGE_2)])
-
-        # Have the end-user enter their Launchpad username and password.
-        # Make sure the credentials are valid, and get information
-        # about the request token as a side effect.
-        username, password, token_info = self.get_http_credentials()
-
-        # Update this object with fresh information about the request token.
-        self.token_info = token_info
-        self.reconciled_access_levels = token_info['access_levels']
-        self._check_consumer()
-
-        # Have the end-user choose an access level from the fresh list.
-        if len(self.reconciled_access_levels) == 2:
-            # There's only one choice: allow access at a certain level
-            # or don't allow access at all.
-            message = self.CHOOSE_ACCESS_LEVEL_ONE
-            level = [level for level in self.reconciled_access_levels
-                     if level['value'] != self.UNAUTHORIZED_ACCESS_LEVEL][0]
-            extra = {'level' : level['title']}
-            only_one_option = level
-        else:
-            message = self.CHOOSE_ACCESS_LEVEL
-            extra = None
-            only_one_option = None
-        access_level = self.input_access_level(
-            self.reconciled_access_levels, self.message(message, extra),
-            only_one_option)
-
-        # Notify the program of the user's choice.
-        if access_level == self.UNAUTHORIZED_ACCESS_LEVEL:
-            self.user_refused_to_authorize(
-                    self.message(self.USER_REFUSED_TO_AUTHORIZE))
-        else:
-            self.user_authorized(
-                access_level, self.message(self.USER_AUTHORIZED))
-
-        # Try to grant the specified level of access to the request token.
-        response, content = self.browser.grant_access(
-            username, password, self.request_token, access_level)
-        if response.status == 409:
-            raise RequestTokenAlreadyAuthorized(
-                self.message(self.REQUEST_TOKEN_ALREADY_AUTHORIZED))
-        elif response.status == 400:
-            raise ClientError(self.message(self.CLIENT_ERROR))
-        elif response.status == 500:
-            raise ServerError(self.message(self.SERVER_ERROR))
-        if access_level == self.UNAUTHORIZED_ACCESS_LEVEL:
-            message = self.SUCCESS_UNAUTHORIZED
-        else:
-            message = self.SUCCESS
-        self.success(self.message(message))
-
-    def get_http_credentials(self, cached_username=None, failed_attempts=0):
-        """Authenticate the user to Launchpad, or raise an exception trying.
-
-        :return: A 3-tuple (username, password,
-        token_info). 'username' and 'password' are the validated
-        Launchpad username and password. 'token_info' is a dict of
-        validated information about the request token, including
-        Launchpad's reconciled list of its available access levels
-        with the access levels the third-party client will accept.
-
-        :param cached_username: If the user has tried to enter their
-        credentials before and failed, this variable will contain the
-        username they entered the first time. This can be presented as
-        a default, since users are more likely to enter the wrong
-        password than the wrong username.
-
-        :param failed_attempts: This method calls itself recursively
-        until failed_attempts equals self.max_failed_attempts.
-        """
-        username = self.input_username(
-            cached_username, self.message(self.INPUT_USERNAME))
-        if username is None:
-            self.open_page_in_user_browser(
-                urljoin(self.web_root, "+login"))
-            raise NoLaunchpadAccount(
-                self.message(self.YOU_NEED_A_LAUNCHPAD_ACCOUNT))
-        password = self.input_password(self.message(self.INPUT_PASSWORD))
-        response, content = self.browser.get_token_info(
-            username, password, self.request_token, self.allow_access_levels)
-        if response.status == 500:
-            raise ServerError(self.message(self.SERVER_ERROR))
-        elif response.status == 401:
-            failed_attempts += 1
-            if failed_attempts == self.max_failed_attempts:
-                raise TooManyAuthenticationFailures(
-                    self.message(self.TOO_MANY_AUTHENTICATION_FAILURES))
-            else:
-                self.authentication_failure(
-                    self.message(self.AUTHENTICATION_FAILURE))
-                return self.get_http_credentials(username, failed_attempts)
-        token_info = simplejson.loads(content)
-        # If Launchpad provides no information about the request token,
-        # that means the request token doesn't exist.
-        if 'oauth_token' not in token_info:
-            raise RequestTokenAlreadyAuthorized(
-                self.message(self.NONEXISTENT_REQUEST_TOKEN))
-        return username, password, token_info
-
-    def _check_consumer(self):
-        """Sanity-check the server consumer against the client consumer."""
-        real_consumer = self.token_info['oauth_token_consumer']
-        if real_consumer != self.consumer_name:
-            message = self.message(
-                self.CONSUMER_MISMATCH, { 'old_consumer' : self.consumer_name,
-                                          'real_consumer' : real_consumer })
-            self.server_consumer_differs_from_client_consumer(
-                self.consumer_name, real_consumer, message)
-            self.consumer_name = real_consumer
-
-    def message(self, raw_message, extra_variables=None):
-        """Prepare a message by plugging in the app name."""
-        variables = { 'app' : self.consumer_name }
-        if extra_variables is not None:
-            variables.update(extra_variables)
-        return raw_message % variables
-
-    def open_page_in_user_browser(self, url):
-        """Open a web page in the user's web browser."""
-        webbrowser.open(url)
-
-    # You should define these methods in your subclass.
-
-    def output(self, message):
-        print self.text_wrapper.fill(message)
-
-    def input_username(self, cached_username, suggested_message):
-        """Collect the Launchpad username from the end-user.
-
-        :param cached_username: A username from a previous entry attempt,
-        to be presented as the default.
-        """
-        raise NotImplementedError()
-
-    def input_password(self, suggested_message):
-        """Collect the Launchpad password from the end-user."""
-        raise NotImplementedError()
-
-    def input_access_level(self, available_levels, suggested_message,
-                           only_one_option=None):
-        """Collect the desired level of access from the end-user."""
-        raise NotImplementedError()
-
-    def startup(self, suggested_messages):
-        """Hook method called on startup."""
-        for message in suggested_messages:
-            self.output(message)
-            self.output("\n")
-
-    def authentication_failure(self, suggested_message):
-        """The user entered invalid credentials."""
-        self.output(suggested_message)
-        self.output("\n")
-
-    def user_refused_to_authorize(self, suggested_message):
-        """The user refused to authorize a request token."""
-        self.output(suggested_message)
-        self.output("\n")
-
-    def user_authorized(self, access_level, suggested_message):
-        """The user authorized a request token with some access level."""
-        self.output(suggested_message)
-        self.output("\n")
-
-    def server_consumer_differs_from_client_consumer(
-        self, client_name, real_name, suggested_message):
-        """The client seems to be lying or mistaken about its name.
-
-        When requesting a request token, the client told Launchpad
-        that its consumer name was "foo". Now the client is telling the
-        end-user that its name is "bar". Something is fishy and at the very
-        least the end-user should be warned about this.
-        """
-        self.output("\n")
-        self.output(suggested_message)
-        self.output("\n")
-
-    def success(self, suggested_message):
-        """The token was successfully authorized."""
-        self.output(suggested_message)
+    def __init__(self, service_root, application_name=None,
+                 consumer_name=None, allow_access_levels=None):
+        """Base class initialization.
+
+        :param service_root: The root of the Launchpad instance being
+            used.
+
+        :param application_name: The name of the application that
+            wants to use launchpadlib. This is used in conjunction
+            with a desktop-wide integration.
+
+            If you specify this argument, your values for
+            consumer_name and allow_access_levels are ignored.
+
+        :param consumer_name: The OAuth consumer name, for an
+            application that wants its own point of integration into
+            Launchpad. In almost all cases, you want to specify
+            application_name instead and do a desktop-wide
+            integration. The exception is when you're integrating a
+            third-party website into Launchpad.
+
+        :param allow_access_levels: A list of the Launchpad access
+            levels to present to the user. ('READ_PUBLIC' and so on.)
+            Your value for this argument will be ignored during a
+            desktop-wide integration.
+        :type allow_access_levels: A list of strings.
+        """
+        self.service_root = uris.lookup_service_root(service_root)
+        self.web_root = uris.web_root_for_service_root(service_root)
+
+        if application_name is None and consumer_name is None:
+            raise ValueError(
+                "You must provide either application_name or consumer_name.")
+
+        if application_name is not None and consumer_name is not None:
+            raise ValueError(
+                "You must provide only one of application_name and "
+                "consumer_name. (You provided %r and %r.)" % (
+                    application_name, consumer_name))
+
+        if consumer_name is None:
+            # System-wide integration. Create a system-wide consumer
+            # and identify the application using a separate
+            # application name.
+            allow_access_levels = ["DESKTOP_INTEGRATION"]
+            consumer = SystemWideConsumer(application_name)
+        else:
+            # Application-specific integration. Use the provided
+            # consumer name to create a consumer automatically.
+            consumer = Consumer(consumer_name)
+            application_name = consumer_name
+
+        self.consumer = consumer
+        self.application_name = application_name
+
+        self.allow_access_levels = allow_access_levels or []
+
+    @property
+    def unique_consumer_id(self):
+        """Return a string identifying this consumer on this host."""
+        return self.consumer.key + '@' + self.service_root
+
+    def authorization_url(self, request_token):
+        """Return the authorization URL for a request token.
+
+        This is the URL the end-user must visit to authorize the
+        token. How exactly does this happen? That depends on the
+        subclass implementation.
+        """
+        page = "%s?oauth_token=%s" % (authorize_token_page, request_token)
+        allow_permission = "&allow_permission="
+        if len(self.allow_access_levels) > 0:
+            page += (
+                allow_permission
+                + allow_permission.join(self.allow_access_levels))
+        return urljoin(self.web_root, page)
+
+    def __call__(self, credentials, credential_store):
+        """Authorize a token and associate it with the given credentials.
+
+        If the credential store runs into a problem storing the
+        credential locally, the `credential_save_failed` callback will
+        be invoked. The callback will not be invoked if there's a
+        problem authorizing the credentials.
+
+        :param credentials: A `Credentials` object. If the end-user
+            authorizes these credentials, this object will have its
+            .access_token property set.
+
+        :param credential_store: A `CredentialStore` object. If the
+            end-user authorizes the credentials, they will be
+            persisted locally using this object.
+
+        :return: If the credentials are successfully authorized, the
+            return value is the `Credentials` object originally passed
+            in. Otherwise the return value is None.
+        """
+        request_token_string = self.get_request_token(credentials)
+        # Hand off control to the end-user.
+        self.make_end_user_authorize_token(credentials, request_token_string)
+        if credentials.access_token is None:
+            # The end-user refused to authorize the application.
+            return None
+        # save() invokes the callback on failure.
+        credential_store.save(credentials, self.unique_consumer_id)
+        return credentials
+
+    def get_request_token(self, credentials):
+        """Get a new request token from the server.
+
+        :param return: The request token.
+        """
+        authorization_json = credentials.get_request_token(
+            web_root=self.web_root,
+            token_format=Credentials.DICT_TOKEN_FORMAT)
+        return authorization_json['oauth_token']
+
+    def make_end_user_authorize_token(self, credentials, request_token):
+        """Authorize the given request token using the given credentials.
+
+        Your subclass must implement this method: it has no default
+        implementation.
+
+        Because an access token may expire or be revoked in the middle
+        of a session, this method may be called at arbitrary points in
+        a launchpadlib session, or even multiple times during a single
+        session (with a different request token each time).
+
+        In most cases, however, this method will be called at the
+        beginning of a launchpadlib session, or not at all.
+        """
+        raise NotImplementedError()
 
 
 class AuthorizeRequestTokenWithBrowser(RequestTokenAuthorizationEngine):
-    """The simplest and most secure request token authorizer.
+    """The simplest (and, right now, the only) request token authorizer.
 
     This authorizer simply opens up the end-user's web browser to a
     Launchpad URL and lets the end-user authorize the request token
     themselves.
     """
 
-    def __init__(self, web_root, consumer_name, request_token,
-                 allow_access_levels=[], max_failed_attempts=3):
-        web_root = uris.lookup_web_root(web_root)
-        page = "+authorize-token?oauth_token=%s" % request_token
-        if len(allow_access_levels) > 0:
-            page += ("&allow_permission=" +
-                     "&allow_permission=".join(allow_access_levels))
-        self.authorization_url = urljoin(web_root, page)
-
+    WAITING_FOR_USER = "The authorization page:\n (%s)\nshould be opening in your browser. Use your browser to authorize\nthis program to access Launchpad on your behalf. \n\nWaiting to hear from Launchpad about your decision..."
+
+    def __init__(self, service_root, application_name, consumer_name=None,
+                 credential_save_failed=None, allow_access_levels=None):
+        """Constructor.
+
+        :param service_root: See `RequestTokenAuthorizationEngine`.
+        :param application_name: See `RequestTokenAuthorizationEngine`.
+        :param consumer_name: The value of this argument is
+            ignored. If we have the capability to open the end-user's
+            web browser, we must be running on the end-user's computer,
+            so we should do a full desktop integration.
+        :param credential_save_failed: See `RequestTokenAuthorizationEngine`.
+        :param allow_access_levels: The value of this argument is
+            ignored, for the same reason as consumer_name.
+        """
+        # It doesn't look like we're doing anything here, but we
+        # are discarding the passed-in values for consumer_name and
+        # allow_access_levels.
         super(AuthorizeRequestTokenWithBrowser, self).__init__(
-            web_root, consumer_name, request_token,
-            allow_access_levels, max_failed_attempts)
-
-    def __call__(self):
-        self.open_page_in_user_browser(self.authorization_url)
-        print "The authorization page:"
-        print "   (%s)" % self.authorization_url
-        print "should be opening in your browser. After you have authorized"
-        print "this program to access Launchpad on your behalf you should come"
-        print ("back here and press <Enter> to finish the authentication "
-               "process.")
-        self.wait_for_request_token_authorization()
-
-    def wait_for_request_token_authorization(self):
-        """Get the end-user to hit enter."""
-        sys.stdin.readline()
+              service_root, application_name, None,
+              credential_save_failed)
+
+    def output(self, message):
+        """Display a message.
+
+        By default, prints the message to standard output. The message
+        does not require any user interaction--it's solely
+        informative.
+        """
+        print message
+
+    def make_end_user_authorize_token(self, credentials, request_token):
+        """Have the end-user authorize the token in their browser."""
+
+        authorization_url = self.authorization_url(request_token)
+        webbrowser.open(authorization_url)
+        self.output(self.WAITING_FOR_USER % authorization_url)
+        while credentials.access_token is None:
+            time.sleep(access_token_poll_time)
+            try:
+                credentials.exchange_request_token_for_access_token(
+                    self.web_root)
+                break
+            except HTTPError, e:
+                if e.response.status == 403:
+                    # The user decided not to authorize this
+                    # application.
+                    raise EndUserDeclinedAuthorization(e.content)
+                elif e.response.status == 401:
+                    # The user has not made a decision yet.
+                    pass
+                else:
+                    # There was an error accessing the server.
+                    print "Unexpected response from Launchpad:"
+                    print e
 
 
 class TokenAuthorizationException(Exception):
@@ -548,6 +566,10 @@
     pass
 
 
+class EndUserDeclinedAuthorization(TokenAuthorizationException):
+    pass
+
+
 class ClientError(TokenAuthorizationException):
     pass
 
 
=== removed file 'src/launchpadlib/docs/browser.txt'
--- src/launchpadlib/docs/browser.txt	2010-12-07 19:30:29 +0000
+++ src/launchpadlib/docs/browser.txt	1970-01-01 00:00:00 +0000
@@ -1,151 +0,0 @@
-*******************************
-The simulated Launchpad browser
-*******************************
-
-The SimulatedLaunchpadBrowser class is a scriptable browser-like class
-that can be trusted with the end-user's username and password. It
-fulfils the same function as the user's web browser, but because it's
-scriptable can be used to create non-browser trusted clients.
-
-    >>> username = '[e-mail]'
-    >>> password = 'zeca'
-    >>> web_root = 'http://launchpad.dev:8085/'
-
-Before showing how SimulatedLaunchpadBrowser can authorize a request
-token, let's create a request token to authorize.
-
-    >>> from launchpadlib.credentials import Credentials
-    >>> credentials = Credentials("doctest consumer")
-    >>> context="firefox"
-    >>> validate_url = credentials.get_request_token(
-    ...     web_root=web_root, context=context)
-    >>> request_token = credentials._request_token.key
-
-get_token_info()
-================
-
-If you have the end-user's username and password, you can use
-get_token_info() to get information about one of the user's request
-tokens. It's useful for confirming that the end-user gave the correct
-username and password, and for reconciling the list of access levels a
-client will accept with Launchpad's master list.
-
-    >>> from launchpadlib.credentials import SimulatedLaunchpadBrowser
-    >>> from launchpadlib.testing.helpers import TestableLaunchpad
-
-    >>> browser = SimulatedLaunchpadBrowser(web_root)
-
-If you make an unauthorized request, you'll get a 401 error.
-(Launchpad returns 200, but SimulatedLaunchpadBrowser sniffs it and
-changes it to a 401.)
-
-    >>> response, content = browser.get_token_info(
-    ...     "baduser", "badpasword", request_token)
-    >>> print response.status
-    401
-
-If you provide the right authorization, you'll get back information
-about your request token.
-
-    >>> response, content = browser.get_token_info(
-    ...     username, password, request_token)
-    >>> print response['content-type']
-    application/json
-
-    # XXX leonardr 2009-10-28 bug=462773 These two URLs should be
-    # exactly the same, but the Content-Location is missing the
-    # lp.context.
-    >>> validate_url.startswith(response['content-location'])
-    True
-
-    >>> import simplejson
-    >>> json = simplejson.loads(content)
-    >>> json['oauth_token'] == request_token
-    True
-
-    >>> print json['oauth_token_consumer']
-    doctest consumer
-
-You'll also get information about the available access
-levels.
-
-    >>> print sorted([level['value'] for level in json['access_levels']])
-    ['READ_PRIVATE', ... 'UNAUTHORIZED', ...]
-
-If you provide a list of possible access levels, you'll
-get back a list that reconciles the list you gave with
-Launchpad's access levels.
-
-    >>> response, content = browser.get_token_info(
-    ...     username, password, request_token,
-    ...     ["READ_PUBLIC", "READ_PRIVATE", "NO_SUCH_ACCESS_LEVEL"])
-
-    >>> print response['content-type']
-    application/json
-
-    >>> json = simplejson.loads(content)
-    >>> print sorted(
-    ...     [level['value'] for level in json['access_levels']])
-    ['READ_PRIVATE', 'READ_PUBLIC', 'UNAUTHORIZED']
-
-Note that the nonexistent access level has been removed from the
-reconciled list, and the "Unauthorized" access level (which must
-always be an option) has been added.
-
-grant_access()
-==============
-
-If you have the end-user's username and password, you can use
-grant_access() to authorize a request token.
-
-If you make an unauthorized request, you'll get a 401 error.  (As with
-get_token_info(), Launchpad returns 200, but SimulatedLaunchpadBrowser
-sniffs it and changes it to a 401.)
-
-    >>> access_level = "READ_PRIVATE"
-
-    >>> response, content = browser.grant_access(
-    ...     "baduser", "badpasword", request_token, access_level, context)
-    >>> print response.status
-    401
-
-If you try to grant an invalid level of access, you'll get a
-400 error.
-
-    >>> response, content = browser.grant_access(
-    ...     username, password, request_token,
-    ...     "NO_SUCH_ACCESS_LEVEL")
-    >>> print response.status
-    400
-
-If you provide all the necessary information, you'll get a 200
-response code and the request token will be authorized.
-
-    >>> response, content = browser.grant_access(
-    ...     username, password, request_token, access_level)
-    >>> print response.status
-    200
-
-If you try to grant access to a request token that's already
-been authorized, you'll get a 409 error.
-
-    >>> response, content = browser.grant_access(
-    ...     username, password, request_token, access_level)
-    >>> print response.status
-    409
-
-Now that the request token is authorized, we can exchange it for an
-access token.
-
-    >>> credentials.exchange_request_token_for_access_token(
-    ...     web_root=web_root)
-    >>> credentials.access_token.key is None
-    False
-
-If you try to grant access to a request token that's already been
-exchanged for an access token, you'll get a 400 error.
-
-    >>> response, content = browser.grant_access(
-    ...     username, password, request_token, access_level)
-    >>> print response.status
-    400
 
=== modified file 'src/launchpadlib/docs/command-line.txt'
--- src/launchpadlib/docs/command-line.txt	2010-12-07 19:30:29 +0000
+++ src/launchpadlib/docs/command-line.txt	2011-02-08 19:01:02 +0000
@@ -2,12 +2,11 @@
 Command-line scripts
 ********************
 
-Launchpad includes some command-line scripts to make Launchpad
+Launchpad includes one command-line script to make Launchpad
 integration easier for third-party libraries that aren't written in
-Python or that can't do token authorization by opening a user's web
-browser.
+Python.
 
-This file tests the workflow underlying the command-line scripts as
+This file tests the workflow underlying the command-line script as
 best it can.
 
 RequestTokenApp
@@ -36,170 +35,3 @@
     >>> print json['oauth_token_consumer']
     consumer
 
-TrustedTokenAuthorizationConsoleApp
-===================================
-
-This class is called by the command-line script
-launchpad-credentials-console. It asks for the user's Launchpad
-username and password, and authorizes a request token on their
-behalf.
-
-    >>> from launchpadlib.apps import TrustedTokenAuthorizationConsoleApp
-    >>> from launchpadlib.testing.helpers import UserInput
-
-This class does not create the request token, or exchange it for the
-access token--that's the job of the program that calls
-launchpad-credentials-console. So we'll use the request token created
-earlier by RequestTokenApp.
-
-    >>> request_token = json['oauth_token']
-
-Since this is a test, we don't want the application to call sys.exit()
-or try to open up pages in a web browser. This subclass of
-TrustedTokenAuthorizationConsoleApp will print messages instead of
-performing such un-doctest-like actions.
-
-    >>> class ConsoleApp(TrustedTokenAuthorizationConsoleApp):
-    ...     def open_page_in_user_browser(self, url):
-    ...         """Print a status message."""
-    ...         self.output("[If this were a real application, the "
-    ...                     "end-user's web browser would be opened "
-    ...                     "to %s]" % url)
-    ...
-    ...     def exit_with(self, code):
-    ...         print "Application exited with code %d" % code
-
-We'll use a UserInput object to simulate a user typing things in at
-the prompt and hitting enter. This UserInput runs the program
-correctly, entering the Launchpad username and password, choosing an
-access level, and hitting Enter to exit.
-
-    >>> username = "[e-mail]"
-    >>> password = "zeca"
-    >>> fake_input = UserInput([username, password, "1", ""])
-
-Here's a successful run of the application. When the request token is
-authorized, the script's response code is 0.
-
-    >>> app = ConsoleApp(
-    ...     web_root, consumer_name, request_token,
-    ...     'READ_PRIVATE, READ_PUBLIC', input_method=fake_input)
-    >>> app.run()
-    Launchpad credential client (console)
-    -------------------------------------
-    An application identified as "consumer" wants to access Launchpad...
-    What email address do you use on Launchpad?
-    (No Launchpad account? Just hit enter.) [User input: [e-mail]]
-    What's your Launchpad password? [User input: zeca]
-    Now it's time for you to decide how much power to give "consumer"...
-    1: Read Non-Private Data
-    2: Read Anything
-    What should "consumer" be allowed to do...? [1-2 or Q] [User input: 1]
-    Okay, I'm telling Launchpad to grant "consumer" access to your account.
-    You're all done!...
-    Press enter to go back to "consumer". [User input: ]
-    Application exited with code 0
-
-Now that the request token has been authorized, we'll need to create
-another one to continue the test.
-
-    >>> json = simplejson.loads(token_app.run())
-    >>> request_token = json['oauth_token']
-    >>> app.request_token = request_token
-
-Invalid input is ignored. The user may enter 'Q' instead of a number
-to refuse to authorize the request token. When the user denies access,
-the exit code is -2.
-
-    >>> fake_input = UserInput([username, password, "A", "99", "Q", ""])
-    >>> app.input_method = fake_input
-    >>> app.run()
-    Launchpad credential client (console)
-    -------------------------------------
-    An application identified as "consumer"...
-    What should "consumer" be allowed to do...? [1-2 or Q] [User input: A]
-    What should "consumer" be allowed to do...? [1-2 or Q] [User input: 99]
-    What should "consumer" be allowed to do...? [1-2 or Q] [User input: Q]
-    Okay, I'm going to cancel the request...
-    You're all done! "consumer" still doesn't have access...
-    <BLANKLINE>
-    Press enter to go back to "consumer". [User input: ]
-    Application exited with code -2
-
-When the third-party application will allow only one level of access,
-the end-user is presented with a yes-or-no choice instead of a list to
-choose from. Again, invalid input is ignored.
-
-    >>> json = simplejson.loads(token_app.run())
-    >>> request_token = json['oauth_token']
-    >>> fake_input = UserInput([username, password, "1", "Q", "Y", ""])
-
-    >>> app = ConsoleApp(
-    ...     web_root, consumer_name, request_token,
-    ...     'READ_PRIVATE', input_method=fake_input)
-
-    >>> app.run()
-    Launchpad credential client (console)
-    -------------------------------------
-    An application identified as "consumer"...
-    Do you want to give "consumer" this level of access? [YN] [User input: 1]
-    Do you want to give "consumer" this level of access? [YN] [User input: Q]
-    Do you want to give "consumer" this level of access? [YN] [User input: Y]
-    ...
-    Application exited with code 0
-
-
-Error handling
---------------
-
-When the end-user refuses to authorize the request token, the app
-exits with a return code of -2, as seen above. When any other error
-gets in the way of the authorization of the request token, the app's
-return code is -1.
-
-If the user hits enter when asked for their email address, indicating
-that they don't have a Launchpad account, the app opens their browser
-to the Launchpad login page.
-
-    >>> json = simplejson.loads(token_app.run())
-    >>> app.request_token = json['oauth_token']
-
-    >>> input_nothing = UserInput(["", ""])
-    >>> app.input_method = input_nothing
-
-    >>> app.run()
-    Launchpad credential client (console)
-    -------------------------------------
-    An application identified as "consumer"...
-    [If this were a real application, the end-user's web browser...]
-    OK, you'll need to get yourself a Launchpad account before...
-    <BLANKLINE>
-    I'm opening the Launchpad registration page in your web browser...
-    Press enter to go back to "consumer". [User input: ]
-    Application exited with code -1
-
-If the user keeps entering bad passwords, the app eventually gives up.
-
-    >>> input_bad_password = UserInput(
-    ...     [username, "badpw", "", "badpw", "", "badpw", ""])
-    >>> json = simplejson.loads(token_app.run())
-    >>> request_token = json['oauth_token']
-    >>> app.request_token = request_token
-    >>> app.input_method = input_bad_password
-    >>> app.run()
-    Launchpad credential client (console)
-    -------------------------------------
-    An application identified as "consumer"...
-    What email address do you use on Launchpad?
-    (No Launchpad account? Just hit enter.)  [User input: [e-mail]]
-    What's your Launchpad password? [User input: badpw]
-    I can't log in with the credentials you gave me. Let's try again.
-    What email address do you use on Launchpad? [[e-mail]] [User input: ]
-    What's your Launchpad password? [User input: badpw]
-    I can't log in with the credentials you gave me. Let's try again.
-    What email address do you use on Launchpad? [[e-mail]] [User input: ]
-    What's your Launchpad password? [User input: badpw]
-    You've failed the password entry too many times...
-    Press enter to go back to "consumer". [User input: ]
-    Application exited with code -1
-
 
=== modified file 'src/launchpadlib/docs/hosted-files.txt'
--- src/launchpadlib/docs/hosted-files.txt	2010-12-07 19:30:29 +0000
+++ src/launchpadlib/docs/hosted-files.txt	2011-02-08 19:01:02 +0000
@@ -55,7 +55,7 @@
     >>> file_handle.close()
     Traceback (most recent call last):
     ...
-    HTTPError: HTTP Error 400: Bad Request
+    BadRequest: HTTP Error 400: Bad Request
     ...
 
 == Caching ==
@@ -90,7 +90,7 @@
     >>> len(mugshot.open().read())
     send: ...
     reply: 'HTTP/1.1 303 See Other...
-    header: Location: http://localhost:58000/.../image.png
+    header: Location: http://.../image.png
     ...
     header: Content-Type: text/plain
     2260
 
=== modified file 'src/launchpadlib/docs/introduction.txt'
--- src/launchpadlib/docs/introduction.txt	2010-12-07 19:30:29 +0000
+++ src/launchpadlib/docs/introduction.txt	2011-02-08 19:01:02 +0000
@@ -66,9 +66,10 @@
     >>> sorted(launchpad.bugs)
     [...]
 
-For convenience, the application may store the credentials on the file system,
-so that the next time Salgado interacts with the application, he won't have
-to go through the whole OAuth request dance.
+If available, the Gnome keyring or KDE wallet will be used to store access
+tokens.  If a keyring/wallet is not available, the application can store the
+credentials on the file system, so that the next time Salgado interacts with
+the application, he won't have to go through the whole OAuth request dance.
 
     >>> import os
     >>> import tempfile
@@ -172,14 +173,14 @@
     >>> launchpad.me
     Traceback (most recent call last):
     ...
-    HTTPError: HTTP Error 401: Unauthorized
+    Unauthorized: HTTP Error 401: Unauthorized
     ...
 
     >>> salgado.display_name = "This won't work."
     >>> salgado.lp_save()
     Traceback (most recent call last):
     ...
-    HTTPError: HTTP Error 401: Unauthorized
+    Unauthorized: HTTP Error 401: Unauthorized
     ...
 
 Convenience
@@ -189,34 +190,24 @@
 setting up a web service connection in one function call. All you have
 to provide is the consumer name.
 
-    >>> launchpad = Launchpad.login_anonymously('launchpad-library')
+    >>> launchpad = Launchpad.login_anonymously(
+    ...     'launchpad-library', service_root="test_dev")
     >>> sorted(launchpad.people)
     [...]
 
     >>> launchpad.me
     Traceback (most recent call last):
     ...
-    HTTPError: HTTP Error 401: Unauthorized
+    Unauthorized: HTTP Error 401: Unauthorized
     ...
 
-Another function call is useful when the consumer name, access token
-and access secret are all known up-front.
-
-    >>> launchpad = Launchpad.login(
-    ...     'launchpad-library', 'salgado-change-anything', 'test')
-    >>> sorted(launchpad.people)
-    [...]
-
-    >>> print launchpad.me.name
-    salgado
-
 Otherwise, the application should obtain authorization from the user
-and get a new set of credentials directly from Launchpad.
+and get a new set of credentials directly from
+Launchpad.
 
-First we must get a request token. We use 'test_dev' as a shorthand
-for the root URL of the Launchpad installation. It's defined in the
-'uris' module as 'http://launchpad.dev:8085/', and the launchpadlib
-code knows how to dereference it before using it as a URL.
+Unfortunately, we can't test this entire process because it requires
+opening up a web browser, but we can test the first step, which is to
+get a request token.
 
     >>> import launchpadlib.credentials
     >>> credentials = Credentials('consumer')
@@ -226,6 +217,11 @@
     >>> authorization_url
     'http://launchpad.dev:8085/+authorize-token?oauth_token=...&lp.context=firefox'
 
+We use 'test_dev' as a shorthand for the root URL of the Launchpad
+installation. It's defined in the 'uris' module as
+'http://launchpad.dev:8085/', and the launchpadlib code knows how to
+dereference it before using it as a URL.
+
 Information about the request token is kept in the _request_token
 attribute of the Credentials object.
 
@@ -236,117 +232,10 @@
     >>> print credentials._request_token.context
     firefox
 
-Now the user must authorize that token, so we'll use the
-SimulatedLaunchpadBrowser to pretend the user is authorizing it.
-
-    >>> from launchpadlib.credentials import SimulatedLaunchpadBrowser
-    >>> browser = SimulatedLaunchpadBrowser(web_root='test_dev')
-    >>> response, content = browser.grant_access(
-    ...     "[e-mail]", "test",
-    ...     credentials._request_token.key, "WRITE_PRIVATE",
-    ...     credentials._request_token.context)
-    >>> response['status']
-    '200'
-
-After that we can exchange that request token for an access token.
-
-    >>> credentials.exchange_request_token_for_access_token(
-    ...     web_root='test_dev')
-
-Once that's done, our credentials will be complete and ready to use.
-
-    >>> credentials.consumer.key
-    'consumer'
-    >>> credentials.access_token
-    <launchpadlib.credentials.AccessToken...
-    >>> credentials.access_token.key is not None
-    True
-    >>> credentials.access_token.secret is not None
-    True
-    >>> credentials.access_token.context
-    'firefox'
-
-Authorizing the request token
------------------------------
-
-There are also two convenience method which do the access token
-negotiation and log into the web service: get_token_and_login() and
-login_with(). These convenience methods use the methods documented
-above to get a request token, and once it has the request token's
-authorization information, it makes the end-user authorize the request
-token by entering their Launchpad username and password.
-
-There are several ways of having the end-user authorize a request
-token, but the most secure is to open up the user's own web browser
-(other ways are described in trusted-client.txt). Because we don't
-want to actually open a web browser during this test, we'll create a
-fake authorizer that uses the SimulatedLaunchpadBrowser to authorize
-the request token.
-
-    >>> from launchpadlib.testing.helpers import (
-    ...     DummyAuthorizeRequestTokenWithBrowser)
-
-    >>> class AuthorizeAsSalgado(DummyAuthorizeRequestTokenWithBrowser):
-    ...     def wait_for_request_token_authorization(self):
-    ...         """Simulate the authorizing user with their web browser."""
-    ...         username = '[e-mail]'
-    ...         password = 'zeca'
-    ...         browser = SimulatedLaunchpadBrowser(self.web_root)
-    ...         browser.grant_access(username, password, self.request_token,
-    ...                              'READ_PUBLIC')
-
-Here, we're using 'test_dev' as shorthand for the root URL of the web
-service. Earlier we used 'test_dev' as shorthand for the website URL,
-and like in that earlier case, launchpadlib will internally
-dereference 'test_dev' into the service root URL, defined in the
-'uris' module as "http://api.launchpad.dev:8085/".
-
-    >>> consumer_name = 'launchpadlib'
-    >>> launchpad = Launchpad.get_token_and_login(
-    ...     consumer_name, service_root="test_dev",
-    ...     authorizer_class=AuthorizeAsSalgado)
-    [If this were a real application, the end-user's web browser would
-    be opened to http://launchpad.dev:8085/+authorize-token?oauth_token=...]
-    The authorization page:
-    (http://launchpad.dev:8085/+authorize-token?oauth_token=...)
-    should be opening in your browser. After you have authorized
-    this program to access Launchpad on your behalf you should come
-    back here and press <Enter> to finish the authentication process.
-
-The login_with method will cache an access token once it gets one, so
-that the end-user doesn't have to authorize a request token every time
-they run the program.
-
-    >>> import tempfile
-    >>> cache_dir = tempfile.mkdtemp()
-    >>> launchpad = Launchpad.login_with(
-    ...     consumer_name, service_root="test_dev",
-    ...     launchpadlib_dir=cache_dir,
-    ...     authorizer_class=AuthorizeAsSalgado)
-    [If this were a real application...]
-    The authorization page:
-    ...
-    >>> print launchpad.me.name
-    salgado
-
-Now that the access token is authorized, we can call login_with()
-again and pass in a null authorizer. If there was no access token,
-this would fail, because there would be no way to authorize the
-request token. But since there's an access token cached in the
-cache directory, login_with() will succeed without even trying to
-authorize a request token.
-
-    >>> launchpad = Launchpad.login_with(
-    ...     consumer_name, service_root="test_dev",
-    ...     launchpadlib_dir=cache_dir,
-    ...     authorizer_class=None)
-    >>> print launchpad.me.name
-    salgado
-
-A bit of clean-up: removing the cache directory.
-
-    >>> import shutil
-    >>> shutil.rmtree(cache_dir)
+Now the user must authorize that token, and this is the part we can't
+test--it requires opening a web browser. Once the token is authorized
+on the server side, we can call exchange_request_token_for_access_token()
+on our Credentials object, which will then be ready to use.
 
 The dictionary request token
 ============================
@@ -470,7 +359,7 @@
     >>> launchpad = Launchpad(credentials=credentials)
     Traceback (most recent call last):
     ...
-    HTTPError: HTTP Error 401: Unauthorized
+    Unauthorized: HTTP Error 401: Unauthorized
     ...
 
 The application is not allowed to access Launchpad with a consumer
@@ -483,7 +372,7 @@
     >>> launchpad = Launchpad(credentials=credentials)
     Traceback (most recent call last):
     ...
-    HTTPError: HTTP Error 401: Unauthorized
+    Unauthorized: HTTP Error 401: Unauthorized
     ...
 
 The application is not allowed to access Launchpad with a bad access secret.
@@ -495,7 +384,7 @@
     >>> launchpad = Launchpad(credentials=credentials)
     Traceback (most recent call last):
     ...
-    HTTPError: HTTP Error 401: Unauthorized
+    Unauthorized: HTTP Error 401: Unauthorized
     ...
 
 Clean up
 
=== added file 'src/launchpadlib/docs/operations.txt'
--- src/launchpadlib/docs/operations.txt	1970-01-01 00:00:00 +0000
+++ src/launchpadlib/docs/operations.txt	2011-02-08 19:01:02 +0000
@@ -0,0 +1,27 @@
+****************
+Named operations
+****************
+
+launchpadlib can transparently determine the size of the list even
+when the size is not directly provided, but is only available through
+a link.
+
+    >>> from launchpadlib.testing.helpers import salgado_with_full_permissions
+    >>> launchpad = salgado_with_full_permissions.login(version="devel")
+
+    >>> results = launchpad.people.find(text='s')
+    >>> 'total_size' in results._wadl_resource.representation.keys()
+    False
+    >>> 'total_size_link' in results._wadl_resource.representation.keys()
+    True
+    >>> len(results) > 1
+    True
+
+Of course, launchpadlib can also determine the size when the size _is_
+directly provided.
+
+    >>> results = launchpad.people.find(text='salgado')
+    >>> 'total_size' in results._wadl_resource.representation.keys()
+    True
+    >>> len(results) == 1
+    True
 
=== modified file 'src/launchpadlib/docs/people.txt'
--- src/launchpadlib/docs/people.txt	2010-12-07 19:30:29 +0000
+++ src/launchpadlib/docs/people.txt	2011-02-08 19:01:02 +0000
@@ -159,7 +159,7 @@
     >>> launchpad.people.newTeam(name='bassists', display_name='Bass Gods')
     Traceback (most recent call last):
     ...
-    HTTPError: HTTP Error 400: Bad Request
+    BadRequest: HTTP Error 400: Bad Request
     ...
 
 Actually, the exception contains other useful information.
 
=== modified file 'src/launchpadlib/docs/toplevel.txt'
--- src/launchpadlib/docs/toplevel.txt	2010-12-07 19:30:29 +0000
+++ src/launchpadlib/docs/toplevel.txt	2011-02-08 19:01:02 +0000
@@ -13,10 +13,16 @@
 collections. The bug collection does lookups by bug ID.
 
     >>> bug = launchpad.bugs[1]
-
-For most top-level collections, simply looking up an object will not
-trigger an HTTP request. The HTTP request happens when you try to
-access one of the object's properties.
+    send: 'GET /.../bugs/1 ...'
+    ...
+
+To avoid triggering an HTTP request when simply looking up an object,
+you can use a different syntax:
+
+    >>> bug = launchpad.bugs(1)
+
+The HTTP request will happen when you need information that can only
+be obtained from the web service.
 
     >>> print bug.id
     send: 'GET /.../bugs/1 ...'
@@ -26,7 +32,7 @@
 Let's look at some more collections. The project collection does
 lookups by project name.
 
-    >>> project = launchpad.projects['firefox']
+    >>> project = launchpad.projects('firefox')
     >>> print project.name
     send: 'GET /.../firefox ...'
     ...
@@ -34,7 +40,7 @@
 
 The project group collection does lookups by project group name.
 
-    >>> group = launchpad.project_groups['gnome']
+    >>> group = launchpad.project_groups('gnome')
     >>> print group.name
     send: 'GET /.../gnome ...'
     ...
@@ -42,7 +48,7 @@
 
 The distribution collection does lookups by distribution name.
 
-    >>> distribution = launchpad.distributions['ubuntu']
+    >>> distribution = launchpad.distributions('ubuntu')
     >>> print distribution.name
     send: 'GET /.../ubuntu ...'
     ...
@@ -51,13 +57,13 @@
 The person collection does lookups by a person's Launchpad
 name.
 
-    >>> person = launchpad.people['salgado']
+    >>> person = launchpad.people('salgado')
     >>> print person.name
     send: 'GET /.../~salgado ...'
     ...
     salgado
 
-    >>> team = launchpad.people['rosetta-admins']
+    >>> team = launchpad.people('rosetta-admins')
     >>> print team.name
     send: 'GET /1.0/~rosetta-admins ...'
     ...
@@ -77,11 +83,11 @@
     True
 
 The truth is that it doesn't know, not before making that HTTP
-request. Until the HTTP request is made, launchpadlib assumes
+request. Until an HTTP request is made, launchpadlib assumes
 everything in launchpad.people[] is a team (since a team has strictly
 more capabilities than a person).
 
-    >>> person2 = launchpad.people['salgado']
+    >>> person2 = launchpad.people('salgado')
     >>> 'default_membership_period' in person2.lp_attributes
     True
 
@@ -101,7 +107,7 @@
 the HTTP request, and then cause an error if the object turns out not
 to be a team.
 
-    >>> person3 = launchpad.people['salgado']
+    >>> person3 = launchpad.people('salgado')
     >>> person3.default_membership_period
     Traceback (most recent call last):
     AttributeError: 'Entry' object has no attribute 'default_membership_period'
 
=== removed file 'src/launchpadlib/docs/trusted-client.txt'
--- src/launchpadlib/docs/trusted-client.txt	2010-12-07 19:30:29 +0000
+++ src/launchpadlib/docs/trusted-client.txt	1970-01-01 00:00:00 +0000
@@ -1,224 +0,0 @@
-***********************
-Making a trusted client
-***********************
-
-To authorize a request token, the end-user must type in their
-Launchpad username and password. Obviously, typing your password into
-a random program is a bad idea. The best case is to use a program you
-already trust with your Launchpad password: your web browser.
-
-But if you're writing an application that can't open the end-user's
-web browser, or you just really want a token authorization client that
-has the same UI as the rest of your application, you should use one of
-the trusted clients packaged with launchpadlib, rather than writing
-your own client.
-
-All the trusted clients are based on the same core code and implement
-the same workflow. This test implements a scriptable trusted client
-and uses it to test the behavior of the standard workflow.
-
-    >>> from launchpadlib.testing.helpers import (
-    ...     ScriptableRequestTokenAuthorization)
-
-Here we see the normal workflow, in which the user inputs all the
-correct data to authorize a request token.
-
-    >>> auth = ScriptableRequestTokenAuthorization(
-    ...     "consumer", "[e-mail]", "zeca",
-    ...     "WRITE_PRIVATE",
-    ...     allow_access_levels = ["WRITE_PUBLIC", "WRITE_PRIVATE"])
-    >>> access_token = auth()
-    An application identified as "consumer" wants to access Launchpad...
-    <BLANKLINE>
-    I'll use your Launchpad password to give "consumer" limited access...
-    What email address do you use on Launchpad?
-    What's your Launchpad password?
-    Now it's time for you to decide how much power to give "consumer" ...
-    ['UNAUTHORIZED', 'WRITE_PUBLIC', 'WRITE_PRIVATE']
-    Okay, I'm telling Launchpad to grant "consumer" access to your account.
-    You're all done! You should now be able to use Launchpad ...
-
-Ordinarily, the third-party program will create a request token and
-pass it into the trusted client. The test class is a little unusual:
-it takes care of creating the request token and, after the end-user
-has authorized it, exchanges the request token for an access
-token. This way we can verify that the entire end-to-end process
-works.
-
-    >>> access_token.key is not None
-    True
-
-Denying access
-==============
-
-It's always possible for the end-user to deny access to the
-application. This will make it impossible to convert the request token
-into an access token.
-
-    >>> auth = ScriptableRequestTokenAuthorization(
-    ...     "consumer", "[e-mail]", "zeca", "UNAUTHORIZED")
-    >>> access_token = auth()
-    An application identified as "consumer" wants to access Launchpad...
-    What email address do you use on Launchpad?
-    ...
-    Okay, I'm going to cancel the request that "consumer" made...
-    You're all done! "consumer" still doesn't have access...
-
-    >>> access_token is None
-    True
-
-Only one allowable access level
-===============================
-
-When the application being authenticated only allows one access level,
-the authorizer creates a special message for display to the end-user.
-
-    >>> auth = ScriptableRequestTokenAuthorization(
-    ...     "consumer", "[e-mail]", "zeca",
-    ...     "WRITE_PRIVATE", allow_access_levels=["WRITE_PRIVATE"])
-
-    >>> auth()
-    An application identified as "consumer" wants to access Launchpad ...
-    ...
-    "consumer" says it needs the following level of access to your Launchpad
-    account: "Change Anything". It can't work with any other level of access,
-    so denying this level of access means prohibiting "consumer" from
-    using your Launchpad account at all.
-    ...
-
-Error handling
-==============
-
-Things can go wrong in many ways, most of which we can test with our
-scriptable authorizer. Here's a utility method to run the
-authorization process with a badly-scripted authorizer and print the
-resulting exception.
-
-    >>> from launchpadlib.credentials import TokenAuthorizationException
-    >>> def print_error(auth):
-    ...     try:
-    ...         auth()
-    ...     except TokenAuthorizationException, e:
-    ...         print str(e)
-
-Authentication failures
------------------------
-
-If the user doesn't have a Launchpad account, or refuses to type in
-their email address, the authorizer will open their web browser to the
-login page, and raise an exception.
-
-    >>> auth = ScriptableRequestTokenAuthorization(
-    ...     "consumer", None, "zeca", "WRITE_PRIVATE")
-    >>> print_error(auth)
-    An application identified as "consumer" wants to access Launchpad ...
-    [If this were a real application, ... opened to http://launchpad.dev:8085/+login]
-    OK, you'll need to get yourself a Launchpad account before you can ...
-    <BLANKLINE>
-    I'm opening the Launchpad registration page in your web browser ...
-
-If the user enters the wrong username/password combination too many
-times, the authorizer will give up and raise an exception.
-
-    >>> auth = ScriptableRequestTokenAuthorization(
-    ...     "consumer", "[e-mail]", "baddpassword",
-    ...     "WRITE_PRIVATE")
-    >>> print_error(auth)
-    An application identified as "consumer" wants to access Launchpad...
-    ...
-    What email address do you use on Launchpad?
-    What's your Launchpad password?
-    I can't log in with the credentials you gave me. Let's try again.
-    What email address do you use on Launchpad?
-    Cached email address: [e-mail]
-    What's your Launchpad password?
-    You've failed the password entry too many times...
-
-The max_failed_attempts argument controls how many attempts the user
-is given to enter their username and password.
-
-    >>> auth = ScriptableRequestTokenAuthorization(
-    ...     "consumer", "bad username", "zeca",
-    ...     "WRITE_PRIVATE", max_failed_attempts=1)
-    >>> print_error(auth)
-    An application identified as "consumer" wants to access Launchpad ...
-    What email address do you use on Launchpad?
-    What's your Launchpad password?
-    You've failed the password entry too many times...
-
-Approving a token that was already approved
--------------------------------------------
-
-To set this up, let's approve a request token but not exchange it for
-an access token.
-
-    >>> auth = ScriptableRequestTokenAuthorization(
-    ...     "consumer", "[e-mail]", "zeca",
-    ...     "WRITE_PRIVATE")
-    >>> auth(exchange_for_access_token=False)
-    An application identified as "consumer" wants to access Launchpad ...
-    ...
-
-Now let's try to approve the request token again:
-
-    >>> print_error(auth)
-    An application identified as "consumer" wants to access Launchpad ...
-    ...
-    It looks like you already approved this request...
-
-Once the request token is exchanged for an access token, it's
-deleted. An attempt to approve a request token that's already been
-exchanged for an access token gives an error message.
-
-    >>> auth.credentials.exchange_request_token_for_access_token(
-    ...     web_root=auth.web_root)
-
-    >>> print_error(auth)
-    An application identified as "consumer" wants to access Launchpad ...
-    ...
-    Launchpad couldn't find an outstanding request for integration...
-
-An attempt to approve a nonexistent request token gives the same error
-message.
-
-    >>> auth = ScriptableRequestTokenAuthorization(
-    ...     "consumer", "[e-mail]", "zeca",
-    ...     "WRITE_PRIVATE")
-    >>> auth.request_token = "nosuchrequesttoken"
-    >>> print_error(auth)
-    An application identified as "consumer" wants to access Launchpad ...
-    ...
-    Launchpad couldn't find an outstanding request for integration...
-
-Miscellaneous error
--------------------
-
-Random errors on the server side or (occasionally) the client side
-will result in a generic error message.
-
-    >>> auth.request_token = "this token will confuse launchpad badly"
-    >>> print_error(auth)
-    An application identified as "consumer" wants to access Launchpad ...
-    ...
-    There seems to be something wrong on the Launchpad server side...
-
-Client duplicity
-----------------
-
-If the third-party client gives one consumer name to Launchpad, and a
-different consumer name to the authorizer, the authorizer will detect
-this possible duplicity and print a warning.
-
-    >>> auth = ScriptableRequestTokenAuthorization(
-    ...     "consumer1", "[e-mail]", "zeca",
-    ...     "WRITE_PRIVATE")
-
-We'll simulate this by changing the authorizer's .consumer_name after
-it obtained a request token from Launchpad.
-
-    >>> auth.consumer_name = "consumer2"
-    >>> auth()
-    An application identified as "consumer2" wants to access Launchpad ...
-    ...
-    WARNING: The application you're using told me its name was "consumer2", but it told Launchpad its name was "consumer1"...
-    ...
 
=== modified file 'src/launchpadlib/launchpad.py'
--- src/launchpadlib/launchpad.py	2010-12-07 19:30:29 +0000
+++ src/launchpadlib/launchpad.py	2011-02-08 19:01:02 +0000
@@ -22,21 +22,33 @@
     ]
 
 import os
-import stat
 import urlparse
+import warnings
 
-from lazr.uri import URI
 from lazr.restfulclient.resource import (
-    CollectionWithKeyBasedLookup, HostedFile, ServiceRoot)
+    CollectionWithKeyBasedLookup,
+    HostedFile,           # Re-import for client convenience
+    ScalarValue,          # Re-import for client convenience
+    ServiceRoot,
+    )
+from lazr.restfulclient.authorize.oauth import SystemWideConsumer
+from lazr.restfulclient._browser import RestfulHttp
 from launchpadlib.credentials import (
-    AccessToken, AnonymousAccessToken, Credentials,
-    AuthorizeRequestTokenWithBrowser)
+    AccessToken,
+    AnonymousAccessToken,
+    AuthorizeRequestTokenWithBrowser,
+    Consumer,
+    Credentials,
+    KeyringCredentialStore,
+    UnencryptedFileCredentialStore,
+    )
 from launchpadlib import uris
 
+
 # Import some constants for backwards compatibility. This way, old
-# scripts that have 'from launchpad import EDGE_SERVICE_ROOT' will still
+# scripts that have 'from launchpad import STAGING_SERVICE_ROOT' will still
 # work.
-from launchpadlib.uris import EDGE_SERVICE_ROOT, STAGING_SERVICE_ROOT
+from launchpadlib.uris import STAGING_SERVICE_ROOT
 OAUTH_REALM = 'https://api.launchpad.net'
 
 
@@ -96,6 +108,41 @@
     collection_of = 'distribution'
 
 
+class LaunchpadOAuthAwareHttp(RestfulHttp):
+    """Detects expired/invalid OAuth tokens and tries to get a new token."""
+
+    def __init__(self, launchpad, authorization_engine, *args):
+        self.launchpad = launchpad
+        self.authorization_engine = authorization_engine
+        super(LaunchpadOAuthAwareHttp, self).__init__(*args)
+
+    def _bad_oauth_token(self, response, content):
+        """Helper method to detect an error caused by a bad OAuth token."""
+        return (response.status == 401 and
+                (content.startswith("Expired token")
+                 or content.startswith("Invalid token")))
+
+    def _request(self, *args):
+        response, content = super(
+            LaunchpadOAuthAwareHttp, self)._request(*args)
+        return self.retry_on_bad_token(response, content, *args)
+
+    def retry_on_bad_token(self, response, content, *args):
+        """If the response indicates a bad token, get a new token and retry.
+
+        Otherwise, just return the response.
+        """
+        if (self._bad_oauth_token(response, content)
+            and self.authorization_engine is not None):
+            # This access token is bad. Scrap it and create a new one.
+            self.launchpad.credentials.access_token = None
+            self.authorization_engine(
+                self.launchpad.credentials, self.launchpad.credential_store)
+            # Retry the request with the new credentials.
+            return self._request(*args)
+        return response, content
+
+
 class Launchpad(ServiceRoot):
     """Root Launchpad API class.
 
@@ -108,19 +155,26 @@
     RESOURCE_TYPE_CLASSES = {
             'bugs': BugSet,
             'distributions': DistributionSet,
-            'HostedFile': HostedFile,
             'people': PersonSet,
             'project_groups': ProjectGroupSet,
             'projects': ProjectSet,
             }
+    RESOURCE_TYPE_CLASSES.update(ServiceRoot.RESOURCE_TYPE_CLASSES)
 
-    def __init__(self, credentials, service_root=uris.STAGING_SERVICE_ROOT,
+    def __init__(self, credentials, authorization_engine,
+                 credential_store, service_root=uris.STAGING_SERVICE_ROOT,
                  cache=None, timeout=None, proxy_info=None,
                  version=DEFAULT_VERSION):
         """Root access to the Launchpad API.
 
         :param credentials: The credentials used to access Launchpad.
         :type credentials: `Credentials`
+        :param authorization_engine: The object used to get end-user input
+            for authorizing OAuth request tokens. Used when an OAuth
+            access token expires or becomes invalid during a
+            session, or is discovered to be invalid once launchpadlib
+            starts up.
+        :type authorization_engine: `RequestTokenAuthorizationEngine`
         :param service_root: The URL to the root of the web service.
         :type service_root: string
         """
@@ -134,22 +188,48 @@
                      "the version name from the root URI." % version)
             raise ValueError(error)
 
+        self.credential_store = credential_store
+
+        # We already have an access token, but it might expire or
+        # become invalid during use. Store the authorization engine in
+        # case we need to authorize a new token during use.
+        self.authorization_engine = authorization_engine
+
         super(Launchpad, self).__init__(
             credentials, service_root, cache, timeout, proxy_info, version)
 
+    def httpFactory(self, credentials, cache, timeout, proxy_info):
+        return LaunchpadOAuthAwareHttp(
+            self, self.authorization_engine, credentials, cache, timeout,
+            proxy_info)
+
+    @classmethod
+    def authorization_engine_factory(cls, *args):
+        return AuthorizeRequestTokenWithBrowser(*args)
+
+    @classmethod
+    def credential_store_factory(cls, credential_save_failed):
+        return KeyringCredentialStore(credential_save_failed)
+
     @classmethod
     def login(cls, consumer_name, token_string, access_secret,
               service_root=uris.STAGING_SERVICE_ROOT,
               cache=None, timeout=None, proxy_info=None,
-              version=DEFAULT_VERSION):
-        """Convenience for setting up access credentials.
+              authorization_engine=None, allow_access_levels=None,
+              max_failed_attempts=None, credential_store=None,
+              credential_save_failed=None, version=DEFAULT_VERSION):
+        """Convenience method for setting up access credentials.
 
         When all three pieces of credential information (the consumer
         name, the access token and the access secret) are available, this
         method can be used to quickly log into the service root.
 
-        :param consumer_name: the consumer name, as appropriate for the
-            `Consumer` constructor
+        This method is deprecated as of launchpadlib version
+        1.9.0. You should use Launchpad.login_anonymously() for
+        anonymous access, and Launchpad.login_with() for all other
+        purposes.
+
+        :param consumer_name: the application name.
         :type consumer_name: string
         :param token_string: the access token, as appropriate for the
             `AccessToken` constructor
@@ -159,61 +239,125 @@
         :type access_secret: string
         :param service_root: The URL to the root of the web service.
         :type service_root: string
+        :param authorization_engine: See `Launchpad.__init__`. If you don't
+            provide an authorization engine, a default engine will be
+            constructed using your values for `service_root` and
+            `credential_save_failed`.
+        :param allow_access_levels: This argument is ignored, and only
+            present to preserve backwards compatibility.
+        :param max_failed_attempts: This argument is ignored, and only
+            present to preserve backwards compatibility.
         :return: The web service root
         :rtype: `Launchpad`
         """
+        cls._warn_of_deprecated_login_method("login")
         access_token = AccessToken(token_string, access_secret)
         credentials = Credentials(
             consumer_name=consumer_name, access_token=access_token)
-        return cls(credentials, service_root, cache, timeout, proxy_info,
-                   version)
+        if authorization_engine is None:
+            authorization_engine = cls.authorization_engine_factory(
+                service_root, consumer_name, allow_access_levels)
+        if credential_store is None:
+            credential_store = cls.credential_store_factory(
+                credential_save_failed)
+        return cls(credentials, authorization_engine, credential_store,
+                   service_root, cache, timeout, proxy_info, version)
 
     @classmethod
     def get_token_and_login(cls, consumer_name,
                             service_root=uris.STAGING_SERVICE_ROOT,
                             cache=None, timeout=None, proxy_info=None,
-                            authorizer_class=AuthorizeRequestTokenWithBrowser,
-                            allow_access_levels=[], max_failed_attempts=3,
+                            authorization_engine=None, allow_access_levels=[],
+                            max_failed_attempts=None, credential_store=None,
+                            credential_save_failed=None,
                             version=DEFAULT_VERSION):
         """Get credentials from Launchpad and log into the service root.
 
-        This is a convenience method which will open up the user's preferred
-        web browser and thus should not be used by most applications.
-        Applications should, instead, use Credentials.get_request_token() to
-        obtain the authorization URL and
-        Credentials.exchange_request_token_for_access_token() to obtain the
-        actual OAuth access token.
-
-        This method will negotiate an OAuth access token with the service
-        provider, but to complete it we will need the user to log into
-        Launchpad and authorize us, so we'll open the authorization page in
-        a web browser and ask the user to come back here and tell us when they
-        finished the authorization process.
-
-        :param consumer_name: The consumer name, as appropriate for the
-            `Consumer` constructor
+        This method is deprecated as of launchpadlib version
+        1.9.0. You should use Launchpad.login_anonymously() for
+        anonymous access and Launchpad.login_with() for all other
+        purposes.
+
+        :param consumer_name: Either a consumer name, as appropriate for
+            the `Consumer` constructor, or a premade Consumer object.
         :type consumer_name: string
         :param service_root: The URL to the root of the web service.
         :type service_root: string
+        :param authorization_engine: See `Launchpad.__init__`. If you don't
+            provide an authorization engine, a default engine will be
+            constructed using your values for `service_root` and
+            `credential_save_failed`.
+        :param allow_access_levels: This argument is ignored, and only
+            present to preserve backwards compatibility.
         :return: The web service root
         :rtype: `Launchpad`
         """
-        credentials = Credentials(consumer_name)
-        service_root = uris.lookup_service_root(service_root)
-        web_root_uri = URI(service_root)
-        web_root_uri.path = ""
-        web_root_uri.host = web_root_uri.host.replace("api.", "", 1)
-        web_root = str(web_root_uri.ensureSlash())
-        authorization_json = credentials.get_request_token(
-            web_root=web_root, token_format=Credentials.DICT_TOKEN_FORMAT)
-        authorizer = authorizer_class(
-            web_root, authorization_json['oauth_token_consumer'],
-            authorization_json['oauth_token'], allow_access_levels,
-            max_failed_attempts)
-        authorizer()
-        credentials.exchange_request_token_for_access_token(web_root)
-        return cls(credentials, service_root, cache, timeout, proxy_info,
-                   version)
+        cls._warn_of_deprecated_login_method("get_token_and_login")
+        return cls._authorize_token_and_login(
+            consumer_name, service_root, cache, timeout, proxy_info,
+            authorization_engine, allow_access_levels,
+            credential_store, credential_save_failed, version)
+
+    @classmethod
+    def _authorize_token_and_login(
+        cls, consumer_name, service_root, cache, timeout, proxy_info,
+        authorization_engine, allow_access_levels, credential_store,
+        credential_save_failed, version):
+        """Authorize a request token. Log in with the resulting access token.
+
+        This is the private, non-deprecated implementation of the
+        deprecated method get_token_and_login(). Once
+        get_token_and_login() is removed, this code can be streamlined
+        and moved into its other call site, login_with().
+        """
+        if isinstance(consumer_name, Consumer):
+            consumer = consumer_name
+        else:
+            # Create a system-wide consumer. lazr.restfulclient won't
+            # do this automatically, but launchpadlib's default is to
+            # do a desktop-wide integration.
+            consumer = SystemWideConsumer(consumer_name)
+
+        # Create the credentials with no Consumer, then set its .consumer
+        # property directly.
+        credentials = Credentials(None)
+        credentials.consumer = consumer
+        if authorization_engine is None:
+            authorization_engine = cls.authorization_engine_factory(
+                service_root, consumer_name, None, allow_access_levels)
+        if credential_store is None:
+            credential_store = cls.credential_store_factory(
+                credential_save_failed)
+        else:
+            # A credential store was passed in, so we won't be using
+            # any provided value for credential_save_failed. But at
+            # least make sure we weren't given a conflicting value,
+            # since that makes the calling code look confusing.
+            cls._assert_login_argument_consistency(
+                "credential_save_failed", credential_save_failed,
+                credential_store.credential_save_failed,
+                "credential_store")
+
+        # Try to get the credentials out of the credential store.
+        cached_credentials = credential_store.load(
+            authorization_engine.unique_consumer_id)
+        if cached_credentials is None:
+            # They're not there. Acquire new credentials using the
+            # authorization engine.
+            credentials = authorization_engine(credentials, credential_store)
+        else:
+            # We acquired credentials. But, the application name
+            # wasn't stored along with the credentials, because in a
+            # desktop integration scenario, a single set of
+            # credentials may be shared by many applications. We need
+            # to set the application name for this specific instance
+            # of the credentials.
+            credentials = cached_credentials
+            credentials.consumer.application_name = (
+                authorization_engine.application_name)
+
+        return cls(credentials, authorization_engine, credential_store,
+                   service_root, cache, timeout, proxy_info, version)
 
     @classmethod
     def login_anonymously(
@@ -225,76 +369,207 @@
          service_root_dir) = cls._get_paths(service_root, launchpadlib_dir)
         token = AnonymousAccessToken()
         credentials = Credentials(consumer_name, access_token=token)
-        return cls(credentials, service_root=service_root, cache=cache_path,
-                   timeout=timeout, proxy_info=proxy_info, version=version)
+        return cls(credentials, None, None, service_root=service_root,
+                   cache=cache_path, timeout=timeout, proxy_info=proxy_info,
+                   version=version)
 
     @classmethod
-    def login_with(cls, consumer_name,
+    def login_with(cls, application_name=None,
                    service_root=uris.STAGING_SERVICE_ROOT,
                    launchpadlib_dir=None, timeout=None, proxy_info=None,
-                   authorizer_class=AuthorizeRequestTokenWithBrowser,
-                   allow_access_levels=[], max_failed_attempts=3,
-                   credentials_file=None, version=DEFAULT_VERSION):
-        """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
-        `credentials_file`, or if not given, into the `launchpadlib_dir`
-        directory. If the same `credentials_file`/`launchpadlib_dir` is passed
-        in a second time, the credentials in 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
+                   authorization_engine=None, allow_access_levels=None,
+                   max_failed_attempts=None, credentials_file=None,
+                   version=DEFAULT_VERSION, consumer_name=None,
+                   credential_save_failed=None, credential_store=None):
+        """Log in to Launchpad, possibly acquiring and storing credentials.
+
+        Use this method to get a `Launchpad` object. If the end-user
+        has no cached Launchpad credential, their browser will open
+        and they'll be asked to log in and authorize a desktop
+        integration. The authorized Launchpad credential will be
+        stored securely: in the GNOME keyring, the KDE Wallet, or in
+        an encrypted file on disk.
+
+        The next time your program (or any other program run by that
+        user on the same computer) invokes this method, the end-user
+        will be prompted to unlock their keyring (or equivalent), and
+        the credential will be retrieved from local storage and
+        reused.
+
+        You can customize this behavior in three ways:
+
+        1. Pass in a filename to `credentials_file`. The end-user's
+           credential will be written to that file, and on subsequent
+           runs read from that file.
+
+        2. Subclass `CredentialStore` and pass in an instance of the
+           subclass as `credential_store`. This lets you change how
+           the end-user's credential is stored and retrieved locally.
+
+        3. Subclass `RequestTokenAuthorizationEngine` and pass in an
+           instance of the subclass as `authorization_engine`. This
+           lets you change change what happens when the end-user needs
+           to authorize the Launchpad credential.
+
+        :param application_name: The application name. This is *not*
+            the OAuth consumer name. Unless a consumer_name is also
+            provided, the OAuth consumer will be a system-wide
+            consumer representing the end-user's computer as a whole.
+        :type application_name: string
+
         :param service_root: The URL to the root of the web service.
         :type service_root: string.  Can either be the full URL to a service
             or one of the short service names.
-        :param launchpadlib_dir: The directory where the cache and
-            credentials are stored.
+
+        :param launchpadlib_dir: The directory used to store cached
+           data obtained from Launchpad. The cache is shared by all
+           consumers, and each Launchpad service root has its own
+           cache.
         :type launchpadlib_dir: string
-        :param credentials_file: If given, the credentials are stored in that
-            file instead in `launchpadlib_dir`.
-        :type credentials_file: string
-        :return: The web service root
+
+        :param authorization_engine: A strategy for getting the
+            end-user to authorize an OAuth request token, for
+            exchanging the request token for an access token, and for
+            storing the access token locally so that it can be
+            reused. By default, launchpadlib will open the end-user's
+            web browser to have them authorize the request token.
+        :type authorization_engine: `RequestTokenAuthorizationEngine`
+
+        :param allow_access_levels: The acceptable access levels for
+            this application.
+
+            This argument is used to construct the default
+            `authorization_engine`, so if you pass in your own
+            `authorization_engine` any value for this argument will be
+            ignored. This argument will also be ignored unless you
+            also specify `consumer_name`.
+
+        :type allow_access_levels: list of strings
+
+        :param max_failed_attempts: Ignored; only present for
+            backwards compatibility.
+
+        :param credentials_file: The path to a file in which to store
+            this user's OAuth access token.
+
+        :param version: The version of the Launchpad web service to use.
+
+        :param consumer_name: The consumer name, as appropriate for
+            the `Consumer` constructor. You probably don't want to
+            provide this, since providing it will prevent you from
+            taking advantage of desktop-wide integration.
+        :type consumer_name: string
+
+        :param credential_save_failed: a callback that is called upon
+           a failure to save the credentials locally. This argument is
+           used to construct the default `credential_store`, so if
+           you pass in your own `credential_store` any value for
+           this argument will be ignored.
+        :type credential_save_failed: A callable
+
+        :param credential_store: A strategy for storing an OAuth
+            access token locally. By default, tokens are stored in the
+            GNOME keyring (or equivalent). If `credentials_file` is
+            provided, then tokens are stored unencrypted in that file.
+        :type credential_store: `CredentialStore`
+
+        :return: A web service root authorized as the end-user.
         :rtype: `Launchpad`
 
         """
         (service_root, launchpadlib_dir, cache_path,
          service_root_dir) = cls._get_paths(service_root, launchpadlib_dir)
-        credentials_path = os.path.join(service_root_dir, 'credentials')
-        if not os.path.exists(credentials_path):
-            os.makedirs(credentials_path)
-        if credentials_file is None:
-            consumer_credentials_path = os.path.join(credentials_path,
-                consumer_name)
-        else:
-            consumer_credentials_path = credentials_file
-        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, version=version)
-        else:
-            launchpad = cls.get_token_and_login(
-                consumer_name, service_root=service_root, cache=cache_path,
-                timeout=timeout, proxy_info=proxy_info,
-                authorizer_class=authorizer_class,
-                allow_access_levels=allow_access_levels,
-                max_failed_attempts=max_failed_attempts, version=version)
-            launchpad.credentials.save_to_path(consumer_credentials_path)
-            os.chmod(consumer_credentials_path, stat.S_IREAD | stat.S_IWRITE)
-        return launchpad
+
+        if (application_name is None and consumer_name is None and
+            authorization_engine is None):
+            raise ValueError(
+                "At least one of application_name, consumer_name, or "
+                "authorization_engine must be provided.")
+
+        if credentials_file is not None and credential_store is not None:
+            raise ValueError(
+                "At most one of credentials_file and credential_store "
+                "must be provided.")
+
+        if credential_store is None:
+            if credentials_file is not None:
+                # The end-user wants credentials stored in an
+                # unencrypted file.
+                credential_store = UnencryptedFileCredentialStore(
+                    credentials_file, credential_save_failed)
+            else:
+                credential_store = cls.credential_store_factory(
+                    credential_save_failed)
+        else:
+            # A credential store was passed in, so we won't be using
+            # any provided value for credential_save_failed. But at
+            # least make sure we weren't given a conflicting value,
+            # since that makes the calling code look confusing.
+            cls._assert_login_argument_consistency(
+                'credential_save_failed', credential_save_failed,
+                credential_store.credential_save_failed,
+                "credential_store")
+            credential_store = credential_store
+
+        if authorization_engine is None:
+            authorization_engine = cls.authorization_engine_factory(
+                service_root, application_name, consumer_name,
+                allow_access_levels)
+        else:
+            # An authorization engine was passed in, so we won't be
+            # using any provided values for application_name,
+            # consumer_name, or allow_access_levels. But at least make
+            # sure we weren't given conflicting values, since that
+            # makes the calling code look confusing.
+            cls._assert_login_argument_consistency(
+                "application_name", application_name,
+                authorization_engine.application_name)
+
+            cls._assert_login_argument_consistency(
+                "consumer_name", consumer_name,
+                authorization_engine.consumer.key)
+
+            cls._assert_login_argument_consistency(
+                "allow_access_levels", allow_access_levels,
+                authorization_engine.allow_access_levels)
+
+        return cls._authorize_token_and_login(
+            authorization_engine.consumer, service_root,
+            cache_path, timeout, proxy_info, authorization_engine,
+            allow_access_levels, credential_store,
+            credential_save_failed, version)
+
+    @classmethod
+    def _warn_of_deprecated_login_method(cls, name):
+        warnings.warn(
+            ("The Launchpad.%s() method is deprecated. You should use "
+             "Launchpad.login_anonymous() for anonymous access and "
+             "Launchpad.login_with() for all other purposes.") % name,
+            DeprecationWarning)
+
+    @classmethod
+    def _assert_login_argument_consistency(
+        cls, argument_name, argument_value, object_value,
+        object_name="authorization engine"):
+        """Helper to find conflicting values passed into the login methods.
+
+        Many of the arguments to login_with are used to build other
+        objects--the authorization engine or the credential store. If
+        these objects are provided directly, many of the arguments
+        become redundant. We'll allow redundant arguments through, but
+        if a argument *conflicts* with the corresponding value in the
+        provided object, we raise an error.
+        """
+        inconsistent_value_message = (
+            "Inconsistent values given for %s: "
+            "(%r passed in, versus %r in %s). "
+            "You don't need to pass in %s if you pass in %s, "
+            "so just omit that argument.")
+        if (argument_value is not None and argument_value != object_value):
+            raise ValueError(inconsistent_value_message % (
+                argument_name, argument_value, object_value,
+                object_name, argument_name, object_name))
+
 
     @classmethod
     def _get_paths(cls, service_root, launchpadlib_dir=None):
@@ -320,8 +595,8 @@
             launchpadlib_dir = os.path.join(home_dir, '.launchpadlib')
         launchpadlib_dir = os.path.expanduser(launchpadlib_dir)
         if not os.path.exists(launchpadlib_dir):
-            os.makedirs(launchpadlib_dir,0700)
-        os.chmod(launchpadlib_dir,0700)
+            os.makedirs(launchpadlib_dir, 0700)
+        os.chmod(launchpadlib_dir, 0700)
         # Determine the real service root.
         service_root = uris.lookup_service_root(service_root)
         # Each service root has its own cache and credential dirs.
@@ -330,5 +605,6 @@
         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)
+            os.makedirs(cache_path, 0700)
         return (service_root, launchpadlib_dir, cache_path, service_root_dir)
+
 
=== modified file 'src/launchpadlib/testing/helpers.py'
--- src/launchpadlib/testing/helpers.py	2010-12-07 19:30:29 +0000
+++ src/launchpadlib/testing/helpers.py	2011-02-08 19:01:02 +0000
@@ -21,29 +21,152 @@
 
 __metaclass__ = type
 __all__ = [
+    'BadSaveKeyring',
+    'fake_keyring',
+    'FauxSocketModule',
+    'InMemoryKeyring',
+    'NoNetworkAuthorizationEngine',
+    'NoNetworkLaunchpad',
     'TestableLaunchpad',
     'nopriv_read_nonprivate',
     'salgado_read_nonprivate',
     'salgado_with_full_permissions',
     ]
 
-import simplejson
+from contextlib import contextmanager
 
+import launchpadlib
 from launchpadlib.launchpad import Launchpad
 from launchpadlib.credentials import (
-    AuthorizeRequestTokenWithBrowser, Credentials,
-    RequestTokenAuthorizationEngine, SimulatedLaunchpadBrowser)
+    AccessToken,
+    Credentials,
+    RequestTokenAuthorizationEngine,
+    )
+
+
+missing = object()
+
+
+def assert_keyring_not_imported():
+    assert getattr(launchpadlib.credentials, 'keyring', missing) is missing, (
+        'During tests the real keyring module should never be imported.')
+
+
+class NoNetworkAuthorizationEngine(RequestTokenAuthorizationEngine):
+    """An authorization engine that doesn't open a web browser.
+
+    You can use this to test the creation of Launchpad objects and the
+    storing of credentials. You can't use it to interact with the web
+    service, since it only pretends to authorize its OAuth request tokens.
+    """
+    ACCESS_TOKEN_KEY = "access_key:84"
+
+    def __init__(self, *args, **kwargs):
+        super(NoNetworkAuthorizationEngine, self).__init__(*args, **kwargs)
+        # Set up some instrumentation.
+        self.request_tokens_obtained = 0
+        self.access_tokens_obtained = 0
+
+    def get_request_token(self, credentials):
+        """Pretend to get a request token from the server.
+
+        We do this by simply returning a static token ID.
+        """
+        self.request_tokens_obtained += 1
+        return "request_token:42"
+
+    def make_end_user_authorize_token(self, credentials, request_token):
+        """Pretend to exchange a request token for an access token.
+
+        We do this by simply setting the access_token property.
+        """
+        credentials.access_token = AccessToken(
+            self.ACCESS_TOKEN_KEY, 'access_secret:168')
+        self.access_tokens_obtained += 1
+
+
+class NoNetworkLaunchpad(Launchpad):
+    """A Launchpad instance for tests with no network access.
+
+    It's only useful for making sure that certain methods were called.
+    It can't be used to interact with the API.
+    """
+
+    def __init__(self, credentials, authorization_engine, credential_store,
+                 service_root, cache, timeout, proxy_info, version):
+        self.credentials = credentials
+        self.authorization_engine = authorization_engine
+        self.credential_store = credential_store
+        self.passed_in_args = dict(
+            service_root=service_root, cache=cache, timeout=timeout,
+            proxy_info=proxy_info, version=version)
+
+    @classmethod
+    def authorization_engine_factory(cls, *args):
+        return NoNetworkAuthorizationEngine(*args)
 
 
 class TestableLaunchpad(Launchpad):
     """A base class for talking to the testing root service."""
 
-    def __init__(self, credentials, service_root=None,
+    def __init__(self, credentials, authorization_engine=None,
+                 credential_store=None, service_root="test_dev",
                  cache=None, timeout=None, proxy_info=None,
                  version=Launchpad.DEFAULT_VERSION):
+        """Provide test-friendly defaults.
+
+        :param authorization_engine: Defaults to None, since a test
+            environment can't use an authorization engine.
+        :param credential_store: Defaults to None, since tests
+            generally pass in fully-formed Credentials objects.
+        :param service_root: Defaults to 'test_dev'.
+        """
         super(TestableLaunchpad, self).__init__(
-            credentials, 'test_dev', cache, timeout, proxy_info,
-            version=version)
+            credentials, authorization_engine, credential_store,
+            service_root=service_root, cache=cache, timeout=timeout,
+            proxy_info=proxy_info, version=version)
+
+
+@contextmanager
+def fake_keyring(fake):
+    """A context manager which injects a testing keyring implementation."""
+    # The real keyring package should never be imported during tests.
+    assert_keyring_not_imported()
+    launchpadlib.credentials.keyring = fake
+    try:
+        yield
+    finally:
+        del launchpadlib.credentials.keyring
+
+
+class FauxSocketModule:
+    """A socket module replacement that provides a fake hostname."""
+
+    def gethostname(self):
+        return 'HOSTNAME'
+
+
+class BadSaveKeyring:
+    """A keyring that generates errors when saving passwords."""
+
+    def get_password(self, service, username):
+        return None
+
+    def set_password(self, service, username, password):
+        raise RuntimeError
+
+
+class InMemoryKeyring:
+    """A keyring that saves passwords only in memory."""
+
+    def __init__(self):
+        self.data = {}
+
+    def set_password(self, service, username, password):
+        self.data[service, username] = password
+
+    def get_password(self, service, username):
+        return self.data.get((service, username))
 
 
 class KnownTokens:
@@ -52,119 +175,18 @@
     def __init__(self, token_string, access_secret):
         self.token_string = token_string
         self.access_secret = access_secret
+        self.token = AccessToken(token_string, access_secret)
+        self.credentials = Credentials(
+            consumer_name="launchpad-library", access_token=self.token)
 
     def login(self, cache=None, timeout=None, proxy_info=None,
               version=Launchpad.DEFAULT_VERSION):
-        """Login using these credentials."""
-        return TestableLaunchpad.login(
-            'launchpad-library', self.token_string, self.access_secret,
-            cache=cache, timeout=timeout, proxy_info=proxy_info,
-            version=version)
+        """Create a Launchpad object using these credentials."""
+        return TestableLaunchpad(
+            self.credentials, cache=cache, timeout=timeout,
+            proxy_info=proxy_info, version=version)
 
 
 salgado_with_full_permissions = KnownTokens('salgado-change-anything', 'test')
 salgado_read_nonprivate = KnownTokens('salgado-read-nonprivate', 'secret')
 nopriv_read_nonprivate = KnownTokens('nopriv-read-nonprivate', 'mystery')
-
-
-class ScriptableRequestTokenAuthorization(RequestTokenAuthorizationEngine):
-    """A request token process that doesn't need any user input.
-
-    The RequestTokenAuthorizationEngine is supposed to be hooked up to a
-    user interface, but that makes it difficult to test. This subclass
-    is designed to be easy to test.
-    """
-
-    def __init__(self, consumer_name, username, password, choose_access_level,
-                 allow_access_levels=[], max_failed_attempts=2,
-                 web_root="http://launchpad.dev:8085/"):
-
-        # Get a request token.
-        self.credentials = Credentials(consumer_name)
-        self.credentials.get_request_token(web_root=web_root)
-
-        # Initialize the superclass with the new request token.
-        super(ScriptableRequestTokenAuthorization, self).__init__(
-            web_root, consumer_name, self.credentials._request_token.key,
-                allow_access_levels, max_failed_attempts)
-
-        self.username = username
-        self.password = password
-        self.choose_access_level = choose_access_level
-
-    def __call__(self, exchange_for_access_token=True):
-        super(ScriptableRequestTokenAuthorization, self).__call__()
-
-        # Now verify that it worked by exchanging the authorized
-        # request token for an access token.
-        if (exchange_for_access_token and
-            self.choose_access_level != self.UNAUTHORIZED_ACCESS_LEVEL):
-            self.credentials.exchange_request_token_for_access_token(
-                web_root=self.web_root)
-            return self.credentials.access_token
-        return None
-
-    def open_page_in_user_browser(self, url):
-        """Print a status message."""
-        print ("[If this were a real application, the end-user's web "
-               "browser would be opened to %s]" % url)
-
-    def input_username(self, cached_username, suggested_message):
-        """Collect the Launchpad username from the end-user."""
-        print suggested_message
-        if cached_username is not None:
-            print "Cached email address: " + cached_username
-        return self.username
-
-    def input_password(self, suggested_message):
-        """Collect the Launchpad password from the end-user."""
-        print suggested_message
-        return self.password
-
-    def input_access_level(self, available_levels, suggested_message,
-                           only_one_option):
-        """Collect the desired level of access from the end-user."""
-        print suggested_message
-        print [level['value'] for level in available_levels]
-        return self.choose_access_level
-
-    def startup(self, suggested_messages):
-        for message in suggested_messages:
-            print message
-
-
-class DummyAuthorizeRequestTokenWithBrowser(AuthorizeRequestTokenWithBrowser):
-
-    def __init__(self, web_root, consumer_name, request_token, username,
-                 password, allow_access_levels=[], max_failed_attempts=3):
-        super(DummyAuthorizeRequestTokenWithBrowser, self).__init__(
-            web_root, consumer_name, request_token, allow_access_levels,
-            max_failed_attempts)
-
-    def open_page_in_user_browser(self, url):
-        """Print a status message."""
-        print ("[If this were a real application, the end-user's web "
-               "browser would be opened to %s]" % url)
-
-
-class UserInput(object):
-    """A class to store fake user input in a readable way.
-
-    An instance of this class can be used as a substitute for the
-    raw_input() function.
-    """
-
-    def __init__(self, inputs):
-        """Initialize with a line of user inputs."""
-        self.stream = iter(inputs)
-
-    def __call__(self, prompt):
-        """Print and return the next line of input."""
-        line = self.readline()
-        print prompt + "[User input: %s]" % line
-        return line
-
-    def readline(self):
-        """Return the next line of input."""
-        next_input = self.stream.next()
-        return str(next_input)
 
=== added file 'src/launchpadlib/tests/test_credential_store.py'
--- src/launchpadlib/tests/test_credential_store.py	1970-01-01 00:00:00 +0000
+++ src/launchpadlib/tests/test_credential_store.py	2011-02-08 19:01:02 +0000
@@ -0,0 +1,138 @@
+# Copyright 2010 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/>.
+
+"""Tests for the credential store classes."""
+
+import os
+import tempfile
+import unittest
+
+from launchpadlib.testing.helpers import (
+    fake_keyring,
+    InMemoryKeyring,
+)
+
+from launchpadlib.credentials import (
+    AccessToken,
+    Credentials,
+    KeyringCredentialStore,
+    UnencryptedFileCredentialStore,
+)
+
+
+class CredentialStoreTestCase(unittest.TestCase):
+
+    def make_credential(self, consumer_key):
+        """Helper method to make a fake credential."""
+        return Credentials(
+            "app name", consumer_secret='consumer_secret:42',
+            access_token=AccessToken(consumer_key, 'access_secret:168'))
+
+
+class TestUnencryptedFileCredentialStore(CredentialStoreTestCase):
+    """Tests for the UnencryptedFileCredentialStore class."""
+
+    def setUp(self):
+        ignore, self.filename = tempfile.mkstemp()
+        self.store = UnencryptedFileCredentialStore(self.filename)
+
+    def tearDown(self):
+        if os.path.exists(self.filename):
+            os.remove(self.filename)
+
+    def test_save_and_load(self):
+        # Make sure you can save and load credentials to a file.
+        credential = self.make_credential("consumer key")
+        self.store.save(credential, "unique key")
+        credential2 = self.store.load("unique key")
+        self.assertEquals(credential.consumer.key, credential2.consumer.key)
+
+    def test_unique_id_doesnt_matter(self):
+        # If a file contains a credential, that credential will be
+        # accessed no matter what unique ID you specify.
+        credential = self.make_credential("consumer key")
+        self.store.save(credential, "some key")
+        credential2 = self.store.load("some other key")
+        self.assertEquals(credential.consumer.key, credential2.consumer.key)
+
+    def test_file_only_contains_one_credential(self):
+        # A credential file may contain only one credential. If you
+        # write two credentials with different unique IDs to the same
+        # file, the first credential will be overwritten with the
+        # second.
+        credential1 = self.make_credential("consumer key")
+        credential2 = self.make_credential("consumer key2")
+        self.store.save(credential1, "unique key 1")
+        self.store.save(credential1, "unique key 2")
+        loaded = self.store.load("unique key 1")
+        self.assertEquals(loaded.consumer.key, credential2.consumer.key)
+
+
+class TestKeyringCredentialStore(CredentialStoreTestCase):
+    """Tests for the KeyringCredentialStore class."""
+
+    def setUp(self):
+        self.keyring = InMemoryKeyring()
+        self.store = KeyringCredentialStore()
+
+    def test_save_and_load(self):
+        # Make sure you can save and load credentials to a keyring.
+        with fake_keyring(self.keyring):
+            credential = self.make_credential("consumer key")
+            self.store.save(credential, "unique key")
+            credential2 = self.store.load("unique key")
+            self.assertEquals(
+                credential.consumer.key, credential2.consumer.key)
+
+    def test_lookup_by_unique_key(self):
+        # Credentials in the keyring are looked up by the unique ID
+        # under which they were stored.
+        with fake_keyring(self.keyring):
+            credential1 = self.make_credential("consumer key1")
+            self.store.save(credential1, "key 1")
+
+            credential2 = self.make_credential("consumer key2")
+            self.store.save(credential2, "key 2")
+
+            loaded1 = self.store.load("key 1")
+            self.assertEquals(
+                credential1.consumer.key, loaded1.consumer.key)
+
+            loaded2 = self.store.load("key 2")
+            self.assertEquals(
+                credential2.consumer.key, loaded2.consumer.key)
+
+    def test_reused_unique_id_overwrites_old_credential(self):
+        # Writing a credential to the keyring with a given unique ID
+        # will overwrite any credential stored under that ID.
+
+        with fake_keyring(self.keyring):
+            credential1 = self.make_credential("consumer key1")
+            self.store.save(credential1, "the only key")
+
+            credential2 = self.make_credential("consumer key2")
+            self.store.save(credential2, "the only key")
+
+            loaded = self.store.load("the only key")
+            self.assertEquals(
+                credential2.consumer.key, loaded.consumer.key)
+
+    def test_bad_unique_id_returns_none(self):
+        # Trying to load a credential without providing a good unique
+        # ID will get you None.
+        with fake_keyring(self.keyring):
+            self.assertEquals(None, self.store.load("no such key"))
+
 
=== added file 'src/launchpadlib/tests/test_http.py'
--- src/launchpadlib/tests/test_http.py	1970-01-01 00:00:00 +0000
+++ src/launchpadlib/tests/test_http.py	2011-02-08 19:01:02 +0000
@@ -0,0 +1,236 @@
+# Copyright 2010 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/>.
+
+"""Tests for the LaunchpadOAuthAwareHTTP class."""
+
+from collections import deque
+import tempfile
+import unittest
+
+from simplejson import dumps, JSONDecodeError
+
+from launchpadlib.errors import Unauthorized
+from launchpadlib.credentials import UnencryptedFileCredentialStore
+from launchpadlib.launchpad import (
+    Launchpad,
+    LaunchpadOAuthAwareHttp,
+    )
+from launchpadlib.testing.helpers import (
+    NoNetworkAuthorizationEngine,
+    NoNetworkLaunchpad,
+    )
+
+
+# The simplest WADL that looks like a representation of the service root.
+SIMPLE_WADL = '''<?xml version="1.0"?>
+<application xmlns="http://research.sun.com/wadl/2006/10">
+  <resources base="http://www.example.com/">
+    <resource path="" type="#service-root"/>
+  </resources>
+
+  <resource_type id="service-root">
+    <method name="GET" id="service-root-get">
+      <response>
+        <representation href="#service-root-json"/>
+      </response>
+    </method>
+  </resource_type>
+
+  <representation id="service-root-json" mediaType="application/json"/>
+</application>
+'''
+
+# The simplest JSON that looks like a representation of the service root.
+SIMPLE_JSON = dumps({})
+
+
+class Response:
+    """A fake HTTP response object."""
+    def __init__(self, status, content):
+        self.status = status
+        self.content = content
+
+
+class SimulatedResponsesHttp(LaunchpadOAuthAwareHttp):
+    """Responds to HTTP requests by shifting responses off a stack."""
+
+    def __init__(self, responses, *args):
+        """Constructor.
+
+        :param responses: A list of HttpResponse objects to use
+            in response to requests.
+        """
+        super(SimulatedResponsesHttp, self).__init__(*args)
+        self.sent_responses = []
+        self.unsent_responses = responses
+        self.cache = None
+
+    def _request(self, *args):
+        response = self.unsent_responses.popleft()
+        self.sent_responses.append(response)
+        return self.retry_on_bad_token(response, response.content, *args)
+
+
+class SimulatedResponsesLaunchpad(Launchpad):
+
+    # Every Http object generated by this class will return these
+    # responses, in order.
+    responses = []
+
+    def httpFactory(self, *args):
+        return SimulatedResponsesHttp(
+            deque(self.responses), self, self.authorization_engine, *args)
+
+    @classmethod
+    def credential_store_factory(cls, credential_save_failed):
+        return UnencryptedFileCredentialStore(
+            tempfile.mkstemp()[1], credential_save_failed)
+
+
+class SimulatedResponsesTestCase(unittest.TestCase):
+    """Test cases that give fake responses to launchpad's HTTP requests."""
+
+    def setUp(self):
+        """Clear out the list of simulated responses."""
+        SimulatedResponsesLaunchpad.responses = []
+        self.engine = NoNetworkAuthorizationEngine(
+            'http://api.example.com/', 'application name')
+
+    def launchpad_with_responses(self, *responses):
+        """Use simulated HTTP responses to get a Launchpad object.
+
+        The given Response objects will be sent, in order, in response
+        to launchpadlib's requests.
+
+        :param responses: Some number of Response objects.
+        :return: The Launchpad object, assuming that errors in the
+            simulated requests didn't prevent one from being created.
+        """
+        SimulatedResponsesLaunchpad.responses = responses
+        return SimulatedResponsesLaunchpad.login_with(
+            'application name', authorization_engine=self.engine)
+
+
+class TestAbilityToParseData(SimulatedResponsesTestCase):
+    """Test launchpadlib's ability to handle the sample data.
+
+    To create a Launchpad object, two HTTP requests must succeed and
+    return usable data: the requests for the WADL and JSON
+    representations of the service root. This test shows that the
+    minimal data in SIMPLE_WADL and SIMPLE_JSON is good enough to
+    create a Launchpad object.
+    """
+
+    def test_minimal_data(self):
+        """Make sure that launchpadlib can use the minimal data."""
+        launchpad = self.launchpad_with_responses(
+            Response(200, SIMPLE_WADL),
+            Response(200, SIMPLE_JSON))
+
+    def test_bad_wadl(self):
+        """Show that bad WADL causes an exception."""
+        self.assertRaises(
+            SyntaxError, self.launchpad_with_responses,
+            Response(200, "This is not WADL."),
+            Response(200, SIMPLE_JSON))
+
+    def test_bad_json(self):
+        """Show that bad JSON causes an exception."""
+        self.assertRaises(
+            JSONDecodeError, self.launchpad_with_responses,
+            Response(200, SIMPLE_WADL),
+            Response(200, "This is not JSON."))
+
+
+class TestTokenFailureDuringRequest(SimulatedResponsesTestCase):
+    """Test access token failures during a request.
+
+    launchpadlib makes two HTTP requests on startup, to get the WADL
+    and JSON representations of the service root. If Launchpad
+    receives a 401 error during this process, it will acquire a fresh
+    access token and try again.
+    """
+
+    def test_good_token(self):
+        """If our token is good, we never get another one."""
+        SimulatedResponsesLaunchpad.responses = [
+            Response(200, SIMPLE_WADL),
+            Response(200, SIMPLE_JSON)]
+
+        self.assertEquals(self.engine.access_tokens_obtained, 0)
+        launchpad = SimulatedResponsesLaunchpad.login_with(
+            'application name', authorization_engine=self.engine)
+        self.assertEquals(self.engine.access_tokens_obtained, 1)
+
+    def test_bad_token(self):
+        """If our token is bad, we get another one."""
+        SimulatedResponsesLaunchpad.responses = [
+            Response(401, "Invalid token."),
+            Response(200, SIMPLE_WADL),
+            Response(200, SIMPLE_JSON)]
+
+        self.assertEquals(self.engine.access_tokens_obtained, 0)
+        launchpad = SimulatedResponsesLaunchpad.login_with(
+            'application name', authorization_engine=self.engine)
+        self.assertEquals(self.engine.access_tokens_obtained, 2)
+
+    def test_expired_token(self):
+        """If our token is expired, we get another one."""
+
+        SimulatedResponsesLaunchpad.responses = [
+            Response(401, "Expired token."),
+            Response(200, SIMPLE_WADL),
+            Response(200, SIMPLE_JSON)]
+
+        self.assertEquals(self.engine.access_tokens_obtained, 0)
+        launchpad = SimulatedResponsesLaunchpad.login_with(
+            'application name', authorization_engine=self.engine)
+        self.assertEquals(self.engine.access_tokens_obtained, 2)
+
+    def test_delayed_error(self):
+        """We get another token no matter when the error happens."""
+        SimulatedResponsesLaunchpad.responses = [
+            Response(200, SIMPLE_WADL),
+            Response(401, "Expired token."),
+            Response(200, SIMPLE_JSON)]
+
+        self.assertEquals(self.engine.access_tokens_obtained, 0)
+        launchpad = SimulatedResponsesLaunchpad.login_with(
+            'application name', authorization_engine=self.engine)
+        self.assertEquals(self.engine.access_tokens_obtained, 2)
+
+    def test_many_errors(self):
+        """We'll keep getting new tokens as long as tokens are the problem."""
+        SimulatedResponsesLaunchpad.responses = [
+            Response(401, "Invalid token."),
+            Response(200, SIMPLE_WADL),
+            Response(401, "Expired token."),
+            Response(401, "Invalid token."),
+            Response(200, SIMPLE_JSON)]
+        self.assertEquals(self.engine.access_tokens_obtained, 0)
+        launchpad = SimulatedResponsesLaunchpad.login_with(
+            'application name', authorization_engine=self.engine)
+        self.assertEquals(self.engine.access_tokens_obtained, 4)
+
+    def test_other_unauthorized(self):
+        """If the token is not at fault, a 401 error raises an exception."""
+
+        SimulatedResponsesLaunchpad.responses = [
+            Response(401, "Some other error.")]
+
+        self.assertRaises(
+            Unauthorized, SimulatedResponsesLaunchpad.login_with,
+            'application name', authorization_engine=self.engine)
 
=== modified file 'src/launchpadlib/tests/test_launchpad.py'
--- src/launchpadlib/tests/test_launchpad.py	2010-12-07 19:30:29 +0000
+++ src/launchpadlib/tests/test_launchpad.py	2011-02-08 19:01:02 +0000
@@ -20,42 +20,47 @@
 
 import os
 import shutil
+import socket
 import stat
 import tempfile
 import unittest
+import warnings
+
+from lazr.restfulclient.resource import ServiceRoot
 
 from launchpadlib.credentials import (
-    AccessToken, AuthorizeRequestTokenWithBrowser, Credentials)
+    AccessToken,
+    Credentials,
+    )
+
+from launchpadlib import uris
+import launchpadlib.launchpad
 from launchpadlib.launchpad import Launchpad
-from launchpadlib import uris
-
-class NoNetworkLaunchpad(Launchpad):
-    """A Launchpad instance for tests with no network access.
-
-    It's only useful for making sure that certain methods were called.
-    It can't be used to interact with the API.
-    """
-
-    consumer_name = None
-    passed_in_kwargs = None
-    credentials = None
-    get_token_and_login_called = False
-
-    def __init__(self, credentials, **kw):
-        self.credentials = credentials
-        self.passed_in_kwargs = kw
-
-    @classmethod
-    def get_token_and_login(cls, consumer_name, **kw):
-        """Create fake credentials and record that we were called."""
-        credentials = Credentials(
-            consumer_name, consumer_secret='consumer_secret:42',
-            access_token=AccessToken('access_key:84', 'access_secret:168'))
-        launchpad = cls(credentials, **kw)
-        launchpad.get_token_and_login_called = True
-        launchpad.consumer_name = consumer_name
-        launchpad.passed_in_kwargs = kw
-        return launchpad
+from launchpadlib.testing.helpers import (
+    assert_keyring_not_imported,
+    BadSaveKeyring,
+    fake_keyring,
+    FauxSocketModule,
+    InMemoryKeyring,
+    NoNetworkAuthorizationEngine,
+    NoNetworkLaunchpad,
+    )
+from launchpadlib.credentials import (
+    KeyringCredentialStore,
+    UnencryptedFileCredentialStore,
+    )
+
+# A dummy service root for use in tests
+SERVICE_ROOT = "http://api.example.com/"
+
+class TestResourceTypeClasses(unittest.TestCase):
+    """launchpadlib must know about restfulclient's resource types."""
+
+    def test_resource_types(self):
+        # Make sure that Launchpad knows about every special resource
+        # class defined by lazr.restfulclient.
+        for name, cls in ServiceRoot.RESOURCE_TYPE_CLASSES.items():
+            self.assertEqual(Launchpad.RESOURCE_TYPE_CLASSES[name], cls)
 
 
 class TestNameLookups(unittest.TestCase):
@@ -63,7 +68,7 @@
 
     def setUp(self):
         self.aliases = sorted(
-            ['production', 'edge', 'staging', 'dogfood', 'dev', 'test_dev'])
+            ['production', 'qastaging', 'staging', 'dogfood', 'dev', 'test_dev'])
 
     def test_short_names(self):
         # Ensure the short service names are all supported.
@@ -115,7 +120,7 @@
         version = "version-foo"
         root = uris.service_roots['staging'] + version
         try:
-            Launchpad(None, root, version=version)
+            Launchpad(None, None, None, service_root=root, version=version)
         except ValueError, e:
             self.assertTrue(str(e).startswith(
                 "It looks like you're using a service root that incorporates "
@@ -127,42 +132,115 @@
         # Make sure the problematic URL is caught even if it has a
         # slash on the end.
         root += '/'
-        self.assertRaises(ValueError, Launchpad, None, root, version=version)
+        self.assertRaises(ValueError, Launchpad, None, None, None,
+                          service_root=root, version=version)
 
         # Test that the default version has the same problem
         # when no explicit version is specified
         default_version = NoNetworkLaunchpad.DEFAULT_VERSION
         root = uris.service_roots['staging'] + default_version + '/'
-        self.assertRaises(ValueError, Launchpad, None, root)
-
-
-class TestLaunchpadLoginWith(unittest.TestCase):
+        self.assertRaises(ValueError, Launchpad, None, None, None,
+                          service_root=root)
+
+
+class TestRequestTokenAuthorizationEngine(unittest.TestCase):
+    """Tests for the RequestTokenAuthorizationEngine class."""
+
+    def test_app_must_be_identified(self):
+        self.assertRaises(
+            ValueError, NoNetworkAuthorizationEngine, SERVICE_ROOT)
+
+    def test_application_name_identifies_app(self):
+        NoNetworkAuthorizationEngine(SERVICE_ROOT, application_name='name')
+
+    def test_consumer_name_identifies_app(self):
+        NoNetworkAuthorizationEngine(SERVICE_ROOT, consumer_name='name')
+
+    def test_conflicting_app_identification(self):
+        # You can't specify both application_name and consumer_name.
+        self.assertRaises(
+            ValueError, NoNetworkAuthorizationEngine,
+            SERVICE_ROOT, application_name='name1', consumer_name='name2')
+
+        # This holds true even if you specify the same value for
+        # both. They're not the same thing.
+        self.assertRaises(
+            ValueError, NoNetworkAuthorizationEngine,
+            SERVICE_ROOT, application_name='name', consumer_name='name')
+
+
+class TestLaunchpadLoginWithCredentialsFile(unittest.TestCase):
+    """Tests for Launchpad.login_with() with a credentials file."""
+
+    def test_filename(self):
+        ignore, filename = tempfile.mkstemp()
+        launchpad = NoNetworkLaunchpad.login_with(
+            application_name='not important', credentials_file=filename)
+
+        # The credentials are stored unencrypted in the file you
+        # specify.
+        credentials = Credentials.load_from_path(filename)
+        self.assertEquals(credentials.consumer.key,
+                          launchpad.credentials.consumer.key)
+        os.remove(filename)
+
+    def test_cannot_specify_both_filename_and_store(self):
+        ignore, filename = tempfile.mkstemp()
+        store = KeyringCredentialStore()
+        self.assertRaises(
+            ValueError, NoNetworkLaunchpad.login_with,
+            application_name='not important', credentials_file=filename,
+            credential_store=store)
+        os.remove(filename)
+
+
+class KeyringTest(unittest.TestCase):
+    """Base class for tests that use the keyring."""
+
+    def setUp(self):
+        # The real keyring package should never be imported during tests.
+        assert_keyring_not_imported()
+        # For these tests we want to use a dummy keyring implementation
+        # that only stores data in memory.
+        launchpadlib.credentials.keyring = InMemoryKeyring()
+
+    def tearDown(self):
+        # Remove the fake keyring module we injected during setUp.
+        del launchpadlib.credentials.keyring
+
+
+class TestLaunchpadLoginWith(KeyringTest):
     """Tests for Launchpad.login_with()."""
 
     def setUp(self):
+        super(TestLaunchpadLoginWith, self).setUp()
         self.temp_dir = tempfile.mkdtemp()
 
     def tearDown(self):
+        super(TestLaunchpadLoginWith, self).tearDown()
         shutil.rmtree(self.temp_dir)
 
     def test_dirs_created(self):
         # The path we pass into login_with() is the directory where
-        # cache and credentials for all service roots are stored.
+        # cache for all service roots are stored.
         launchpadlib_dir = os.path.join(self.temp_dir, 'launchpadlib')
-        launchpad = NoNetworkLaunchpad.login_with(
-            'not important', service_root='http://api.example.com/beta',
+        NoNetworkLaunchpad.login_with(
+            'not important', service_root=SERVICE_ROOT,
             launchpadlib_dir=launchpadlib_dir)
         # The 'launchpadlib' dir got created.
         self.assertTrue(os.path.isdir(launchpadlib_dir))
         # A directory for the passed in service root was created.
         service_path = os.path.join(launchpadlib_dir, 'api.example.com')
         self.assertTrue(os.path.isdir(service_path))
-        # Inside the service root directory, there is a 'cache' and a
-        # 'credentials' directory.
+        # Inside the service root directory, there is a 'cache'
+        # directory.
         self.assertTrue(
             os.path.isdir(os.path.join(service_path, 'cache')))
+
+        # In older versions there was also a 'credentials' directory,
+        # but no longer.
         credentials_path = os.path.join(service_path, 'credentials')
-        self.assertTrue(os.path.isdir(credentials_path))
+        self.assertFalse(os.path.isdir(credentials_path))
 
     def test_dirs_created_are_changed_to_secure(self):
         launchpadlib_dir = os.path.join(self.temp_dir, 'launchpadlib')
@@ -173,8 +251,8 @@
         statinfo = os.stat(launchpadlib_dir)
         mode = stat.S_IMODE(statinfo.st_mode)
         self.assertNotEqual(mode, stat.S_IWRITE | stat.S_IREAD | stat.S_IEXEC)
-        launchpad = NoNetworkLaunchpad.login_with(
-            'not important', service_root='http://api.example.com/beta',
+        NoNetworkLaunchpad.login_with(
+            'not important', service_root=SERVICE_ROOT,
             launchpadlib_dir=launchpadlib_dir)
         # Verify the mode has been changed to 0700
         statinfo = os.stat(launchpadlib_dir)
@@ -183,8 +261,8 @@
 
     def test_dirs_created_are_secure(self):
         launchpadlib_dir = os.path.join(self.temp_dir, 'launchpadlib')
-        launchpad = NoNetworkLaunchpad.login_with(
-            'not important', service_root='http://api.example.com/beta',
+        NoNetworkLaunchpad.login_with(
+            'not important', service_root=SERVICE_ROOT,
             launchpadlib_dir=launchpadlib_dir)
         self.assertTrue(os.path.isdir(launchpadlib_dir))
         # Verify the mode is safe
@@ -198,44 +276,159 @@
         # credentials will be cached to disk.
         launchpadlib_dir = os.path.join(self.temp_dir, 'launchpadlib')
         launchpad = NoNetworkLaunchpad.login_with(
-            'not important', service_root='http://api.example.com/',
+            'not important', service_root=SERVICE_ROOT,
             launchpadlib_dir=launchpadlib_dir, version="foo")
-        self.assertEquals(launchpad.passed_in_kwargs['version'], 'foo')
+        self.assertEquals(launchpad.passed_in_args['version'], 'foo')
 
         # Now execute the same test a second time. This time, the
         # credentials are loaded from disk and a different code path
         # is executed. We want to make sure this code path propagates
         # the 'version' argument.
         launchpad = NoNetworkLaunchpad.login_with(
-            'not important', service_root='http://api.example.com/',
+            'not important', service_root=SERVICE_ROOT,
             launchpadlib_dir=launchpadlib_dir, version="bar")
-        self.assertEquals(launchpad.passed_in_kwargs['version'], 'bar')
-
-    def test_no_credentials_calls_get_token_and_login(self):
-        # If no credentials are found, get_token_and_login() is called.
-        service_root = 'http://api.example.com/beta'
+        self.assertEquals(launchpad.passed_in_args['version'], 'bar')
+
+    def test_application_name_is_propagated(self):
+        # Create a Launchpad instance for a given application name.
+        # Credentials are stored, but they don't include the
+        # application name, since multiple applications may share a
+        # single system-wide credential.
+        launchpadlib_dir = os.path.join(self.temp_dir, 'launchpadlib')
+        launchpad = NoNetworkLaunchpad.login_with(
+            'very important', service_root=SERVICE_ROOT,
+            launchpadlib_dir=launchpadlib_dir)
+        self.assertEquals(
+            launchpad.credentials.consumer.application_name, 'very important')
+
+        # Now execute the same test a second time. This time, the
+        # credentials are loaded from disk and a different code path
+        # is executed. We want to make sure this code path propagates
+        # the application name, instead of picking an empty one from
+        # disk.
+        launchpad = NoNetworkLaunchpad.login_with(
+            'very important', service_root=SERVICE_ROOT,
+            launchpadlib_dir=launchpadlib_dir)
+        self.assertEquals(
+            launchpad.credentials.consumer.application_name, 'very important')
+
+    def test_authorization_engine_is_propagated(self):
+        # You can pass in a custom authorization engine, which will be
+        # used to get a request token and exchange it for an access
+        # token.
+        engine = NoNetworkAuthorizationEngine(
+            SERVICE_ROOT, 'application name')
+        NoNetworkLaunchpad.login_with(authorization_engine=engine)
+        self.assertEquals(engine.request_tokens_obtained, 1)
+        self.assertEquals(engine.access_tokens_obtained, 1)
+
+    def test_login_with_must_identify_application(self):
+        # If you call login_with without identifying your application
+        # you'll get an error.
+        self.assertRaises(ValueError, NoNetworkLaunchpad.login_with)
+
+    def test_application_name_identifies_app(self):
+        # If you pass in application_name, that's good enough to identify
+        # your application.
+        NoNetworkLaunchpad.login_with(application_name="name")
+
+    def test_consumer_name_identifies_app(self):
+        # If you pass in consumer_name, that's good enough to identify
+        # your application.
+        NoNetworkLaunchpad.login_with(consumer_name="name")
+
+    def test_inconsistent_application_name_rejected(self):
+        """Catch an attempt to specify inconsistent application_names."""
+        engine = NoNetworkAuthorizationEngine(
+            SERVICE_ROOT, 'application name1')
+        self.assertRaises(ValueError, NoNetworkLaunchpad.login_with,
+                          "application name2",
+                          authorization_engine=engine)
+
+    def test_inconsistent_consumer_name_rejected(self):
+        """Catch an attempt to specify inconsistent application_names."""
+        engine = NoNetworkAuthorizationEngine(
+            SERVICE_ROOT, None, consumer_name="consumer_name1")
+
+        self.assertRaises(ValueError, NoNetworkLaunchpad.login_with,
+                          "consumer_name2",
+                          authorization_engine=engine)
+
+    def test_inconsistent_allow_access_levels_rejected(self):
+        """Catch an attempt to specify inconsistent allow_access_levels."""
+        engine = NoNetworkAuthorizationEngine(
+            SERVICE_ROOT, consumer_name="consumer",
+            allow_access_levels=['FOO'])
+
+        self.assertRaises(ValueError, NoNetworkLaunchpad.login_with,
+                          None, consumer_name="consumer",
+                          allow_access_levels=['BAR'],
+                          authorization_engine=engine)
+
+    def test_inconsistent_credential_save_failed(self):
+        # Catch an attempt to specify inconsistent callbacks for
+        # credential save failure.
+        def callback1():
+            pass
+        store = KeyringCredentialStore(credential_save_failed=callback1)
+
+        def callback2():
+            pass
+        self.assertRaises(ValueError, NoNetworkLaunchpad.login_with,
+                          "app name", credential_store=store,
+                          credential_save_failed=callback2)
+
+    def test_non_desktop_integration(self):
+        # When doing a non-desktop integration, you must specify a
+        # consumer_name. You can pass a list of allowable access
+        # levels into login_with().
+        launchpad = NoNetworkLaunchpad.login_with(
+            consumer_name="consumer", allow_access_levels=['FOO'])
+        self.assertEquals(launchpad.credentials.consumer.key, "consumer")
+        self.assertEquals(launchpad.credentials.consumer.application_name,
+                          None)
+        self.assertEquals(launchpad.authorization_engine.allow_access_levels,
+                          ['FOO'])
+
+    def test_desktop_integration_doesnt_happen_without_consumer_name(self):
+        # The only way to do a non-desktop integration is to specify a
+        # consumer_name. If you specify application_name instead, your
+        # value for allow_access_levels is ignored, and a desktop
+        # integration is performed.
+        launchpad = NoNetworkLaunchpad.login_with(
+            'application name', allow_access_levels=['FOO'])
+        self.assertEquals(launchpad.authorization_engine.allow_access_levels,
+                          ['DESKTOP_INTEGRATION'])
+
+    def test_no_credentials_creates_new_credential(self):
+        # If no credentials are found, a desktop-wide credential is created.
         timeout = object()
         proxy_info = object()
         launchpad = NoNetworkLaunchpad.login_with(
             'app name', launchpadlib_dir=self.temp_dir,
-            service_root=service_root, timeout=timeout, proxy_info=proxy_info)
-        self.assertEqual(launchpad.consumer_name, 'app name')
+            service_root=SERVICE_ROOT, timeout=timeout, proxy_info=proxy_info)
+        # Here's the new credential.
+        self.assertEqual(launchpad.credentials.access_token.key,
+                         NoNetworkAuthorizationEngine.ACCESS_TOKEN_KEY)
+        self.assertEqual(launchpad.credentials.consumer.application_name,
+                         'app name')
+        self.assertEquals(launchpad.authorization_engine.allow_access_levels,
+                          ['DESKTOP_INTEGRATION'])
+        # The expected arguments were passed in to the Launchpad
+        # constructor.
         expected_arguments = dict(
-            allow_access_levels=[],
-            authorizer_class=AuthorizeRequestTokenWithBrowser,
-            max_failed_attempts=3,
-            service_root=service_root,
-            timeout=timeout,
-            proxy_info=proxy_info,
+            service_root=SERVICE_ROOT,
             cache=os.path.join(self.temp_dir, 'api.example.com', 'cache'),
-            version='beta')
-        self.assertEqual(launchpad.passed_in_kwargs, expected_arguments)
+            timeout=timeout,
+            proxy_info=proxy_info,
+            version=NoNetworkLaunchpad.DEFAULT_VERSION)
+        self.assertEqual(launchpad.passed_in_args, expected_arguments)
 
     def test_anonymous_login(self):
         """Test the anonymous login helper function."""
         launchpad = NoNetworkLaunchpad.login_anonymously(
             'anonymous access', launchpadlib_dir=self.temp_dir,
-            service_root='http://api.example.com/beta')
+            service_root=SERVICE_ROOT)
         self.assertEqual(launchpad.credentials.access_token.key, '')
         self.assertEqual(launchpad.credentials.access_token.secret, '')
 
@@ -245,62 +438,6 @@
             'anonymous access')
         self.assertFalse(os.path.exists(credentials_path))
 
-    def test_new_credentials_are_saved(self):
-        # After get_token_and_login() have been called, the created
-        # credentials are saved.
-        launchpad = NoNetworkLaunchpad.login_with(
-            'app name', launchpadlib_dir=self.temp_dir,
-            service_root='http://api.example.com/beta')
-        credentials_path = os.path.join(
-            self.temp_dir, 'api.example.com', 'credentials', 'app name')
-        self.assertTrue(os.path.exists(credentials_path))
-        # Make sure that the credentials can be loaded, thus were
-        # written correctly.
-        loaded_credentials = Credentials.load_from_path(credentials_path)
-        self.assertEqual(loaded_credentials.consumer.key, 'app name')
-        self.assertEqual(
-            loaded_credentials.consumer.secret, 'consumer_secret:42')
-        self.assertEqual(
-            loaded_credentials.access_token.key, 'access_key:84')
-        self.assertEqual(
-            loaded_credentials.access_token.secret, 'access_secret:168')
-
-    def test_new_credentials_are_secure(self):
-        # The newly created credentials file is only readable and
-        # writable by the user.
-        launchpad = NoNetworkLaunchpad.login_with(
-            'app name', launchpadlib_dir=self.temp_dir,
-            service_root='http://api.example.com/beta')
-        credentials_path = os.path.join(
-            self.temp_dir, 'api.example.com', 'credentials', 'app name')
-        statinfo = os.stat(credentials_path)
-        mode = stat.S_IMODE(statinfo.st_mode)
-        self.assertEqual(mode, stat.S_IWRITE | stat.S_IREAD)
-
-    def test_existing_credentials_are_reused(self):
-        # If a credential file for the application already exists, that
-        # one is used.
-        os.makedirs(
-            os.path.join(self.temp_dir, 'api.example.com', 'credentials'))
-        credentials_file_path = os.path.join(
-            self.temp_dir, 'api.example.com', 'credentials', 'app name')
-        credentials = Credentials(
-            'app name', consumer_secret='consumer_secret:42',
-            access_token=AccessToken('access_key:84', 'access_secret:168'))
-        credentials.save_to_path(credentials_file_path)
-
-        launchpad = NoNetworkLaunchpad.login_with(
-            'app name', launchpadlib_dir=self.temp_dir,
-            service_root='http://api.example.com/beta')
-        self.assertFalse(launchpad.get_token_and_login_called)
-        self.assertEqual(launchpad.credentials.consumer.key, 'app name')
-        self.assertEqual(
-            launchpad.credentials.consumer.secret, 'consumer_secret:42')
-        self.assertEqual(
-            launchpad.credentials.access_token.key, 'access_key:84')
-        self.assertEqual(
-            launchpad.credentials.access_token.secret, 'access_secret:168')
-
     def test_existing_credentials_arguments_passed_on(self):
         # When re-using existing credentials, the arguments login_with
         # is called with are passed on the the __init__() method.
@@ -313,21 +450,22 @@
             access_token=AccessToken('access_key:84', 'access_secret:168'))
         credentials.save_to_path(credentials_file_path)
 
-        service_root = 'http://api.example.com/'
         timeout = object()
         proxy_info = object()
         version = "foo"
         launchpad = NoNetworkLaunchpad.login_with(
             'app name', launchpadlib_dir=self.temp_dir,
-            service_root=service_root, timeout=timeout, proxy_info=proxy_info,
+            service_root=SERVICE_ROOT, timeout=timeout, proxy_info=proxy_info,
             version=version)
         expected_arguments = dict(
-            service_root=service_root,
+            service_root=SERVICE_ROOT,
             timeout=timeout,
             proxy_info=proxy_info,
             version=version,
             cache=os.path.join(self.temp_dir, 'api.example.com', 'cache'))
-        self.assertEqual(launchpad.passed_in_kwargs, expected_arguments)
+        for key, expected in expected_arguments.items():
+            actual = launchpad.passed_in_args[key]
+            self.assertEqual(actual, expected)
 
     def test_None_launchpadlib_dir(self):
         # If no launchpadlib_dir is passed in to login_with,
@@ -335,32 +473,30 @@
         old_home = os.environ['HOME']
         os.environ['HOME'] = self.temp_dir
         launchpad = NoNetworkLaunchpad.login_with(
-            'app name', service_root='http://api.example.com/beta')
+            'app name', service_root=SERVICE_ROOT)
         # Reset the environment to the old value.
         os.environ['HOME'] = old_home
 
-        cache_dir = launchpad.passed_in_kwargs['cache']
+        cache_dir = launchpad.passed_in_args['cache']
         launchpadlib_dir = os.path.abspath(
             os.path.join(cache_dir, '..', '..'))
         self.assertEqual(
             launchpadlib_dir, os.path.join(self.temp_dir, '.launchpadlib'))
         self.assertTrue(os.path.exists(
             os.path.join(launchpadlib_dir, 'api.example.com', 'cache')))
-        self.assertTrue(os.path.exists(
-            os.path.join(launchpadlib_dir, 'api.example.com', 'credentials')))
 
     def test_short_service_name(self):
         # A short service name is converted to the full service root URL.
         launchpad = NoNetworkLaunchpad.login_with('app name', 'staging')
         self.assertEqual(
-            launchpad.passed_in_kwargs['service_root'],
+            launchpad.passed_in_args['service_root'],
             'https://api.staging.launchpad.net/')
 
         # A full URL as the service name is left alone.
         launchpad = NoNetworkLaunchpad.login_with(
             'app name', uris.service_roots['staging'])
         self.assertEqual(
-            launchpad.passed_in_kwargs['service_root'],
+            launchpad.passed_in_args['service_root'],
             uris.service_roots['staging'])
 
         # A short service name that does not match one of the
@@ -370,27 +506,143 @@
         self.assertRaises(
             ValueError, NoNetworkLaunchpad.login_with, 'app name', 'foo')
 
-    def test_separate_credentials_file(self):
-        my_credentials_path = os.path.join(self.temp_dir, 'my_creds') 
-        launchpad = NoNetworkLaunchpad.login_with(
-            'app name', launchpadlib_dir=self.temp_dir,
-            credentials_file=my_credentials_path,
-            service_root='http://api.example.com/beta')
-        default_credentials_path = os.path.join(
-            self.temp_dir, 'api.example.com', 'credentials', 'app name')
-        self.assertFalse(os.path.exists(default_credentials_path))
-        self.assertTrue(os.path.exists(my_credentials_path))
-
-        self.assertTrue(launchpad.get_token_and_login_called)
-
-        # gets reused, too
-        launchpad = NoNetworkLaunchpad.login_with(
-            'app name', launchpadlib_dir=self.temp_dir,
-            credentials_file=my_credentials_path,
-            service_root='http://api.example.com/beta')
-        self.assertFalse(os.path.exists(default_credentials_path))
-        self.assertTrue(os.path.exists(my_credentials_path))
-        self.assertFalse(launchpad.get_token_and_login_called)
+    def test_max_failed_attempts_accepted(self):
+        # You can pass in a value for the 'max_failed_attempts'
+        # argument, even though that argument doesn't do anything.
+        NoNetworkLaunchpad.login_with(
+            'not important', max_failed_attempts=5)
+
+
+class TestDeprecatedLoginMethods(KeyringTest):
+    """Make sure the deprecated login methods still work."""
+
+    def test_login_is_deprecated(self):
+        # login() works but triggers a deprecation warning.
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            launchpad = NoNetworkLaunchpad.login(
+                'consumer', 'token', 'secret')
+            self.assertEquals(len(caught), 1)
+            self.assertEquals(caught[0].category, DeprecationWarning)
+
+    def test_get_token_and_login_is_deprecated(self):
+        # get_token_and_login() works but triggers a deprecation warning.
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            launchpad = NoNetworkLaunchpad.get_token_and_login('consumer')
+            self.assertEquals(len(caught), 1)
+            self.assertEquals(caught[0].category, DeprecationWarning)
+
+
+class TestCredenitialSaveFailedCallback(unittest.TestCase):
+    # There is a callback which will be called if saving the credentials
+    # fails.
+
+    def setUp(self):
+        # launchpadlib.launchpad uses the socket module to look up the
+        # hostname, obviously that can vary so we replace the socket module
+        # with a fake that returns a fake hostname.
+        launchpadlib.launchpad.socket = FauxSocketModule()
+        self.temp_dir = tempfile.mkdtemp()
+
+    def tearDown(self):
+        launchpadlib.launchpad.socket = socket
+        shutil.rmtree(self.temp_dir)
+
+    def test_credentials_save_failed(self):
+        # If saving the credentials did not succeed and a callback was
+        # provided, it is called.
+
+        callback_called = []
+        def callback():
+            # Since we can't rebind "callback_called" here, we'll have to
+            # settle for mutating it to signal success.
+            callback_called.append(None)
+
+        launchpadlib_dir = os.path.join(self.temp_dir, 'launchpadlib')
+        service_root = "http://api.example.com/"
+        with fake_keyring(BadSaveKeyring()):
+            NoNetworkLaunchpad.login_with(
+                'not important', service_root=service_root,
+                launchpadlib_dir=launchpadlib_dir,
+                credential_save_failed=callback)
+            self.assertEquals(len(callback_called), 1)
+
+    def test_default_credentials_save_failed_is_to_raise_exception(self):
+        # If saving the credentials did not succeed and no callback was
+        # provided, the underlying exception is raised.
+        launchpadlib_dir = os.path.join(self.temp_dir, 'launchpadlib')
+        service_root = "http://api.example.com/"
+        with fake_keyring(BadSaveKeyring()):
+            self.assertRaises(
+                RuntimeError,
+                NoNetworkLaunchpad.login_with,
+                'not important', service_root=service_root,
+                launchpadlib_dir=launchpadlib_dir)
+
+
+class TestMultipleSites(unittest.TestCase):
+    # If the same application name (consumer name) is used to access more than
+    # one site, the credentials need to be stored seperately.  Therefore, the
+    # "username" passed ot the keyring includes the service root.
+
+    def setUp(self):
+        # launchpadlib.launchpad uses the socket module to look up the
+        # hostname, obviously that can vary so we replace the socket module
+        # with a fake that returns a fake hostname.
+        launchpadlib.launchpad.socket = FauxSocketModule()
+        self.temp_dir = tempfile.mkdtemp()
+
+    def tearDown(self):
+        launchpadlib.launchpad.socket = socket
+        shutil.rmtree(self.temp_dir)
+
+    def test_components_of_application_key(self):
+        launchpadlib_dir = os.path.join(self.temp_dir, 'launchpadlib')
+        keyring = InMemoryKeyring()
+        service_root = 'http://api.example.com/'
+        application_name = 'Super App 3000'
+        with fake_keyring(keyring):
+            launchpad = NoNetworkLaunchpad.login_with(
+                application_name, service_root=service_root,
+                launchpadlib_dir=launchpadlib_dir)
+            consumer_name = launchpad.credentials.consumer.key
+
+        application_key = keyring.data.keys()[0][1]
+
+        # Both the consumer name (normally the name of the application) and
+        # the service root (the URL of the service being accessed) are
+        # included in the key when storing credentials.
+        self.assert_(service_root in application_key)
+        self.assert_(consumer_name in application_key)
+
+        # The key used to store the credentials is of this structure (and
+        # shouldn't change between releases or stored credentials will be
+        # "forgotten").
+        self.assertEquals(application_key, consumer_name + '@' + service_root)
+
+    def test_same_app_different_servers(self):
+        launchpadlib_dir = os.path.join(self.temp_dir, 'launchpadlib')
+        keyring = InMemoryKeyring()
+        # Be paranoid about the keyring starting out empty.
+        assert not keyring.data, 'oops, a fresh keyring has data in it'
+        with fake_keyring(keyring):
+            # Create stored credentials for the same application but against
+            # two different sites (service roots).
+            NoNetworkLaunchpad.login_with(
+                'application name', service_root='http://alpha.example.com/',
+                launchpadlib_dir=launchpadlib_dir)
+            NoNetworkLaunchpad.login_with(
+                'application name', service_root='http://beta.example.com/',
+                launchpadlib_dir=launchpadlib_dir)
+
+        # There should only be two sets of stored credentials (this assertion
+        # is of the test mechanism, not a test assertion).
+        assert len(keyring.data.keys()) == 2
+
+        application_key_1 = keyring.data.keys()[0][1]
+        application_key_2 = keyring.data.keys()[1][1]
+        self.assertNotEqual(application_key_1, application_key_2)
 
 
 def test_suite():
 
=== modified file 'src/launchpadlib/uris.py'
--- src/launchpadlib/uris.py	2010-12-07 19:30:29 +0000
+++ src/launchpadlib/uris.py	2011-02-08 19:01:02 +0000
@@ -16,27 +16,29 @@
 
 """Launchpad-specific URIs and convenience lookup functions.
 
-The code in this module lets users say "edge" when they mean
-"https://api.edge.launchpad.net/".
+The code in this module lets users say "staging" when they mean
+"https://api.staging.launchpad.net/".
 """
 
 __metaclass__ = type
 __all__ = [
     'lookup_service_root',
     'lookup_web_root',
+    'web_root_for_service_root',
     ]
 
 from urlparse import urlparse
+from lazr.uri import URI
 
 LPNET_SERVICE_ROOT = 'https://api.launchpad.net/'
-EDGE_SERVICE_ROOT = 'https://api.edge.launchpad.net/'
+QASTAGING_SERVICE_ROOT = 'https://api.qastaging.launchpad.net/'
 STAGING_SERVICE_ROOT = 'https://api.staging.launchpad.net/'
 DEV_SERVICE_ROOT = 'https://api.launchpad.dev/'
 DOGFOOD_SERVICE_ROOT = 'https://api.dogfood.launchpad.net/'
 TEST_DEV_SERVICE_ROOT = 'http://api.launchpad.dev:8085/'
 
 LPNET_WEB_ROOT = 'https://launchpad.net/'
-EDGE_WEB_ROOT = 'https://edge.launchpad.net/'
+QASTAGING_WEB_ROOT = 'https://qastaging.launchpad.net/'
 STAGING_WEB_ROOT = 'https://staging.launchpad.net/'
 DEV_WEB_ROOT = 'https://launchpad.dev/'
 DOGFOOD_WEB_ROOT = 'https://dogfood.launchpad.net/'
@@ -45,7 +47,7 @@
 
 service_roots = dict(
     production=LPNET_SERVICE_ROOT,
-    edge=EDGE_SERVICE_ROOT,
+    qastaging=QASTAGING_SERVICE_ROOT,
     staging=STAGING_SERVICE_ROOT,
     dogfood=DOGFOOD_SERVICE_ROOT,
     dev=DEV_SERVICE_ROOT,
@@ -55,7 +57,7 @@
 
 web_roots = dict(
     production=LPNET_WEB_ROOT,
-    edge=EDGE_WEB_ROOT,
+    qastaging=QASTAGING_WEB_ROOT,
     staging=STAGING_WEB_ROOT,
     dogfood=DOGFOOD_WEB_ROOT,
     dev=DEV_WEB_ROOT,
@@ -81,7 +83,7 @@
 def lookup_service_root(service_root):
     """Dereference an alias to a service root.
 
-    A recognized server alias such as "edge" gets turned into the
+    A recognized server alias such as "staging" gets turned into the
     appropriate URI. A URI gets returned as is. Any other string raises a
     ValueError.
     """
@@ -91,9 +93,21 @@
 def lookup_web_root(web_root):
     """Dereference an alias to a website root.
 
-    A recognized server alias such as "edge" gets turned into the
+    A recognized server alias such as "staging" gets turned into the
     appropriate URI. A URI gets returned as is. Any other string raises a
     ValueError.
     """
     return _dereference_alias(web_root, web_roots)
 
+
+def web_root_for_service_root(service_root):
+    """Turn a service root URL into a web root URL.
+
+    This is done heuristically, not with a lookup.
+    """
+    service_root = lookup_service_root(service_root)
+    web_root_uri = URI(service_root)
+    web_root_uri.path = ""
+    web_root_uri.host = web_root_uri.host.replace("api.", "", 1)
+    web_root = str(web_root_uri.ensureSlash())
+    return web_root
 
=== removed file 'src/launchpadlib/wadl-to-refhtml.xsl'
--- src/launchpadlib/wadl-to-refhtml.xsl	2010-12-07 19:30:29 +0000
+++ src/launchpadlib/wadl-to-refhtml.xsl	1970-01-01 00:00:00 +0000
@@ -1,1045 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-  wadl-to-refhtml.xsl
-
-  Generate HTML documentation for a webservice described in a WADL file.
-  This is tailored to WADL generated by Launchpad's web service.
-
-  Based on wadl_documentaion.xsl from Mark Nottingham <[e-mail]>
-  that can be found at http://www.mnot.net/webdesc/
-  Copyright (c) 2006-2007 Yahoo! Inc.
-  Copyright (c) 2008 Canonical Ltd.
-
-  This work is licensed under the Creative Commons Attribution-ShareAlike 2.5
-  License. To view a copy of this license, visit
-    http://creativecommons.org/licenses/by-sa/2.5/
-  or send a letter to
-    Creative Commons
-    543 Howard Street, 5th Floor
-    San Francisco, California, 94105, USA
--->
-
-<xsl:stylesheet
- xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
- xmlns:wadl="http://research.sun.com/wadl/2006/10"
- xmlns:html="http://www.w3.org/1999/xhtml"
- xmlns="http://www.w3.org/1999/xhtml"
- exclude-result-prefixes="xsl wadl html"
->
-    <xsl:output
-        method="xml"
-        encoding="UTF-8"
-        indent="yes"
-        doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN"
-        doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"
-    />
-
-
-    <!-- Allow using key('id', 'people') to identify unique elements, since
-    the document doesn't have a parsed DTD.
-    -->
-    <xsl:key name="id" match="*[@id]" use="@id"/>
-
-    <!-- Embedded stylesheet. -->
-    <xsl:template name="css-stylesheet">
-        <style type="text/css">
-            body {
-                font-family: sans-serif;
-                font-size: 0.85em;
-                margin: 2em 8em;
-            }
-            .methods {
-                background-color: #eef;
-                padding: 1em;
-                margin-bottom: 0.5em;
-            }
-            .method {
-                padding-left: 4em;
-            }
-            h1 {
-                font-size: 2.5em;
-            }
-            h2 {
-                border-bottom: 1px solid black;
-                margin-top: 1em;
-                margin-bottom: 0.5em;
-                font-size: 2em;
-               }
-            h3 {
-                color: orange;
-                font-size: 1.75em;
-                margin-top: 1.25em;
-                margin-bottom: 0em;
-            }
-            h4 {
-                font-size: 1.50em;
-                margin: 0em;
-                padding: 0em;
-                border-bottom: 2px solid white;
-            }
-            h5 {
-                font-size: 1.25em;
-                margin-left: -3em;
-            }
-            h6 {
-                font-size: 1.1em;
-                color: #99a;
-                margin: 0.5em 0em 0.25em 0em;
-            }
-            dd {
-                margin-left: 1em;
-            }
-            tt, code {
-                font-size: 1.2em;
-            }
-            table {
-                margin-bottom: 0.5em;
-            }
-            th {
-                text-align: left;
-                font-weight: normal;
-                color: black;
-                border-bottom: 1px solid black;
-                padding: 3px 6px;
-            }
-            td {
-                padding: 3px 6px;
-                vertical-align: top;
-                background-color: #f6f6ff;
-                font-size: 0.85em;
-            }
-            td p {
-                margin: 0px;
-            }
-            ul {
-                padding-left: 1.75em;
-            }
-            p + ul, p + ol, p + dl {
-                margin-top: 0em;
-            }
-            label {
-                font-weight: bold;
-            }
-            .optional {
-                font-weight: normal;
-                opacity: 0.75;
-            }
-            .toc-link {
-                font-size: 0.85em;
-            }
-        </style>
-    </xsl:template>
-
-    <!-- Contains the base URL for the webservice without a trailing
-         slash.  -->
-    <xsl:variable name="base">
-        <xsl:variable name="uri" select="//wadl:resources/@base"/>
-        <xsl:choose>
-            <xsl:when
-                test="substring($uri, string-length($uri) , 1) = '/'">
-                <xsl:value-of
-                    select="substring($uri, 1, string-length($uri) - 1)"/>
-            </xsl:when>
-            <xsl:otherwise>
-                <xsl:value-of select="$uri"/>
-            </xsl:otherwise>
-        </xsl:choose>
-    </xsl:variable>
-
-    <!-- Generate the URL to the top-level collection. -->
-    <xsl:template name="resource-uri-doc">
-        <xsl:param name="url"><xsl:value-of
-                select="$base"/>/<xsl:value-of select="@id"/></xsl:param>
-        <p><label>URL:</label>
-            <code><xsl:copy-of select="$url" /></code></p>
-    </xsl:template>
-
-    <xsl:template name="entry-uri-doc">
-        <xsl:call-template name="resource-uri-doc">
-            <xsl:with-param name="url">
-                <xsl:choose>
-                    <xsl:when test="@id = 'has_milestones'
-                                    or @id = 'bug_target'
-                                    or @id = 'has_bugs'">
-                        <em>depends on the underlying entry</em>
-                    </xsl:when>
-                    <xsl:otherwise>
-                        <xsl:call-template name="find-entry-uri"/>
-                     </xsl:otherwise>
-                 </xsl:choose>
-            </xsl:with-param>
-        </xsl:call-template>
-    </xsl:template>
-
-    <xsl:template name="find-entry-uri">
-        <xsl:value-of select="$base"/>
-        <xsl:choose>
-            <xsl:when test="@id = 'archive'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;distribution&gt;</var>
-                <xsl:text>/+archive/</xsl:text>
-                <var>&lt;archive.name&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'archive_permission'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;archive.distribution&gt;</var>
-                <xsl:text>/+archive/</xsl:text>
-                <var>&lt;archive.name&gt;</var>
-                <xsl:text>/+</xsl:text>
-                <xsl:text>name</xsl:text>
-                <xsl:text>/</xsl:text>
-                <xsl:text>person.name</xsl:text>
-                <xsl:text>.</xsl:text>
-                <xsl:text>[component or source package].name</xsl:text>
-            </xsl:when>
-            <xsl:when test="@id = 'binary_package_publishing_history'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;distribution.name&gt;</var>
-                <xsl:text>/+archive/</xsl:text>
-                <var>&lt;binary_package.name&gt;</var>
-                <xsl:text>/+binarypub/</xsl:text>
-                <var>&lt;id&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'branch'">
-                <xsl:text>/~</xsl:text>
-                <var>&lt;author.name&gt;</var>
-                <xsl:text>/</xsl:text>
-                <var>&lt;project.name&gt;</var>
-                <xsl:text>/</xsl:text>
-                <var>&lt;name&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'branch_merge_proposal'">
-                <xsl:text>/~</xsl:text>
-                <var>&lt;author.name&gt;</var>
-                <xsl:text>/</xsl:text>
-                <var>&lt;project.name&gt;</var>
-                <xsl:text>/</xsl:text>
-                <var>&lt;branch.name&gt;</var>
-                <xsl:text>/+merge/</xsl:text>
-                <var>&lt;id&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'bug'">
-                <xsl:text>/bugs/</xsl:text><var>&lt;id&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'bug_attachment'">
-                <xsl:text>/bugs/</xsl:text>
-                <var>&lt;bug.id&gt;</var>
-                <xsl:text>/attachments/</xsl:text>
-                <var>&lt;id&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'bug_subscription'">
-                <xsl:text>/bugs/</xsl:text>
-                <var>&lt;bug.id&gt;</var>
-                <xsl:text>/subscriptions/</xsl:text>
-                <var>&lt;subscriber.name&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'bug_task'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;target.name&gt;</var>
-                <xsl:text>/+bug/</xsl:text>
-                <var >&lt;bug.id&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'bug_watch'">
-                <xsl:text>/bugs/</xsl:text>
-                <var>&lt;bug.id&gt;</var>
-                <xsl:text>/watch/</xsl:text>
-                <var>&lt;id&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'bug_tracker'">
-                <xsl:text>/bugs/bugtrackers/</xsl:text>
-                <var>&lt;name&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'build'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;distribution.name&gt;</var>
-                <xsl:text>/+source/</xsl:text>
-                <var>&lt;source_package.name&gt;</var>
-                <xsl:text>/+build/</xsl:text>
-                <var>&lt;id&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'cve'">
-                <xsl:text>/bugs/cve/</xsl:text>
-                <var>&lt;sequence&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'distribution_source_package'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;distribution.name&gt;</var>
-                <xsl:text>/+source/</xsl:text>
-                <var>&lt;name&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'distro_arch_series'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;distribution.name&gt;</var>
-                <xsl:text>/</xsl:text>
-                <var>&lt;distroseries.name&gt;</var>
-                <xsl:text>/</xsl:text>
-                <var>&lt;architecture_tag&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'distro_series'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;distribution.name&gt;</var>
-                <xsl:text>/</xsl:text>
-                <var>&lt;name&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'email_address'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;person.name&gt;</var>
-                <xsl:text>/+email/</xsl:text>
-                <var>&lt;email&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'h_w_device'">
-                <xsl:text>/+hwdb/+device/</xsl:text>
-                <var>&lt;id&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'h_w_device_class'">
-                <xsl:text>/+hwdb/+deviceclass/</xsl:text>
-                <var>&lt;id&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'h_w_driver'">
-                <xsl:text>/+hwdb/+driver/</xsl:text>
-                <var>&lt;id&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'h_w_submission'">
-                <xsl:text>/+hwdb/+submission/</xsl:text>
-                <var>&lt;submission-key&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'h_w_submission_device'">
-                <xsl:text>/+hwdb/+submissiondevice/</xsl:text>
-                <var>&lt;id&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'h_w_vendor_i_d'">
-                <xsl:text>/+hwdb/+hwvendorid/</xsl:text>
-                <var>&lt;id&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'jabber_id'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;person.name&gt;</var>
-                <xsl:text>/+jabberid/</xsl:text>
-                <var>&lt;id&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'irc_id'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;person.name&gt;</var>
-                <xsl:text>/+ircnick/</xsl:text>
-                <var>&lt;id&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'language'">
-                <xsl:text>/+languages/</xsl:text>
-                <var>&lt;code&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'message'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;target.name&gt;</var>
-                <xsl:text>/+bug/</xsl:text>
-                <var>&lt;bug.id&gt;</var>
-                <xsl:text>/comments/</xsl:text>
-                <var>&lt;index&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'milestone'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;target.name&gt;</var>
-                <xsl:text>/+milestone/</xsl:text>
-                <var>&lt;name&gt;</var>
-            </xsl:when>
-            <xsl:when test="   @id = 'distribution'
-                            or @id = 'pillar'
-                            or @id = 'product'
-                            or @id = 'project'
-                            or @id = 'project_group'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;name&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'team' or @id = 'person'">
-                <xsl:text>/~</xsl:text>
-                <var>&lt;name&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'product_release'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;product.name&gt;</var>
-                <xsl:text>/</xsl:text>
-                <var>&lt;product_series.name&gt;</var>
-                <xsl:text>/</xsl:text>
-                <var>&lt;name&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'product_series'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;product.name&gt;</var>
-                <xsl:text>/</xsl:text>
-                <var>&lt;name&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'project_release'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;project.name&gt;</var>
-                <xsl:text>/</xsl:text>
-                <var>&lt;project_series.name&gt;</var>
-                <xsl:text>/</xsl:text>
-                <var>&lt;release.version&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'project_release_file'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;project.name&gt;</var>
-                <xsl:text>/</xsl:text>
-                <var>&lt;project_series.name&gt;</var>
-                <xsl:text>/</xsl:text>
-                <var>&lt;release.version&gt;</var>
-                <xsl:text>/+file/</xsl:text>
-                <var>&lt;hosted_file.filename&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'project_series'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;project.name&gt;</var>
-                <xsl:text>/</xsl:text>
-                <var>&lt;name&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'source_package'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;distribution.name&gt;</var>
-                <xsl:text>/</xsl:text>
-                <var>&lt;distro_series.name&gt;</var>
-                <xsl:text>/+source/</xsl:text>
-                <var>&lt;name&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'source_package_publishing_history'">
-                <xsl:text>/</xsl:text>
-                <var>&lt;distribution&gt;</var>
-                <xsl:text>/+archive/</xsl:text>
-                <var>&lt;name&gt;</var>
-                <xsl:text>/+sourcepub/</xsl:text>
-                <var>&lt;id&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'team_membership'">
-                <xsl:text>/~</xsl:text>
-                <var>&lt;team.name&gt;</var>
-                <xsl:text>/+member/</xsl:text>
-                <var>&lt;member.name&gt;</var>
-            </xsl:when>
-            <xsl:when test="@id = 'wiki_name'">
-                <xsl:text>/~</xsl:text>
-                <var>&lt;person.name&gt;</var>