Diff for "API/launchpadlib"

Not logged in - Log In / Register

Differences between revisions 3 and 5 (spanning 2 versions)
Revision 3 as of 2008-07-31 16:31:46
Size: 9642
Editor: cpe-24-193-113-134
Revision 5 as of 2008-07-31 18:04:41
Size: 10058
Editor: cpe-24-193-113-134
Deletions are marked like this. Additions are marked like this.
Line 51: Line 51:
Line 53: Line 54:
Line 63: Line 65:
 (https://launchpad.net/+authorize-token?oauth_token=foobar)  (https://launchpad.net/+authorize-token?oauth_token=xxxxxxxxx)
Line 117: Line 119:
Line 118: Line 121:
Line 122: Line 126:
Line 124: Line 129:
Line 127: Line 133:
Line 135: Line 142:
Line 150: Line 158:
Line 155: Line 164:
Line 158: Line 168:
Line 165: Line 176:
Line 171: Line 183:
Line 176: Line 189:
Line 181: Line 195:
Line 188: Line 203:
Line 192: Line 208:
    me = launchpad.people['me']
    me.display_name = 'A new Launchpad web service user.'
me = launchpad.people['my-user-name']
    me.display_name = 'A user who edits through the Launchpad web service.'
Line 195: Line 212:
Line 203: Line 221:
documentation for details.
documentation for details. A bugtask entry supports an operation called "transitionToAssignee".
This operation takes a single argument called "assignee", which should be a Launchpad person.
Here it is in action.

Line 208: Line 229:
    # A new Launchpad web service user.     # A user who edits through the Launchpad web service.
Line 217: Line 239:
Line 218: Line 241:
        ...         print person.name
Line 227: Line 251:
Line 236: Line 261:
Line 240: Line 266:
Line 244: Line 271:
Line 253: Line 281:
Line 255: Line 284:
Line 261: Line 291:
Line 267: Line 298:
Line 277: Line 308:
We track these in the launchpadlib bug tracker
(https://bugs.edge.launchpad.net/launchpadlib) and will be working on
them during the limited beta.
We track these in the launchpadlib bug tracker (https://bugs.edge.launchpad.net/launchpadlib) and will be working to improve launchpadlib throughout the limited beta.


launchpadlib is an open-source Python library that lets you treat the HTTP resources published by Launchpad's web service as Python objects responding to a standard set of commands. With launchpadlib you can integrate your applications into Launchpad without knowing a lot about HTTP client programming.

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 (external link forthcoming).

Launchpad's web service currently exposes the following major parts of Launchpad:

  • People and teams
  • Team memberships
  • Bugs and bugtasks

One part of Launchpad is exposed through the web service, but not supported by the current version of launchpadlib:

  • Uploaded files, such as bug attachments

As new features and capabilities are added to the web service, you'll be able to access most of them without having to update your copy of launchpadlib. You _will_ have to upgrade launchpadlib to get new client-side features (like support for uploaded files). The Launchpad team will put out an announcement whenever a server-side change means you should upgrade launchpadlib.


The launchpadlib library depends on wadllib, another open-source library released by the Launchpad team. Get a copy of the wadllib source with bzr and install it.

  $ bzr branch lp:wadllib
  $ cd wadllib
  $ sudo ./setup.py install

Then do the same for launchpadlib.

  $ bzr branch lp:launchpadlib
  $ cd launchpadlib
  $ sudo ./setup.py install

Getting started

The first step towards using Launchpad's web service is setting up credentials for your client. Run this code in a Python session:

    from launchpadlib.launchpad import Launchpad
    launchpad = Launchpad.get_token_and_login('just testing')

(You can substitute whatever string you like for 'just testing'. This string should describe what you'll be doing with the credentials. Traditionally it's the name of a program you're writing, but here we're just testing.)

You'll see a message like this:

 The authorization page
 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.

Your web browser will open to a page at launchpad.net. You'll be asked to login to Launchpad, and grant some level of access to your new credentials. The level of access you choose will determine how much you can do through launchpadlib with these credentials. This lets your users delegate a portion of their Launchpad permissions to your program, without having to trust it completely.

Once you grant access, hit Enter within your Python session. You'll get back a Launchpad object. Now you can access the web service.

Here's some code that retrieves a bug from Launchpad and prints its title.

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

Before proceeding further, save your credentials so that you don't have to do the get_token_and_login dance again the next time you need to access the web service.

    launchpad.credentials.save(open("some-file.txt", "w"))

Let's create a new Launchpad object from saved credentials right now.

    from launchpadlib import Credentials
    credentials = Credentials()
    launchpad = Launchpad(credentials)

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

The top-level objects

The Launchpad object has attributes corresponding to the major parts of Launchpad. Currently there are two of these attributes, launchpad.bugs and launchpad.people. You've already seen launchpad.bugs. This code uses launchpad.people to look up the person with the Launchpad name "salgado".

    salgado = launchpad.people['salgado']

You can search for objects in other ways. Here's another way of finding "salgado".

    salgado = launchpad.people.getByEmail(

Some searches return more than one object.

    for person in launchpad.people.find(text="salgado"):
        print person.name
    # agustin-salgado
    # ariel-salgado
    # axel-salgado
    # bruno-salgado
    # camilosalgado
    # ...


Bugs, people, team memberships, and most other objects published through Launchpad's web service, all work pretty much the same way. We call all these objects "entries". Each corresponds to a single piece of data within Launchpad.

You can use the web service to discover various facts about an entry. The launchpadlib makes the facts available as attributes of the entry object.

'name' and 'display_name' are facts about people.

    print salgado.name
    # salgado

    print salgado.display_name
    # Guilherme Salgado

'private' and 'description' are facts about bugs.

    print bug_one.private
    # False

    print bug_one.description
    # Microsoft has a majority market share in the new desktop PC marketplace.
    # This is a bug, which Ubuntu is designed to fix.
    # ...

Every entry has a 'self_link' attribute. You can treat this as a permanent ID for the entry. If your program needs to keep track of Launchpad objects across multiple runs, a simple way to do it is to keep track of the self_links.

    print salgado.self_link
    # http://api.launchpad.dev/~salgado

    # http://api.launchpad.dev/bugs/1

Some of an object's attributes are links to other entries. Bugs have an attribute 'owner', but the owner of a bug is a person, with attributes of its own.

    owner = bug_one.owner
    print repr(owner)
    # <person at http://api.launchpad.net/beta/~sabdfl>
    print owner.name
    # sabdfl
    print owner.display_name
    # Mark Shuttleworth

If you have permission, you can change an entry's attributes and write the data back to the server.

    me = launchpad.people['my-user-name']
    me.display_name = 'A user who edits through the Launchpad web service.'

Having permission means not only being authorized to perform an operation on the Launchpad side, but using a launchpadlib Credentials object that authorizes the operation. If you've set up your launchpadlib Credentials for read-only access, you won't be able to change the dataset through launchpadlib.

Some entries also support special operations--see the reference documentation for details. A bugtask entry supports an operation called "transitionToAssignee". This operation takes a single argument called "assignee", which should be a Launchpad person. Here it is in action.

    task = list(bug_one.bug_tasks)[0]
    print task.owner.display_name
    # A user who edits through the Launchpad web service.


When Launchpad groups similar entries together, we call it a collection. You've already seen one collection: the list of people you get back when you call launchpad.people.find.

    for person in launchpad.people.find(text="salgado"):
        print person.name

That's a collection of 'people'-type entries. You can iterate over a collection as you can any Python list.

Some of an entry's attributes are links to related collections. Bug #1 has a number of associated bug tasks, represented as a collection of 'bug task' entries.

    tasks = bug_one.bug_tasks
    print len(tasks)
    # 15
    for task in tasks:
        print task.bug_target_display_name
    # Computer Science Ubuntu
    # Ichthux
    # ...

The person 'salgado' understands two languages, represented here as a collection of two 'language' entries.

    for language in salgado.languages:
        print language.self_link
    # http://api.launchpad.net/beta/+languages/en
    # http://api.launchpad.net/beta/+languages/pt_BR

Because collections can be very large, it's often useful to have a break condition in your iterators. Bugs generally have a manageable number of bug tasks, and people understand a manageable number of languages, but launchpad tracks a huge number of people and bugs. If you iterate over a list without providing a break condition, launchpadlib will just keep pulling down entries until it runs out. In theory you could run this code:

    for bug in launchpad.bugs:
        print bug.description

But with no break condition, it would run a very long time, given that Launchpad tracks over 250,000 bugs. Realistically, the code would run until your client was banned for making too many requests. It's better to do something like this:

    index = 0
    for bug in launchpad.bugs:
        if index >= 10:
        index += 1
        print bug.description

Planned improvements

Right now launchpadlib has some obvious deficiencies. One you may have just noticed is that collections don't support the slice operator; that's why you need to use iterators with break conditions. Another is that there are no introspection facilities: you can't do dir() on an object to see what attributes and links it has.

We track these in the launchpadlib bug tracker (https://bugs.edge.launchpad.net/launchpadlib) and will be working to improve launchpadlib throughout the limited beta.

API/launchpadlib (last edited 2021-10-07 16:05:43 by cjwatson)