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

[Leonard Richardson]

[Leonard Richardson (leonardr)]

This branch does some refactoring and adds some more tests for the RequestTokenAuthorizationEngine, the core of any trusted request token authorization client other than the end-user's web browser.

1. The class itself is renamed from AuthorizeRequestTokenProcess to RequestTokenAuthorizationEngine. RTAE is not the best name but I found ARTP really confusing.

2. RTAE no longer overwrites 'allow_access_levels' after it gets the token information. This lets me use the same RTAE object twice in tests.

3. Added code to detect when Launchpad doesn't recognize the request token.

4. Gave default implementations for a lot of the RTAE plugin methods, which just print the suggested_message. I already defined this code in the ScriptableRequestTokenAuthorization test helper, and I don't want to define it again for the command-line client.

5. Added tests for trying to approve a token that was already approved, trying to approve a nonexistent token, and triggering a server error.

[Abel Deuring (adeuring)]

review: Approve (code)

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

72. By Leonard Richardson on 2009-10-30

Fixed up tests and return codes.

73. By Leonard Richardson on 2009-10-30

Added docstrings.

74. By Leonard Richardson on 2009-10-30

Cleaned up the exit function.

75. By Leonard Richardson on 2009-10-30

Added another docstring.

76. By Leonard Richardson on 2009-10-30

Added the command-line script, made a lot of spacing tweaks.

77. By Leonard Richardson on 2009-10-30

Merged with trunk.

=== modified file 'src/launchpadlib/apps.py'
--- src/launchpadlib/apps.py	2009-10-28 17:27:53 +0000
+++ src/launchpadlib/apps.py	2009-10-30 19:21:14 +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("-" * len(start))
+
+        try:
+            self()
+        except TokenAuthorizationException, e:
+            print str(e)
+            self.error_code = -1
+            return self.pressEnterToExit()
+        return self.pressEnterToExit()
+
+    def exit_with(self, code):
+        """Exit the app with the specified error code."""
+        sys.exit(code)
+
+    def getSingleCharInput(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 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
+
+    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.getSingleCharInput(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.getSingleCharInput(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-10-30 19:21:14 +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-10-30 19:21:14 +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-10-30 19:21:14 +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)
+    >>> ignore = 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
+    >>> ignore = 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)
+
+    >>> ignore = 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
+
+    >>> ignore = 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
+    >>> ignore = 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-10-30 19:21:14 +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)