************
launchpadlib
************

launchpadlib is the standalone Python language bindings to Launchpad's web
services API.  It is officially supported by Canonical, although third party
packages may be available to provide bindings to other programming languages.

OAuth authentication
====================

The Launchpad API requires user authentication via OAuth, and launchpadlib
provides a high level interface to OAuth for the most common use cases.
Several pieces of information are necessary to complete the OAuth request:

 * A consumer key, which is unique to the application using the API
 * An access token, which represents the user to the web service
 * An access token secret, essentially a password for the token

Consumer keys are hard-baked into the application.  They are generated by the
application developer and registered with Launchpad independently of the use
of the application.  Since consumer keys are arbitrary, a registered consumer
key can be paired with a secret, but most open source applications will forgo
this since it's not really a secret anyway.

The access token cannot be provided directly.  Instead, the application
generates an unauthenticated request token, exchanging this for an access
token and a secret after obtaining approval to do so from the user.  This
permission is typically gained by redirecting the user through their trusted
web browser, then back to the application.

This entire exchange is managed by launchpadlib's credentials classes.
Credentials can be stored in a file, though the security of this depends on
the implementation of the file object.  In the simplest case, the application
will request a new access token every time.

    >>> from launchpadlib.credentials import Consumer
    >>> consumer = Consumer('launchpad-library')
    >>> consumer.key
    'launchpad-library'
    >>> consumer.secret
    ''

Salgado has full access to the Launchpad API.  Out of band, the application
itself obtains Salgado's approval to access the Launchpad API on his behalf.
How the application does this is up to the application, provided it conforms
to the OAuth protocol.  Once this happens, we have Salgado's credentials for
accessing Launchpad.

    >>> from launchpadlib.credentials import AccessToken
    >>> access_token = AccessToken('salgado-change-anything', 'test')

And now these credentials are used to access the root service on Salgado's
behalf.

    >>> from launchpadlib.credentials import Credentials
    >>> credentials = Credentials(
    ...     consumer_name=consumer.key, consumer_secret=consumer.secret,
    ...     access_token=access_token)

    >>> from launchpadlib.testing.helpers import (
    ...     TestableLaunchpad as Launchpad)
    >>> launchpad = Launchpad(credentials=credentials)
    >>> sorted(launchpad.people)
    [...]
    >>> 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.

    >>> import os
    >>> import tempfile
    >>> fd, path = tempfile.mkstemp('.credentials')
    >>> os.close(fd)

Once Salgado's credentials are obtained for the first time, just set the
appropriate instance variables and use the save() method.

    >>> credentials.consumer = consumer
    >>> credentials.access_token = access_token
    >>> credentials_file = open(path, 'w')
    >>> credentials.save(credentials_file)
    >>> credentials_file.close()

And the credentials are perfectly valid for accessing Launchpad.

    >>> launchpad = Launchpad(credentials=credentials)
    >>> sorted(launchpad.people)
    [...]
    >>> sorted(launchpad.bugs)
    [...]

The credentials can also be retrieved from the file, so that the OAuth request
dance can be avoided.

    >>> credentials = Credentials()
    >>> credentials_file = open(path)
    >>> credentials.load(credentials_file)
    >>> credentials_file.close()
    >>> credentials.consumer.key
    'launchpad-library'
    >>> credentials.consumer.secret
    ''
    >>> credentials.access_token.key
    'salgado-change-anything'
    >>> credentials.access_token.secret
    'test'

These credentials too, are perfectly usable to access Launchpad.

    >>> launchpad = Launchpad(credentials=credentials)
    >>> sorted(launchpad.people)
    [...]
    >>> sorted(launchpad.bugs)
    [...]

The security of the stored credentials is left up to the file-like object.
Here, the application decides to use a dubious encryption algorithm to hide
Salgado's credentials.

    >>> from StringIO import StringIO
    >>> from codecs import EncodedFile
    >>> encrypted_file = StringIO()
    >>> stream = EncodedFile(encrypted_file, 'rot_13', 'ascii')
    >>> credentials.save(stream)
    >>> print encrypted_file.getvalue()
    [1]
    pbafhzre_frperg =
    npprff_gbxra = fnytnqb-punatr-nalguvat
    pbafhzre_xrl = ynhapucnq-yvoenel
    npprff_frperg = grfg
    <BLANKLINE>
    <BLANKLINE>

    >>> stream.seek(0)
    >>> credentials = Credentials()
    >>> credentials.load(stream)
    >>> credentials.consumer.key
    'launchpad-library'
    >>> credentials.consumer.secret
    ''
    >>> credentials.access_token.key
    'salgado-change-anything'
    >>> credentials.access_token.secret
    'test'


Anonymous access
================

An anonymous access token doesn't authenticate any particular
user. Using it will give a client read-only access to the public parts
of the Launchpad dataset.

    >>> from launchpadlib.credentials import AnonymousAccessToken
    >>> anonymous_token = AnonymousAccessToken()

    >>> from launchpadlib.credentials import Credentials
    >>> credentials = Credentials(
    ...     consumer_name="a consumer", access_token=anonymous_token)
    >>> launchpad = Launchpad(credentials=credentials)

    >>> salgado = launchpad.people['salgado']
    >>> print salgado.display_name
    Guilherme Salgado

An anonymous client can't modify the dataset, or read any data that's
permission-controlled or scoped to a particular user.

    >>> launchpad.me
    Traceback (most recent call last):
    ...
    HTTPError: HTTP Error 401: Unauthorized
    ...

    >>> salgado.display_name = "This won't work."
    >>> salgado.lp_save()
    Traceback (most recent call last):
    ...
    HTTPError: HTTP Error 401: Unauthorized
    ...

