Get started with launchpadlib

This document shows how to use a Python client to read and write Launchpad’s data using the launchpadlib library. It doesn’t cover the HTTP requests and responses that go back and forth behind the scenes: for that, see the “hacking” document. This document also doesn’t cover the full range of what’s possible with Launchpad’s web service: for that, see the web service reference documentation. Check out the API examples page if you would like to see more sample code.

Installation

If you have the latest version of Ubuntu, you can install launchpadlib from the Ubuntu repositories using apt-get:

sudo apt-get install python3-launchpadlib

If you have an older version of Ubuntu, some parts of the instructions below may not work with the version from the repositories. However, you should be able to install the latest version of launchpadlib manually.

On any platform with Python and pip, you can install launchpadlib using the pip command:

pip install launchpadlib

Getting started

The first step towards using Launchpad’s web service is to choose a cache directory. The documents you retrieve from Launchpad will be stored here, which will save you a lot of time. Run this code in a Python session, substituting an appropriate directory on your computer:

cachedir = "/home/me/.launchpadlib/cache/"

The next step is to set up credentials for your client. For quick read-only access to Launchpad data, you can get anonymous access. Otherwise, you’ll need to authenticate with Launchpad using OAuth.

Anonymous access

Note

login_anonymously() is only available with launchpadlib version 1.5.4 or higher

The Launchpad.login_anonymously() method gives you automatic read-only access to public Launchpad data.

from launchpadlib.launchpad import Launchpad
launchpad = Launchpad.login_anonymously('just testing', 'production', cachedir, version='devel')

  • Launchpad.login_anonymously() is a string that identifies the web service client. We use this string to gauge client popularity and detect buggy or inefficient clients. Here, though, we’re just testing.

  • The second argument tells launchpadlib which Launchpad instance to run against. Here, we’re using production, which is mapped to the web service root on the production Launchpad server: https://api.launchpad.net/. Anonymous access cannot change the Launchpad dataset, so there’s no concern about a bad test program accidentally overwriting data. (If you want to play it safe, you could use ‘staging’ instead - though staging is sometimes down for extended periods.)

  • version specifies the API version to use. For historical reasons the default is '1.0', and you may want to use this in certain circumstances, but in most cases you should use 'devel' so that you get a reasonably complete and current interface.

  • The login_anonymously() method automatically negotiates a read-only credential with Launchpad. You can use your Launchpad object right away.

bug_one = launchpad.bugs[1]
print(bug_one.title)
# Microsoft has a majority market share

You’ll get an error if you try to modify the dataset, access private data, or access objects like launchpad.me which assume a particular user is logged in.

Note that login_anonymously() is only available in launchpadlib starting in version 1.5.4.

Authenticated access

To get read-write access to Launchpad, or to see a user’s private data, you’ll need to get an OAuth credential for that user. If you’re writing an application need to get an OAuth credential for that user. If you’re writing an application that the user will run on their own computer, just call the Launchpad.login_with() method.

This method takes two important arguments: the name of your application, and the name of the Launchpad server you want to run against.

from launchpadlib.launchpad import Launchpad
launchpad = Launchpad.login_with('My Application', 'staging', version='devel')

The default server name is ‘staging’, so that you don’t destroy data by accident while developing. When you do a release, you can change this to ‘production’.

If this code complains that ‘staging’ isn’t a URL, then you’re not running the most up-to-date launchpadlib. You can replace ‘staging’ with ``launchpadlib.launchpad.STAGING_SERVICE_ROOT`` to make it work in Ubuntu 9.10’s launchpadlib. .. note:: If this code complains that ‘staging’ isn’t a URL, it means you’re not running a recent version of launchpadlib. To make it work in Ubuntu 9.10’s launchpadlib, replace ‘staging’ with launchpadlib.launchpad.STAGING_SERVICE_ROOT. If you have an existing desktop-wide Launchpad credential, launchpadlib will find it and use it. If there’s no existing desktop credential (because you’ve never used a launchpadlib application on this computer, or because you had a If you have an existing desktop-wide Launchpad credential, launchpadlib will find it and use it. If there’s no existing desktop credential, launchpadlib will guide you through authorizing a new credential, as seen in Application integration.

For login_with(), you can also pass in a callback function as credential_save_failed. That function will be invoked if a desktop credential can’t be created - either because the end-user refused to perform the authorization, or because there was a problem storing the credential after authorization.

import sys
from launchpadlib.launchpad import Launchpad

def no_credential():
    print("Can't proceed without Launchpad credential.")
sys.exit()

launchpad = Launchpad.login_with(
    'My Application', 'staging', credential_save_failed=no_credential, version='devel')