Diff for "API/launchpadlib"

Not logged in - Log In / Register

Differences between revisions 1 and 4 (spanning 3 versions)
Revision 1 as of 2008-05-08 19:00:57
Size: 145
Editor: barry
Comment:
Revision 4 as of 2008-07-31 16:37:41
Size: 10045
Editor: leonardr
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
This is a stub for information about the Python library for scripting Launchpad through its [:API: web services interface]. 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 [[../Hacking|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.

= Installation =

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
 (https://launchpad.net/+authorize-token?oauth_token=foobar)
 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()
    credentials.load("some-file.txt")
    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(
        email="guilherme.salgado@canonical.com")
}}}

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
    # ...
}}}


== Entries ==

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

    bug_one.self_link
    # 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.'
    me.lp_save()
}}}

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]
    task.transitionToAssignee(assignee=me)
    print task.owner.display_name
    # A user who edits through the Launchpad web service.
}}}


== Collections ==

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
    # JAK LINUX
    # ...
}}}

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:
            break
        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.

launchpadlib

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.

Installation

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
 (https://launchpad.net/+authorize-token?oauth_token=foobar)
 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()
    credentials.load("some-file.txt")
    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(
        email="guilherme.salgado@canonical.com")

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
    # ...

Entries

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

    bug_one.self_link
    # 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.'
    me.lp_save()

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]
    task.transitionToAssignee(assignee=me)
    print task.owner.display_name
    # A user who edits through the Launchpad web service.

Collections

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
    # JAK LINUX
    # ...

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