Convenience
===========

When you want anonymous access, a convenience method is available for
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')
    >>> sorted(launchpad.people)
    [...]

    >>> launchpad.me
    Traceback (most recent call last):
    ...
    HTTPError: 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.

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.

    >>> import launchpadlib.credentials
    >>> credentials = Credentials('consumer')

    >>> authorization_url = credentials.get_request_token(
    ...     context='firefox', web_root='test_dev')
    >>> authorization_url
    'http://launchpad.dev:8085/+authorize-token?oauth_token=...&lp.context=firefox'

Information about the request token is kept in the _request_token
attribute of the Credentials object.

    >>> credentials._request_token.key is not None
    True
    >>> credentials._request_token.secret is not None
    True
    >>> 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(
    ...     "foo.bar@canonical.com", "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 = 'salgado@ubuntu.com'
    ...         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)

The dictionary request token
============================

By default, get_request_token returns the URL that the user needs to
use when granting access to the token. But you can specify a different
token_format and get a dictionary instead.

    >>> credentials = Credentials('consumer')
    >>> dictionary = credentials.get_request_token(
    ...     context='firefox', web_root='test_dev',
    ...     token_format=Credentials.DICT_TOKEN_FORMAT)

The dictionary has useful information about the token and about the
levels of authentication Launchpad offers.

    >>> sorted(dictionary.keys())
    ['access_levels', 'lp.context', 'oauth_token',
     'oauth_token_consumer', 'oauth_token_secret']

The _request_token attribute of the Credentials object has the same
fields set as if you had asked for the default URI token format.

    >>> credentials._request_token.key is not None
    True
    >>> credentials._request_token.secret is not None
    True
    >>> print credentials._request_token.context
    firefox


Credentials file errors
=======================

If the credentials file is empty, loading it raises an exception.

    >>> credentials = Credentials()
    >>> credentials.load(StringIO())
    Traceback (most recent call last):
    ...
    CredentialsFileError: No configuration for version 1

It is an error to save a credentials file when no consumer or access token is
available.

    >>> credentials.consumer = None
    >>> credentials.save(StringIO())
    Traceback (most recent call last):
    ...
    CredentialsFileError: No consumer

    >>> credentials.consumer = consumer
    >>> credentials.access_token = None
    >>> credentials.save(StringIO())
    Traceback (most recent call last):
    ...
    CredentialsFileError: No access token

The credentials file is not intended to be edited, but because it's human
readable, that's of course possible.  If the credentials file gets corrupted,
an error is raised.

    >>> credentials_file = StringIO("""\
    ... [1]
    ... #consumer_key: aardvark
    ... consumer_secret: badger
    ... access_token: caribou
    ... access_secret: dingo
    ... """)
    >>> credentials.load(credentials_file)
    Traceback (most recent call last):
    ...
    NoOptionError: No option 'consumer_key' in section: '1'

    >>> credentials_file = StringIO("""\
    ... [1]
    ... consumer_key: aardvark
    ... #consumer_secret: badger
    ... access_token: caribou
    ... access_secret: dingo
    ... """)
    >>> credentials.load(credentials_file)
    Traceback (most recent call last):
    ...
    NoOptionError: No option 'consumer_secret' in section: '1'

    >>> credentials_file = StringIO("""\
    ... [1]
    ... consumer_key: aardvark
    ... consumer_secret: badger
    ... #access_token: caribou
    ... access_secret: dingo
    ... """)
    >>> credentials.load(credentials_file)
    Traceback (most recent call last):
    ...
    NoOptionError: No option 'access_token' in section: '1'

    >>> credentials_file = StringIO("""\
    ... [1]
    ... consumer_key: aardvark
    ... consumer_secret: badger
    ... access_token: caribou
    ... #access_secret: dingo
    ... """)
    >>> credentials.load(credentials_file)
    Traceback (most recent call last):
    ...
    NoOptionError: No option 'access_secret' in section: '1'


Bad credentials
===============

The application is not allowed to access Launchpad with a bad access token.

    >>> access_token = AccessToken('bad', 'no-secret')
    >>> credentials = Credentials(
    ...     consumer_name=consumer.key, consumer_secret=consumer.secret,
    ...     access_token=access_token)
    >>> launchpad = Launchpad(credentials=credentials)
    Traceback (most recent call last):
    ...
    HTTPError: HTTP Error 401: Unauthorized
    ...

The application is not allowed to access Launchpad with a consumer
name that doesn't match the credentials.

    >>> access_token = AccessToken('salgado-change-anything', 'test')
    >>> credentials = Credentials(
    ...     consumer_name='not-the-launchpad-library',
    ...     access_token=access_token)
    >>> launchpad = Launchpad(credentials=credentials)
    Traceback (most recent call last):
    ...
    HTTPError: HTTP Error 401: Unauthorized
    ...

The application is not allowed to access Launchpad with a bad access secret.

    >>> access_token = AccessToken('hgm2VK35vXD6rLg5pxWw', 'bad-secret')
    >>> credentials = Credentials(
    ...     consumer_name=consumer.key, consumer_secret=consumer.secret,
    ...     access_token=access_token)
    >>> launchpad = Launchpad(credentials=credentials)
    Traceback (most recent call last):
    ...
    HTTPError: HTTP Error 401: Unauthorized
    ...

Clean up
========

    >>> os.remove(path)