Merge lp:~benji/launchpad/add-launchpadlib-examples into lp:launchpad

[Benji York]

Integrate the examples added to the launchpadlib docs by https://launchpad.net/arsenal.

The reStructured Text is somewhat simplistic, but it's what our stack can handle at the moment.

[Leonard Richardson (leonardr)]

This looks good with one exception. The example starting on line 19 shows how to use the HostedFile class. It doesn't belong in the documentation for the Launchpad web service: it (or something equivalent) should show up when you run help() on a HostedFile object.

review: Needs Fixing

[Benji York (benji)]

> This looks good with one exception. The example starting on line 19
> shows how to use the HostedFile class. It doesn't belong in the
> documentation for the Launchpad web service: it (or something
> equivalent) should show up when you run help() on a HostedFile object.

I replaced that bit with a note to the user about finding information
about the HostedFile object in the lazr.restfulclient documentation.

[Leonard Richardson (leonardr)]

It seems like if we're going to put that cross-reference in one place, we should mention it for every single link to a hosted file. But since the goal here is simple cleanup, and this is definitely an improvement, (and I don't actually want to mention it every single time) I'm not going to press the issue. Let's see how users respond and take it from there.

review: Approve

=== modified file 'lib/lp/bugs/interfaces/bugattachment.py'
--- lib/lp/bugs/interfaces/bugattachment.py	2010-09-03 19:32:28 +0000
+++ lib/lp/bugs/interfaces/bugattachment.py	2010-11-02 19:57:57 +0000
@@ -66,7 +66,34 @@
 
 
 class IBugAttachment(IHasBug):
-    """A file attachment to an IBug."""
+    """A file attachment to an IBug.
+
+    Launchpadlib example of accessing content of an attachment::
+
+        for attachment in bug.attachments:
+            buffer = attachment.data.open()
+            for line in buffer:
+                print line
+            buffer.close()
+
+    Launchpadlib example of accessing metadata about an attachment::
+
+        attachment = bug.attachments[0]
+        print "title:", attachment.title
+        print "ispatch:", attachment.type
+
+    For information about the file-like object returned by
+    attachment.data.open() see lazr.restfulclient's documentation of the
+    HostedFile object.
+
+    Details about the message associated with an attachment can be found on
+    the "message" attribute::
+
+        message = attachment.message
+        print "subject:", message.subject.encode('utf-8')
+        print "owner:", message.owner.display_name.encode('utf-8')
+        print "created:", message.date_created
+    """
     export_as_webservice_entry()
 
     id = Int(title=_('ID'), required=True, readonly=True)

=== modified file 'lib/lp/bugs/interfaces/bugtracker.py'
--- lib/lp/bugs/interfaces/bugtracker.py	2010-09-29 21:18:47 +0000
+++ lib/lp/bugs/interfaces/bugtracker.py	2010-11-02 19:57:57 +0000
@@ -200,7 +200,24 @@
 
 
 class IBugTracker(Interface):
-    """A remote bug system."""
+    """A remote bug system.
+
+    Launchpadlib example: What bug tracker is used for a distro source
+    package?
+
+    ::
+
+        product = source_package.upstream_product
+        if product:
+            tracker = product.bug_tracker
+            if not tracker:
+                project = product.project_group
+                if project:
+                    tracker = project.bug_tracker
+        if tracker:
+            print "%s at %s" %(tracker.bug_tracker_type, tracker.base_url)
+
+    """
     export_as_webservice_entry()
 
     id = Int(title=_('ID'))

=== modified file 'lib/lp/registry/interfaces/distribution.py'
--- lib/lp/registry/interfaces/distribution.py	2010-10-29 10:01:34 +0000
+++ lib/lp/registry/interfaces/distribution.py	2010-11-02 19:57:57 +0000
@@ -626,7 +626,19 @@
 class IDistribution(
     IDistributionEditRestricted, IDistributionPublic, IHasBugSupervisor,
     IRootContext, IStructuralSubscriptionTarget):
-    """An operating system distribution."""
+    """An operating system distribution.
+
+    Launchpadlib example: retrieving the current version of a package in a
+    particular distroseries.
+
+    ::
+
+        ubuntu = launchpad.distributions["ubuntu"]
+        archive = ubuntu.main_archive
+        series = ubuntu.current_series
+        print archive.getPublishedSources(exact_match=True,
+            source_name="apport", distro_series=series)[0].source_package_version
+    """
     export_as_webservice_entry()
 
 

=== modified file 'lib/lp/registry/interfaces/person.py'
--- lib/lp/registry/interfaces/person.py	2010-11-02 06:21:58 +0000
+++ lib/lp/registry/interfaces/person.py	2010-11-02 19:57:57 +0000
@@ -1714,9 +1714,22 @@
 
 
 class ITeam(IPerson, ITeamPublic):
-    """ITeam extends IPerson.
-
-    The teamowner should never be None.
+    """A group of people and other teams.
+
+    Launchpadlib example of getting the date a user joined a team::
+
+        def get_join_date(team, user):
+            team = launchpad.people[team]
+            members = team.members_details
+            for member in members:
+                if member.member.name == user:
+                    return member.date_joined
+            return None
+
+    Implementation notes:
+
+    - ITeam extends IPerson.
+    - The teamowner should never be None.
     """
     export_as_webservice_entry('team')