CINXE.COM

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html;charset=utf-8"> <meta name="robots" content="noindex,nofollow"> <title>Diff for "API/launchpadlib" - Launchpad Help</title> <script type="text/javascript" src="/moin_static198/common/js/common.js"></script> <script type="text/javascript">  </script> <link rel="stylesheet" type="text/css" charset="utf-8" media="all" href="/moin_static198/lp20/css/common.css"> <link rel="stylesheet" type="text/css" charset="utf-8" media="screen" href="/moin_static198/lp20/css/screen.css"> <link rel="stylesheet" type="text/css" charset="utf-8" media="print" href="/moin_static198/lp20/css/print.css"> <link rel="stylesheet" type="text/css" charset="utf-8" media="projection" href="/moin_static198/lp20/css/projection.css">   <link rel="alternate" title="Launchpad Help: API/launchpadlib" href="/API/launchpadlib?diffs=1&show_att=1&action=rss_rc&unique=0&page=API%2Flaunchpadlib&ddiffs=1" type="application/rss+xml"> <script type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-12833497-4']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script> <link rel="Start" href="/FrontPage"> <link rel="Alternate" title="Wiki Markup" href="/API/launchpadlib?action=raw"> <link rel="Alternate" media="print" title="Print View" href="/API/launchpadlib?action=print"> <link rel="Up" href="/API"> <link rel="Search" href="/FindPage"> <link rel="Index" href="/TitleIndex"> <link rel="Glossary" href="/WordIndex"> <link rel="Help" href="/HelpOnFormatting"> </head> <body lang="en" dir="ltr"> <div id="header"> <h1> <a href="https://help.launchpad.net/" class="header-link"> <img src=' /moin_static198/lp20/img/logo.png ' /> launchpad help</a> </h1> <div id="finder"> <div class="fixbox"> <form id="searchform" method="get" action=""> <input type="hidden" name="action" value="fullsearch"> <input type="hidden" name="context" value="180"> <input id="searchinput" type="text" name="value" value="" size="20" onfocus="searchFocus(this)" onblur="searchBlur(this)" onkeyup="searchChange(this)" onchange="searchChange(this)" alt="Search"> </form> </div> <ul class="editbar"><li>Immutable Page</li><li><a class="nbinfo" href="/API/launchpadlib?action=info" rel="nofollow">Info</a></li><li><a class="nbattachments" href="/API/launchpadlib?action=AttachFile" rel="nofollow">Attachments</a></li><li> <form class="actionsmenu" method="GET" action="/API/launchpadlib"> <div> <label>More Actions:</label> <select name="action" onchange="if ((this.selectedIndex != 0) && (this.options[this.selectedIndex].disabled == false)) { this.form.submit(); } this.selectedIndex = 0;"> <option value="raw">Raw Text</option> <option value="print">Print View</option> <option value="RenderAsDocbook">Render as Docbook</option> <option value="show" disabled class="disabled">Delete Cache</option> <option value="show" disabled class="disabled">------------------------</option> <option value="SpellCheck">Check Spelling</option> <option value="LikePages">Like Pages</option> <option value="LocalSiteMap">Local Site Map</option> <option value="show" disabled class="disabled">------------------------</option> <option value="RenamePage" disabled class="disabled">Rename Page</option> <option value="DeletePage" disabled class="disabled">Delete Page</option> <option value="show" disabled class="disabled">------------------------</option> <option value="show" disabled class="disabled">Subscribe User</option> <option value="show" disabled class="disabled">------------------------</option> <option value="show" disabled class="disabled">Remove Spam</option> <option value="show" disabled class="disabled">Revert to this revision</option> <option value="PackagePages">Package Pages</option> <option value="SyncPages">Sync Pages</option> <option value="show" disabled class="disabled">------------------------</option> <option value="Load">Load</option> <option value="Save">Save</option> <option value="SlideShow">SlideShow</option> </select> <input type="submit" value="Do"> </div> <script type="text/javascript">  </script> </form> </li></ul> </div> </div> <div id="locationline"> </div> <div id="sepbar"> </div> <div id="login"> <div class="fl"> <h1 class="maintitle"> Diff for "API/launchpadlib" </h1> </div> <div class="fr"> Not logged in - <a href="/?action=login">Log In / Register</a> </div> </div> <div id="pageline"><hr style="display:none;"></div> <div class="message"> </div> <div id="page" lang="en" dir="ltr"> <div id="content"> Differences between revisions 83 and 84 <table class="diff"> <tr> <td style="border:0;"> <form action="/API/launchpadlib" method="get"> <div style="text-align:left"> <input name="action" value="diff" type="hidden"> <input name="rev1" value="82" type="hidden"> <input name="rev2" value="83" type="hidden"> <input value="Previous change" type="submit"> </div> </form> </td> <td style="border:0"> </td> <td style="border:0;"> <form action="/API/launchpadlib" method="get"> <div style="text-align:right"> <input name="action" value="diff" type="hidden"> <input name="rev1" value="84" type="hidden"> <input name="rev2" value="84" type="hidden"> <input value="Next change" type="submit" disabled="disabled"> </div> </form> </td> </tr> </table> <table class="diff"> <tr><td class="diff-info"> <div class="diff-info diff-info-header"><a class="diff-nav-link diff-first-link diff-old-rev" href="/API/launchpadlib?action=diff&rev1=1&rev2=84" title="Diff with oldest revision in left pane">⇤</a> <a class="diff-nav-link diff-prev-link diff-old-rev" href="/API/launchpadlib?action=diff&rev1=82&rev2=84" title="Diff with older revision in left pane">←</a> Revision 83 as of 2024-06-03 10:19:03 → </div> <div class="diff-info diff-info-rev-size">Size: 25247</div> <div class="diff-info diff-info-rev-author">Editor: <a class="interwiki" href="https://launchpad.net/~ruinedyourlife" title="ruinedyourlife @ 2a01:cb19:85b4:1d00:fdb7:1617:d252:f9fd[2a01:cb19:85b4:1d00:fdb7:1617:d252:f9fd]">ruinedyourlife</a></div> <div class="diff-info diff-info-rev-comment">Comment: move to api/examples</div> </td><td class="diff-info"> <div class="diff-info diff-info-header"> ← Revision 84 as of 2024-07-04 12:12:36 → ⇥</div> <div class="diff-info diff-info-rev-size">Size: 25254</div> <div class="diff-info diff-info-rev-author">Editor: <a class="interwiki" href="https://launchpad.net/~jugmac00" title="jugmac00 @ p200300d30f1d3c0066008dd8781c6932.dip0.t-ipconnect.de[2003:d3:f1d:3c00:6600:8dd8:781c:6932]">jugmac00</a></div> <div class="diff-info diff-info-rev-comment">Comment: fix broken link</div> </td></tr> <tr> <td class="diff-removed">Deletions are marked like this.</td> <td class="diff-added">Additions are marked like this.</td> </tr> <tr class="diff-title"> <td><a href="#line-208">Line 208</a>:</td> <td><a href="#line-208">Line 208</a>:</td> </tr> <tr> <td class="diff-removed">and what data is stored inside it, you'd visit https://launchpad.net/+apidoc#bug.</td> <td class="diff-added">and what data is stored inside it, you'd visit https://api.launchpad.net/devel.html#bug.</td> </tr> </table> <div dir="ltr" id="content-below-diff" lang="en"> <a href="/FrontPage">Launchpad Help</a> > <a href="/API">API</a> > Examples <div><table style="&quot; float:right; font-size: 0.9em; width:40%; background:#F1F1ED; margin: 0 0 1em 1em; &quot;"><tbody><tr> <td style="&quot; padding:0.5em; &quot;"><div class="table-of-contents">Contents<ol><li> <a href="#launchpadlib">launchpadlib</a></li><li> <a href="#Installation">Installation</a><ol><li> <a href="#The_launchpadlib_in_Ubuntu_.28easy_to_install.29">The launchpadlib in Ubuntu (easy to install)</a></li><li> <a href="#launchpad_using_pip">launchpad using pip</a></li></ol></li><li> <a href="#Getting_started">Getting started</a><ol><li> <a href="#Anonymous_access">Anonymous access</a></li><li> <a href="#Authenticated_access">Authenticated access</a></li><li> <a href="#Authenticated_access_for_website_integration">Authenticated access for website integration</a></li></ol></li><li> <a href="#Getting_help">Getting help</a></li><li> <a href="#The_top-level_objects">The top-level objects</a></li><li> <a href="#Entries">Entries</a><ol><li> <a href="#self_link:_the_permanent_ID">self_link: the permanent ID</a></li><li> <a href="#web_link:_the_link_to_the_Launchpad_website">web_link: the link to the Launchpad website</a></li><li> <a href="#Named_operations">Named operations</a></li></ol></li><li> <a href="#Errors">Errors</a></li><li> <a href="#Collections">Collections</a></li><li> <a href="#Hosted_files">Hosted files</a></li><li> <a href="#Persistent_references_to_Launchpad_objects">Persistent references to Launchpad objects</a></li><li> <a href="#Three_things_to_make_your_client_faster">Three things to make your client faster</a></li><li> <a href="#Planned_improvements">Planned improvements</a></li><li> <a href="#See_also">See also</a></li><li> <a href="#launchpadlib_API_compatibility">launchpadlib API compatibility</a><ol><li> <a href="#A.3E.3D_1.5.5_.28.3E.3D_Ubuntu_Lucid_Lynx.29">>= 1.5.5 (>= Ubuntu Lucid Lynx)</a></li><li> <a href="#A1.8.0_.28no_Ubuntu_release.29">1.8.0 (no Ubuntu release)</a></li><li> <a href="#A.3E.3D_1.9.0_.28.3E.3D_Ubuntu_Natty_Narwhal.29">>= 1.9.0 (>= Ubuntu Natty Narwhal)</a></li></ol></li></ol></div></td> </tr> </tbody></table></div> <h1 id="launchpadlib">launchpadlib</h1> <ul><li style="list-style-type:none"><a class="https" href="https://launchpad.net/launchpadlib">https://launchpad.net/launchpadlib</a> </li></ul>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 <a href="/API/Hacking">the "hacking" document</a>. This document also doesn't cover the full range of what's possible with Launchpad's web service: for that, see the <a class="http" href="http://launchpad.net/+apidoc/">web service reference documentation</a>. Check out the <a href="/API/Examples">API examples page</a> if you would like to see more sample code. Launchpad's web service currently exposes the following major parts of Launchpad: <ul><li>People and teams </li><li>Team memberships </li><li>Bugs and bugtasks </li><li>The project registry </li><li>Hosted files, such as bug attachments and mugshots. </li></ul>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. <h1 id="Installation">Installation</h1> <h2 id="The_launchpadlib_in_Ubuntu_.28easy_to_install.29">The launchpadlib in Ubuntu (easy to install)</h2> If you have the latest version of Ubuntu then to install the launchpadlib available in the Ubuntu repositories, open a terminal and run the command: <pre> $ sudo apt-get install python3-launchpadlib</pre>And you are done! If you have an older version of Ubuntu then parts of the instructions below may not work with the version from the repositories but you should be able to install the latest version of launchpadlib manually. <h2 id="launchpad_using_pip">launchpad using pip</h2> On any platform with a working Python and pip, you should be able to say: <pre> pip install launchpadlib</pre> <h1 id="Getting_started">Getting started</h1> 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: <pre> cachedir = "/home/me/.launchpadlib/cache/"</pre>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. <h2 id="Anonymous_access">Anonymous access</h2> The <tt class="backtick">Launchpad.login_anonymously()</tt> method will give you automatic read-only access to public Launchpad data. <pre> from launchpadlib.launchpad import Launchpad launchpad = Launchpad.login_anonymously('just testing', 'production', cachedir, version='devel')</pre>The first argument to <tt class="backtick">Launchpad.login_anonymously()</tt> 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 <tt class="backtick">production</tt>, which is mapped to the web service root on the production Launchpad server: "<a class="https" href="https://api.launchpad.net/">https://api.launchpad.net/</a>". 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.) The <tt class="backtick">version</tt> argument specifies the API version to use. For historical reasons the default is <tt class="backtick">'1.0'</tt>, and you may want to use this in certain special circumstances, but in most cases you should use <tt class="backtick">'devel'</tt> so that you get a reasonably complete and current interface. The <tt class="backtick">login_anonymously()</tt> method automatically negotiates a read-only credential with Launchpad. You can use your <tt class="backtick">Launchpad</tt> object right away. <pre> bug_one = launchpad.bugs[1] print(bug_one.title) # Microsoft has a majority market share</pre>You'll get an error if you try to modify the dataset, access private data, or access objects like <tt class="backtick">launchpad.me</tt> which assume a particular user is logged in. Note that <tt class="backtick">login_anonymously()</tt> is only available in launchpadlib starting in version 1.5.4. <h2 id="Authenticated_access">Authenticated access</h2> 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 that the user will run on their own computer, this is easy: just call the <tt class="backtick">Launchpad.login_with()</tt> method. This method takes two important arguments: the name of your application, and the name of the Launchpad server you want to run against. 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'. <pre> from launchpadlib.launchpad import Launchpad launchpad = Launchpad.login_with('My Application', 'staging', version='devel')</pre>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 <tt class="backtick">launchpadlib.launchpad.STAGING_SERVICE_ROOT</tt> to make it work in Ubuntu 9.10's launchpadlib. 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 credential that expired), launchpadlib will guide you through authorizing a new credential, as seen <a href="/API/ThirdPartyIntegration">here</a>. There's one other important argument to <tt class="backtick">login_with()</tt>. You can pass in a callback function as <tt class="backtick">credential_save_failed</tt>. 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. <pre> 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')</pre> <h2 id="Authenticated_access_for_website_integration">Authenticated access for website integration</h2> Things are a little more difficult if you want to integrate Launchpad's functionality into your own website. You can't call <tt class="backtick">Launchpad.login_with()</tt>, because that will open up a web browser on your webserver--not on your user's computer. Instead, you create a <tt class="backtick">Credentials</tt> object identifying your website and call <tt class="backtick">get_request_token()</tt> to ask Launchpad for a request token. Be sure to pass in the name of the Launchpad server you want to use (probably "production" as <tt class="backtick">web_root</tt>. <pre> from launchpadlib.credentials import Credentials credentials = Credentials("my website") request_token_info = credentials.get_request_token(web_root="production")</pre>You'll get back a string that looks like '<a class="https" href="https://launchpad.net/+authorize-token?oauth_token=">https://launchpad.net/+authorize-token?oauth_token=</a>...' This is the URL your end-user needs to visit in order to authorize your token. At this point, you should redirect your user to that URL. Then, start periodically calling <tt class="backtick">exchange_request_token_for_access_token()</tt>: <pre> from lazr.restfulclient.errors import HTTPError complete = False while not complete: try: credentials.exchange_request_token_for_access_token( web_root="production") complete = True except HTTPError: # The user hasn't authorized the token yet.</pre>Once <tt class="backtick">exchange_request_token_for_access_token()</tt> successfully executes, an authorized access token will be present in <tt class="backtick">credentials.access_token</tt>. You can then pass the <tt class="backtick">Credentials</tt> object into the <tt class="backtick">Launchpad</tt> constructor. <pre> from launchpadlib.launchpad import Launchpad launchpad = Launchpad(credentials, service_root="production")</pre>While this system is not ideal, we don't know of any third-party websites that are integrating Launchpad functionality in a way that requires OAuth tokens. <h1 id="Getting_help">Getting help</h1> If you don't know the capabilities of one of the objects you've got, you can call dir() on it. You'll see all of its fields and all the custom methods it supports. Unfortunately, you'll also see a bunch of launchpadlib-specific junk that you don't care about. That's why we've made available these four lists: <ul><li><tt class="backtick">lp_attributes</tt>: Data fields of this object. You can read from these might be able to write to some of them. </li><li><tt class="backtick">lp_collections</tt>: List of launchpad objects associated with this object. </li><li><tt class="backtick">lp_entries</tt>: Other Launchpad objects associated with this one. </li><li><tt class="backtick">lp_operations</tt>: The names of Launchpad methods you can call on the object. </li></ul><pre> print(sorted(bug_one.lp_attributes)) # ['date_created', 'date_last_message', 'date_last_updated', ... 'tags', 'title'] print(sorted(bug_one.lp_operations)) # ['addAttachment', 'addWatch', 'subscribe', 'unsubscribe']</pre>If you need more detailed help, you can look the object up in <a class="http" href="http://launchpad.net/+apidoc">the reference documentation</a>. First, find out the type of the object. <pre> print(repr(bug_one)) # <bug at https://api.staging.launchpad.net/beta/bugs/1></pre>This is a 'bug' type object. Now you use the type of the object as an anchor into the reference documentation. To find out the capabilities of this object and what data is stored inside it, you'd visit <a class="https" href="https://api.launchpad.net/devel.html#bug">https://api.launchpad.net/devel.html#bug</a>. As you'll see, the reference documentation still needs some work, and it's geared more towards web service hackers than launchpadlib users, but it will tell you about all of this object's attributes and all the supported operations. <ul><li>The "Default representation" section tells you about the available attributes. </li><li class="gap">The "Custom POST methods" and "Custom GET methods" sections tell you about methods the object supports other than the default methods described below. The methods take whatever parameters are listed in "Request query parameters". (You can ignore the "ws.op" parameter because you're using launchpadlib; that's just the name of the method.) </li></ul> <h1 id="The_top-level_objects">The top-level objects</h1> The Launchpad object has attributes corresponding to the major parts of Launchpad. These are: <ul><li><tt class="backtick">.bugs</tt>: All the bugs in Launchpad </li><li><tt class="backtick">.people</tt>: All the people in Launchpad </li><li><tt class="backtick">.me</tt>: You </li><li><tt class="backtick">.distributions</tt>: All the distributions in Launchpad </li><li><tt class="backtick">.projects</tt>: All the projects in Launchpad </li><li><tt class="backtick">.project_groups</tt>: All the project groups in Launchpad </li></ul>As a super special secret, <tt class="backtick">distributions</tt>, <tt class="backtick">projects</tt> and <tt class="backtick">project_groups</tt> are all actually the same thing. <pre> me = launchpad.me print(me.name) # This should be your user name, e.g. 'salgado'</pre>The <tt class="backtick">launchpad.people</tt> attribute gives you access to other people who use Launchpad. This code uses launchpad.people to look up the person with the Launchpad name "salgado". <pre> people = launchpad.people salgado = people['salgado'] print(salgado.display_name) # Guilherme Salgado</pre>You can search for objects in other ways. Here's another way of finding "salgado". <pre> salgado = people.getByEmail(email="guilherme.salgado@canonical.com") print(salgado.display_name) # Guilherme Salgado</pre>Some searches return more than one object. <pre> for person in people.find(text="salgado"): print(person.name) # agustin-salgado # ariel-salgado # axel-salgado # bruno-salgado # camilosalgado # ...</pre>Note that, unlike typical Python methods, these methods--<tt class="backtick">find()</tt> and <tt class="backtick">getByEmail()</tt>--don't support positional arguments, only keyword arguments. You can't call <tt class="backtick">people.find("salgado")</tt>; it has to be <tt class="backtick">people.find(text="salgado")</tt>. <h1 id="Entries">Entries</h1> Bugs, people, projects, 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. <tt class="backtick">name</tt> and <tt class="backtick">display_name</tt> are facts about people. <pre> print(salgado.name) # salgado print(salgado.display_name) # Guilherme Salgado</pre><tt class="backtick">private</tt> and <tt class="backtick">description</tt> are facts about bugs. <pre> 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. # ...</pre>Some of an object's attributes are links to other entries. Bugs have an attribute <tt class="backtick">owner</tt>, but the owner of a bug is a person, with attributes of its own. <pre> owner = bug_one.owner print(repr(owner)) # <person at https://api.staging.launchpad.net/beta/~sabdfl> print(owner.name) # sabdfl print(owner.display_name) # Mark Shuttleworth</pre>If you have permission, you can change an entry's attributes and write the data back to the server using <tt class="backtick">lp_save()</tt>. <pre> me = people['my-user-name'] me.display_name = 'A user who edits through the Launchpad web service.' me.lp_save() print(people['my-user-name'].display_name) # A user who edits through the Launchpad web service.</pre>Having permission means not only being authorized to perform an operation on the Launchpad side, but using a launchpadlib <tt class="backtick">Credentials</tt> object that authorizes the operation. If you've set up your launchpadlib Credentials for read-only access, you won't be able to change data through launchpadlib. <h2 id="self_link:_the_permanent_ID">self_link: the permanent ID</h2> Every entry has a <tt class="backtick">self_link</tt> 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 <tt class="backtick">self_link</tt>s. <pre> print(salgado.self_link) # https://api.staging.launchpad.net/beta/~salgado bug_one.self_link # https://api.staging.launchpad.net/beta/bugs/1</pre> <h2 id="web_link:_the_link_to_the_Launchpad_website">web_link: the link to the Launchpad website</h2> Most of the entries published by the web service correspond to pages on the Launchpad website. You can get the website URL of an entry with the <tt class="backtick">web_link</tt> attribute: <pre> print(salgado.web_link) # https://staging.launchpad.net/~salgado bug_one.web_link # https://bugs.staging.launchpad.net/bugs/1</pre>Some entries don't correspond to any page on the Launchpad website: these entries won't have a <tt class="backtick">web_link</tt>. <h2 id="Named_operations">Named operations</h2> Entries can support special operations just like collections, but again note that, these methods don't support positional arguments, only keyword arguments. <h1 id="Errors">Errors</h1> When the Launchpad web service encounters an error, it sends back an error message to launchpadlib, which raises an HTTPError exception. You'll see information about the HTTP request that caused the error, and the server-side error message. Depending on the error, you may be able to recover or change your code and try again. If you're using an old version of launchpadlib, the HTTPError may not be this helpful. To see the server-side error message, you'll need to print out the .content of the HTTPError exception. <div class="highlight python"><div class="codearea" dir="ltr" lang="en"> <script type="text/javascript"> function isnumbered(obj) { return obj.childNodes.length && obj.firstChild.childNodes.length && obj.firstChild.firstChild.className == 'LineNumber'; } function nformat(num,chrs,add) { var nlen = Math.max(0,chrs-(''+num).length), res = ''; while (nlen>0) { res += ' '; nlen-- } return res+num+add; } function addnumber(did, nstart, nstep) { var c = document.getElementById(did), l = c.firstChild, n = 1; if (!isnumbered(c)) { if (typeof nstart == 'undefined') nstart = 1; if (typeof nstep == 'undefined') nstep = 1; var n = nstart; while (l != null) { if (l.tagName == 'SPAN') { var s = document.createElement('SPAN'); var a = document.createElement('A'); s.className = 'LineNumber'; a.appendChild(document.createTextNode(nformat(n,4,''))); a.href = '#' + did + '_' + n; s.appendChild(a); s.appendChild(document.createTextNode(' ')); n += nstep; if (l.childNodes.length) { l.insertBefore(s, l.firstChild); } else { l.appendChild(s); } } l = l.nextSibling; } } return false; } function remnumber(did) { var c = document.getElementById(did), l = c.firstChild; if (isnumbered(c)) { while (l != null) { if (l.tagName == 'SPAN' && l.firstChild.className == 'LineNumber') l.removeChild(l.firstChild); l = l.nextSibling; } } return false; } function togglenumber(did, nstart, nstep) { var c = document.getElementById(did); if (isnumbered(c)) { remnumber(did); } else { addnumber(did,nstart,nstep); } return false; } </script> <script type="text/javascript"> document.write('<a href="#" onclick="return togglenumber(\'CA-fb78a48ac0526ee8649dc78bfa231d31edb45c55\', 1, 1);" \ class="codenumbers">Toggle line numbers<\/a>'); </script> <pre dir="ltr" id="CA-fb78a48ac0526ee8649dc78bfa231d31edb45c55" lang="en"><a href="#CA-fb78a48ac0526ee8649dc78bfa231d31edb45c55_1"> 1</a> try: <a href="#CA-fb78a48ac0526ee8649dc78bfa231d31edb45c55_2"> 2</a> failing_thing() <a href="#CA-fb78a48ac0526ee8649dc78bfa231d31edb45c55_3"> 3</a> except HTTPError as http_error: <a href="#CA-fb78a48ac0526ee8649dc78bfa231d31edb45c55_4"> 4</a> print(http_error.content) </pre></div></div> <h1 id="Collections">Collections</h1> 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. <pre> for person in launchpad.people.find(text="salgado"): print(person.name)</pre>That's a collection of <tt class="backtick">people</tt>-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. <pre> tasks = bug_one.bug_tasks print(len(tasks)) # 17 for task in tasks: print(task.bug_target_display_name) # Computer Science Ubuntu # Ichthux # JAK LINUX # ...</pre>The person 'salgado' understands two languages, represented here as a collection of two <tt class="backtick">language</tt> entries. <pre> for language in salgado.languages: print(language.self_link) # https://api.staging.launchpad.net/beta/+languages/en # https://api.staging.launchpad.net/beta/+languages/pt_BR</pre>Because collections can be very large, it's usually a bad idea to iterate over them. Bugs generally have a manageable number of bug tasks, and people understand a manageable number of languages, but Launchpad tracks over 250,000 bugs. If you just iterate over a list, launchpadlib will just keep pulling down entries until it runs out, which might be forever (or, realistically, until your client is banned for making too many requests). That's why we recommend you slice Launchpad's collections into Python lists, and operate on the lists. Here's code that prints descriptions for the 10 most recently filed bugs. <pre> bugs = launchpad.bugs[:10] for bug in bugs: print(bug.description)</pre>For performance reasons, we've put a couple restrictions on collection slices that don't apply to slices on regular Python lists. You can only slice from the beginning of a collection, not the end. <pre> launchpad.bugs[-5:] # *** ValueError: Collection slices must have a nonnegative start point.</pre>And your slice needs to have a definite end point: you can't slice to the end of a collection. <pre> bugs[10:] # *** ValueError: Collection slices must have a definite, nonnegative end point. bugs[:-5] # *** ValueError: Collection slices must have a definite, nonnegative end point.</pre>On the plus side, you can include a step number with your slice, as with a normal Python list: <pre> every_other_bug = launchpad.bugs[0:10:2] len(every_other_bug) # 5</pre> <h1 id="Hosted_files">Hosted files</h1> Launchpad stores some data in the form of binary files. A good example is people's mugshots. With launchpadlib, you can read and write these binary files programatically. If you have a launchpadlib reference to one of these hosted files, you can read its data by calling the <tt class="backtick">open()</tt> method and treating the result as an open filehandle. <pre> mugshot = launchpad.me.mugshot mugshot_handle = mugshot.open() mugshot_handle.read() # [binary data] mugshot_handle.content_type # 'image/jpeg' mugshot_handle.last_modified # 'Wed, 12 Mar 2008 21:47:05 GMT'</pre>You'll get an error if the file doesn't exist: for instance, if a person doesn't have a mugshot. <pre> launchpad.people['has-no-mugshot'].mugshot # *** HTTPError: HTTP Error 404: Not Found</pre>To create or overwrite a file, open the hosted file object for write. You'll need to provide the access mode ("w"), the MIME type of the file you're sending to Launchpad, and the filename you want to give it on the server side. <pre> with mugshot.open("w", "image/jpeg", "my-image.jpg") as mugshot_handle: mugshot_handle.write("image data goes here")</pre>If there's something wrong--maybe you provide a file of the wrong type--you'll get an <tt class="backtick">HTTPError</tt> with a status code of 400. The <tt class="backtick">content</tt> attribute will contain an error message. <pre> print(http_error.content) # This image is not exactly 192x192 pixels in size. print(http_error.content) # The file uploaded was not recognized as an image; please # check it and retry.</pre> <h1 id="Persistent_references_to_Launchpad_objects">Persistent references to Launchpad objects</h1> Every entry and collection has a unique ID: its URL. You can get this unique ID by calling <tt class="backtick">str()</tt> on the object. <pre> print(str(bug_one)) # https://api.staging.launchpad.net/beta/bugs/1</pre>If you need to keep track of Launchpad objects over time, or pass references to Launchpad objects to other programs, use these strings. If you've got one of these strings, you can turn it into the corresponding Launchpad object by calling <tt class="backtick">launchpad.load()</tt>. <pre> bug_one = launchpad.load("https://api.staging.launchpad.net/beta/bugs/1") print(bug_one.title) Microsoft has a majority market share</pre>You're bookmarking the Launchpad objects and coming back to them later, just like you'd bookmark pages in your web browser. <h1 id="Three_things_to_make_your_client_faster">Three things to make your client faster</h1> 1. Use the latest launchpadlib. (The versions in the current Ubuntu release should be fine; otherwise run from the branch or the latest tarball.) 2. Profile: <pre> import httplib2 httplib2.debuglevel = 1</pre>3. Fetch objects only once: Don't do this: <pre> if bug.person is not None: print(bug.person.name)</pre>instead <pre> p = bug.person if p is not None: print(p.name)</pre>(From <a class="http" href="http://blog.launchpad.net/api/three-tips-for-faster-launchpadlib-api-clients">the blog</a>). <h1 id="Planned_improvements">Planned improvements</h1> launchpadlib still has deficiencies. We track bugs in the launchpadlib bug tracker (<a class="https" href="https://bugs.launchpad.net/launchpadlib">https://bugs.launchpad.net/launchpadlib</a>) and will be working to improve launchpadlib throughout the limited beta. <h1 id="See_also">See also</h1> <ul><li><a class="http" href="http://launchpad.net/+apidoc/">web service reference documentation</a> for a list of all objects, operations, etc </li></ul> <h1 id="launchpadlib_API_compatibility">launchpadlib API compatibility</h1> The API compatibility of the launchpadlib Python library has not always been maintained as well as an author of a program using it would hope. <h2 id="A.3E.3D_1.5.5_.28.3E.3D_Ubuntu_Lucid_Lynx.29">>= 1.5.5 (>= Ubuntu Lucid Lynx)</h2> Version 1.5.5 added the support for accessing various different versions of the remote web-service API (at the time of writing, these versions are known as "beta", "1.0" and "devel"). Whilst the new <tt class="backtick">version</tt> parameters were compatibly added, there was an incompatible change to the URLs that launchpadlib would accept as <tt class="backtick">service_root</tt> parameters: <ul><li>launchpadlib 1.5.4 and earlier requires URLs of the form <tt class="backtick">https://api.launchpad.net/beta/</tt> </li><li>launchpadlib 1.5.5 and later requires URLs of the form <tt class="backtick">https://api.launchpad.net/</tt> </li></ul>and either will break in non-obvious ways if you give it the wrong form. <h2 id="A1.8.0_.28no_Ubuntu_release.29">1.8.0 (no Ubuntu release)</h2> Version 1.8.0 changed things, which 1.9.0 then changed again. And, it never went into any final Ubuntu release. Probably best to just pretend it doesn't exist. <h2 id="A.3E.3D_1.9.0_.28.3E.3D_Ubuntu_Natty_Narwhal.29">>= 1.9.0 (>= Ubuntu Natty Narwhal)</h2> Version 1.9.x's changes versus 1.6.x include a major refactor of how authentication tokens are obtained. Notable consequences: <ul><li>Different kinds of tokens are obtained, and they are stored differently by default (in GNOME keyring or similar technologies instead of files), meaning it's highly unlikely that tokens stored by launchpadlib 1.6.x will be noticed by 1.9.x, so users will have to re-authorize. </li><li>Most of the methods by which a <tt class="backtick">Launchpad</tt> object is obtained have changed significantly: (Note, positional parameter indices referred to below are 1-based) </li></ul>Launchpad.init: <ul><li>Parameters <tt class="backtick">authorization_engine</tt> and <tt class="backtick">credential_store</tt> inserted at position 2. It is no longer safe to call <tt class="backtick">Launchpad.__init__</tt> with positional parameters beyond the first in compatible applications! </li></ul>Launchpad.login: <ul><li>Method is now deprecated. </li><li>Five new parameters inserted at position 8. Mitigating factor: the only parameter after this was <tt class="backtick">version</tt>, which was probably being passed as a keyword argument anyway. </li></ul>Launchpad.get_token_and_login: <ul><li>Method is now deprecated. </li><li>Parameter 6 renamed from <tt class="backtick">authorizer_class</tt> to <tt class="backtick">authorization_engine</tt>. </li><li>Parameters <tt class="backtick">credential_store</tt> and <tt class="backtick">credential_save_failed</tt> inserted at position 9. Mitigating factor: the only parameter after this was <tt class="backtick">version</tt>, which was probably being passed as a keyword argument anyway. </li></ul>Launchpad.login_with: <ul><li>Positional parameter 1 changed from <tt class="backtick">consumer_name</tt> to <tt class="backtick">application_name</tt> to attempt to force common use-cases to acquire a desktop integration rather than consumer-specific token without code changes. </li><li>Parameter 6 renamed from <tt class="backtick">authorizer_class</tt> to <tt class="backtick">authorization_engine</tt>. </li><li>New parameter <tt class="backtick">consumer_name</tt> appended to replace the incarnation removed at position 1. (But it does not actually work - see <a class="https" href="https://launchpad.net/bugs/755313">https://launchpad.net/bugs/755313</a>) </li><li>New parameters <tt class="backtick">credential_save_failed</tt> and <tt class="backtick">credential_store</tt> appended. </li></ul></div></div>API/launchpadlib (last edited 2024-07-04 12:12:36 by <a class="interwiki" href="https://launchpad.net/~jugmac00" title="jugmac00 @ p200300d30f1d3c0066008dd8781c6932.dip0.t-ipconnect.de[2003:d3:f1d:3c00:6600:8dd8:781c:6932]">jugmac00</a>) <div id="pagebottom"></div> </div> <div id="footer"> <a href="https://help.launchpad.net/Legal">Terms of use</a> | <a href="https://launchpad.net/feedback">Help improve Launchpad</a> | <a href="https://launchpad.net/faq">FAQ</a> | <a href="/RecentChanges">Recent Changes</a> <a rel="license" href="http://creativecommons.org/licenses/by/2.0/uk/"> Launchpad Help by <a xmlns:cc="http://creativecommons.org/ns#" href="https://canonical.com/" property="cc:attributionName" rel="cc:attributionURL">Canonical Ltd</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/2.0/uk/">Creative Commons Attribution 2.0 UK: England & Wales License</a>. <img alt="Creative Commons License" style="border-width:0;vertical-align:middle;" src="https://licensebuttons.net/l/by/2.0/uk/80x15.png" /></a> © 2004-2019 <a href="https://canonical.com/" target="_blank">Canonical Limited.</a> </div> </body> </html>