Merge lp:~leonardr/launchpadlib/trusted-workflow-tests-2 into lp:launchpadlib

[Leonard Richardson]

[Leonard Richardson (leonardr)]

This branch creates a TrustedTokenAuthorizationConsoleApp, a console application that guides the end-user through the process of authorizing a request token. It creates a lot of doctests for the App object and a small command-line script that invokes it. The doctests use the new UserInput class which simulates a user typing things into a console application.

There are a lot of small spacing tweaks in this branch to make the application look good when run from the command line. These changes don't necessarily show up in the doctests, which are much more lenient about whitespace.

In addition to the doctests I manually ran the console application to test things that can't be automatically tested such as the use of getpass and the opening of a page in the web browser.

[lp:~leonardr/launchpadlib/trusted-workflow-tests-2]

77. By Leonard Richardson on 2009-10-30

Merged with trunk.

[Guilherme Salgado (salgado)]

On Fri, 2009-10-30 at 17:35 +0000, Leonard Richardson wrote:
> Leonard Richardson has proposed merging lp:~leonardr/launchpadlib/trusted-workflow-tests-2 into lp:launchpadlib.
>
> Requested reviews:
> LAZR Developers (lazr-developers)
>
>
> This branch creates a TrustedTokenAuthorizationConsoleApp, a console
> application that guides the end-user through the process of
> authorizing a request token. It creates a lot of doctests for the App
> object and a small command-line script that invokes it. The doctests
> use the new UserInput class which simulates a user typing things into
> a console application.
>
> There are a lot of small spacing tweaks in this branch to make the
> application look good when run from the command line. These changes
> don't necessarily show up in the doctests, which are much more lenient
> about whitespace.

Did you consider changing your tests to run without the
NORMALIZE_WHITESPACE option, which is enabled by default for all our
tests? But I guess there's no real benefit in making the test more
fragile just to show that the app looks good when running on the command
line.

>
> In addition to the doctests I manually ran the console application to
> test things that can't be automatically tested such as the use of
> getpass and the opening of a page in the web browser.
> --

> === modified file 'src/launchpadlib/apps.py'
> --- src/launchpadlib/apps.py 2009-10-28 17:27:53 +0000
> +++ src/launchpadlib/apps.py 2009-10-30 17:35:17 +0000
> @@ -20,9 +20,18 @@
> themselves are kept in bin/.
> """
>
> +__all__ = [
> + 'RequestTokenApp',
> + 'TrustedTokenAuthorizationConsoleApp',
> + ]
> +
> +import getpass
> +import sys
> +
> import simplejson
>
> -from launchpadlib.credentials import Credentials
> +from launchpadlib.credentials import (
> + Credentials, RequestTokenAuthorizationEngine, TokenAuthorizationException)
> from launchpadlib.uris import lookup_web_root
>
>
> @@ -43,3 +52,124 @@
> 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("-" ...

[Guilherme Salgado (salgado)]

On Fri, 2009-10-30 at 17:29 -0200, Guilherme Salgado wrote:
>
> > + return self.pressEnterToExit()
> > +
> > + def exit_with(self, code):
>
> Why is this not exitWith()?

As you explained to me on IRC, this is because you're using the python
naming standard instead of the LP one. Fair enough, but the two methods
below use the LP one. Care to rename them?

And here's a review of the two remaining files, which had conflicts when
I first reviewed your branch. Just one question, in fact.

> === modified file 'src/launchpadlib/credentials.py'
> --- src/launchpadlib/credentials.py 2009-10-30 14:48:21 +0000
> +++ src/launchpadlib/credentials.py 2009-10-30 19:55:30 +0000
> @@ -289,16 +291,20 @@
>
> def __init__(self, web_root, consumer_name, request_token,
> allow_access_levels=[], max_failed_attempts=3):
> - self.web_root = web_root
> + self.web_root = uris.lookup_web_root(web_root)

What's the reason for this change?

> 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)
>

[Leonard Richardson (leonardr)]

> > + try:
> > + self()
> > + except TokenAuthorizationException, e:
> > + print str(e)
> > + self.error_code = -1
> > + return self.pressEnterToExit()
>
> The above call is redundant because of the one below, no?
>
> > + return self.pressEnterToExit()

Yes, I've removed the redundant call.

> > + def pressEnterToExit(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)
> > + return self.error_code
>
> Since exit_with() will call sys.exit(), there's no reason to return
> anything here, is there?

The default implementation of exit_with() calls sys.exit(), but my testing version returned the error code. However I was just ignoring the error code in my tests, so it's not necessary.

[Leonard Richardson (leonardr)]

> As you explained to me on IRC, this is because you're using the python
> naming standard instead of the LP one. Fair enough, but the two methods
> below use the LP one. Care to rename them?

I've renamed getSingleCharInput and pressEnterToExit.

> And here's a review of the two remaining files, which had conflicts when
> I first reviewed your branch. Just one question, in fact.
>
> > === modified file 'src/launchpadlib/credentials.py'
> > --- src/launchpadlib/credentials.py 2009-10-30 14:48:21 +0000
> > +++ src/launchpadlib/credentials.py 2009-10-30 19:55:30 +0000
> > @@ -289,16 +291,20 @@
> >
> > def __init__(self, web_root, consumer_name, request_token,
> > allow_access_levels=[], max_failed_attempts=3):
> > - self.web_root = web_root
> > + self.web_root = uris.lookup_web_root(web_root)
>
> What's the reason for this change?

I think I explained this on IRC too, but for the record: lookup_web_root lets you pass in "staging" as the site root instead of "https://staging.launchpad.net/".

[lp:~leonardr/launchpadlib/trusted-workflow-tests-2]

78. By Leonard Richardson on 2009-11-02

Response to feedback.

[Gary Poster (gary)]

Approving on Salgado's behalf because Leonard appears to have addressed his concerns and Salgado is not available today.

review: Approve

=== modified file 'src/launchpadlib/apps.py'
--- src/launchpadlib/apps.py	2009-10-28 17:27:53 +0000
+++ src/launchpadlib/apps.py	2009-11-02 12:35:19 +0000
@@ -20,9 +20,18 @@
 themselves are kept in bin/.
 """
 
