Merge lp:~sinzui/launchpad/ds-get-source-package into lp:launchpad

[Curtis Hovey]

[Curtis Hovey (sinzui)]

This is my branch to clarify distroseries getSourcePackage().

    lp:~sinzui/launchpad/ds-get-source-package
    Diff size: 23
    Launchpad bug: https://bugs.launchpad.net/bugs/id
    Test command:
        rm lib/canonical/launchpad/api/index.html; make build
    Pre-implementation: no one
    Target release: 10.02

clarify distroseries getSourcePackage()
---------------------------------------

When using the following commands with the Launchpad API I received back an
object and I don't think I should have.

    karmic.getSourcePackage(name='compiz-plugins')
    <source_package at .../ubuntu/karmic/+source/compiz-plugins>

    However, compiz-plugins does not exist in Karmic
    https://edge.launchpad.net/ubuntu/karmic/+source/compiz-plugins.

Curtis:
    The behaviour is correct. SourcePackages are meta objects for accessing
    publishing history, files, and common names. getSourcePackage() is used
    by Soyuz and Code to create the first publishing record of a file.
    The SourcePackages may also represent a package that was in a distro
    series, but was deleted.

Rules
-----

    * Update getSourcePackage() and getBinaryPackage() documentation to
      clarify that the object returned is not guaranteed to be published
      in the series.

QA
--

    * Verify that the API states that the methods do not guarantee that the
      object was published in the series.

Lint
----

Linting changed files:
  lib/lp/registry/interfaces/distroseries.py

Test
----

None

Implementation
--------------

    * lib/lp/registry/interfaces/distroseries.py
      * Updated the documentation.

[Paul Hummer (rockstar)]

Easy branches are my favorite!

review: Approve (code)

=== modified file 'lib/lp/registry/interfaces/distroseries.py'
--- lib/lp/registry/interfaces/distroseries.py	2010-02-19 12:03:35 +0000
+++ lib/lp/registry/interfaces/distroseries.py	2010-02-25 19:50:38 +0000
@@ -421,7 +421,7 @@
         """Return a source package in this distro series by name.
 
         The name given may be a string or an ISourcePackageName-providing
-        object.
+        object. The source package may not be published in the distro series.
         """
 
     def getTranslatableSourcePackages():
@@ -516,7 +516,8 @@
     def getBinaryPackage(name):
         """Return a DistroSeriesBinaryPackage for this name.
 
-        The name given may be an IBinaryPackageName or a string.
+        The name given may be an IBinaryPackageName or a string.  The
+        binary package may not be published in the distro series.
         """
 
     def getSourcePackageRelease(sourcepackagerelease):