+__all__ = [
+    'RequestTokenApp',
+    'TrustedTokenAuthorizationConsoleApp',
+    ]
+
+import getpass
+import sys
+
 import simplejson
 
-from launchpadlib.credentials import Credentials
+from launchpadlib.credentials import (
+    Credentials, RequestTokenAuthorizationEngine, TokenAuthorizationException)
 from launchpadlib.uris import lookup_web_root
 
 
@@ -43,3 +52,122 @@
         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
 
=== added file 'src/launchpadlib/bin/launchpad-credentials-console'
--- src/launchpadlib/bin/launchpad-credentials-console	1970-01-01 00:00:00 +0000
+++ src/launchpadlib/bin/launchpad-credentials-console	2009-11-02 12:35:19 +0000
@@ -0,0 +1,54 @@
+#!/usr/bin/python
+
+# Copyright 2009 Canonical Ltd.
+
+# This file is part of launchpadlib.
+#
+# launchpadlib is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Lesser General Public License as published by the
+# Free Software Foundation, version 3 of the License.
+#
+# launchpadlib is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+# for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with launchpadlib. If not, see <http://www.gnu.org/licenses/>.
+
+"""Take the user's Launchpad credentials and authorize a request token.
+
+This script will guide the user through the process of authorizing a
+request token with their username and password. It's not as secure as
+opening the user's web browser, but if you are writing a console
+application and want to keep the authorization process console-based,
+it's better to use this script than write the authorization code yourself.
+"""
+
+__metaclass__ = type
+
+from optparse import OptionParser
+from launchpadlib.apps import (
+    RequestTokenApp, TrustedTokenAuthorizationConsoleApp)
+
+parser = OptionParser()
+parser.usage = "%prog CONSUMER_NAME REQUEST_TOKEN [-r URL] [-a LEVEL,LEVEL,...]"
+parser.add_option("-s", "--site", dest="web_root",
+                  help=("The name of the Launchpad site on which the request "
+                        "token can be found (default: %default). This can "
+                        "also be the URL to the root of the site."),
+                  metavar="URL", default="staging")
+parser.add_option("-a", "--access-level", dest="access_levels",
+                  help="Any restrictions on your clients' access levels",
+                  metavar="[LEVEL,LEVEL,...]", default="")
+
+if __name__ == '__main__':
+    (options, args) = parser.parse_args()
+    if len(args) < 2:
+        parser.error("You must provide both a consumer name and the ID of "
+                     "an OAuth request token on Launchpad.")
+    consumer_name, token_id = args[:2]
+    TrustedTokenAuthorizationConsoleApp(
+        options.web_root, consumer_name, token_id,
+        options.access_levels).run()
+
 
=== modified file 'src/launchpadlib/credentials.py'
--- src/launchpadlib/credentials.py	2009-10-30 14:48:21 +0000
+++ src/launchpadlib/credentials.py	2009-11-02 12:35:19 +0000
@@ -27,8 +27,10 @@
 import base64
 import cgi
 import httplib2
+import textwrap
 from urllib import urlencode, quote
 from urlparse import urljoin
+import webbrowser
 
 import simplejson
 
@@ -265,7 +267,7 @@
 
     INPUT_USERNAME = "What email address do you use on Launchpad?"
 
-    INPUT_PASSWORD = "What's your Launchpad password?"
+    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."""
 
@@ -273,9 +275,9 @@
 
     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 = """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."""
 
-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."""
+    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." """
 
@@ -289,16 +291,20 @@
 
     def __init__(self, web_root, consumer_name, request_token,
                  allow_access_levels=[], max_failed_attempts=3):
-        self.web_root = web_root
+        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.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
@@ -315,14 +321,17 @@
             # 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['title'] for level in self.reconciled_access_levels
-                     if level['value'] != self.UNAUTHORIZED_ACCESS_LEVEL]
-            extra = {'level' : level[0]}
+            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))
+            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:
@@ -420,8 +429,8 @@
 
     # You should define these methods in your subclass.
 
-    def startup(self, suggested_message):
-        """Hook method called on startup."""
+    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.
@@ -435,22 +444,31 @@
         """Collect the Launchpad password from the end-user."""
         raise NotImplementedError()
 
-    def input_access_level(self, available_levels, suggested_message):
+    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."""
-        print suggested_message
+        self.output(suggested_message)
+        self.output("\n")
 
     def user_refused_to_authorize(self, suggested_message):
         """The user refused to authorize a request token."""
-        print suggested_message
+        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."""
-        print suggested_message
+        self.output(suggested_message)
+        self.output("\n")
 
     def server_consumer_differs_from_client_consumer(
         self, client_name, real_name, suggested_message):
@@ -461,11 +479,13 @@
         end-user that its name is "bar". Something is fishy and at the very
         least the end-user should be warned about this.
         """
-        print suggested_message
+        self.output("\n")
+        self.output(suggested_message)
+        self.output("\n")
 
     def success(self, suggested_message):
         """The token was successfully authorized."""
-        print suggested_message
+        self.output(suggested_message)
 
 
 class TokenAuthorizationException(Exception):
 
=== modified file 'src/launchpadlib/docs/command-line.txt'
--- src/launchpadlib/docs/command-line.txt	2009-10-27 16:26:06 +0000
+++ src/launchpadlib/docs/command-line.txt	2009-11-02 12:35:19 +0000
@@ -20,9 +20,11 @@
 
     >>> import simplejson
     >>> from launchpadlib.apps import RequestTokenApp
-    >>> app = RequestTokenApp(
-    ...     "http://launchpad.dev:8085/", "consumer", "context")
-    >>> json = simplejson.loads(app.run())
+
+    >>> web_root = "http://launchpad.dev:8085/"
+    >>> consumer_name = "consumer"
+    >>> token_app = RequestTokenApp(web_root, consumer_name, "context")
+    >>> json = simplejson.loads(token_app.run())
 
     >>> sorted(json.keys())
     ['access_levels', 'lp.context', 'oauth_token',
@@ -33,3 +35,171 @@
 
     >>> 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_login_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/testing/helpers.py'
--- src/launchpadlib/testing/helpers.py	2009-10-30 14:48:21 +0000
+++ src/launchpadlib/testing/helpers.py	2009-11-02 12:35:19 +0000
@@ -119,11 +119,36 @@
         print suggested_message
         return self.password
 
-    def input_access_level(self, available_levels, suggested_message):
+    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_message):
-        print suggested_message
+    def startup(self, suggested_messages):
+        for message in suggested_messages:
+            print message
+
+
+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)