= BinaryPackageRelease =

BinaryPackageRelease stores unique versions of binarypackagenames
across build records.

   >>> from canonical.launchpad.webapp.testing import verifyObject
   >>> from lp.soyuz.interfaces.binarypackagerelease import (
   ...     IBinaryPackageRelease,
   ...     )
   >>> from lp.soyuz.model.binarypackagerelease import BinaryPackageRelease

   >>> firefox_bin_release = BinaryPackageRelease.get(12)
   >>> verifyObject(IBinaryPackageRelease, firefox_bin_release)
   True

Useful properties:

   >>> firefox_bin_release.name, firefox_bin_release.version
   (u'mozilla-firefox', u'0.9')

   >>> from lp.registry.interfaces.distroseries import IDistroSeriesSet
   >>> warty = getUtility(IDistroSeriesSet).get(1)
   >>> warty.name
   u'warty'
   >>> hoary = getUtility(IDistroSeriesSet).get(3)
   >>> hoary.name
   u'hoary'

Retrieve the respective DistributionSourcePackageRelease, which allow
us to easily link to a source reference published in the web-ui.

   >>> from lp.soyuz.interfaces.distributionsourcepackagerelease import IDistributionSourcePackageRelease
   >>> verifyObject(
   ...    IDistributionSourcePackageRelease,
   ...    firefox_bin_release.distributionsourcepackagerelease)
   True

The 'is_new' property tells us whether or not this
BinaryPackageRelease has ever been published for the DistroArchSeries
it was built for. If not, then 'is_new' will be True, otherwise False.

   >>> firefox_bin_release.is_new
   False

   >>> pmount_bin_release = BinaryPackageRelease.get(20)
   >>> pmount_bin_release.name, pmount_bin_release.version
   (u'pmount', u'0.1-1')

   >>> pmount_bin_release.is_new
   True

The IBinaryPackageNameSet.getNotNewByNames() returns all the
BinaryPackageName records for BinaryPackageReleases that are published
in the supplied distroseries in the archives with the supplied
BinaryPackageNames.  This is a way of quickly establishing the "is_new"
value for a range of packages all at the same time, although it returns
old (published) packages, not new ones.  However, the new packages can
be quickly ascertained through a set operation.

    >>> from zope.security.proxy import removeSecurityProxy
    >>> from lp.soyuz.interfaces.binarypackagename import (
    ...     IBinaryPackageNameSet)
    >>> foobar_name = getUtility(IBinaryPackageNameSet)['foobar']
    >>> name_ids = (
    ...     foobar_name.id,
    ...     pmount_bin_release.binarypackagename.id,
    ...     firefox_bin_release.binarypackagename.id)
    >>> archive_ids = removeSecurityProxy(
    ...     warty.distribution.all_distro_archive_ids)
    >>> names = getUtility(IBinaryPackageNameSet).getNotNewByNames(
    ...     name_ids, warty, archive_ids)

    >>> import operator
    >>> for name in sorted(names, key=operator.attrgetter('name')):
    ...     print name.name
    mozilla-firefox
    pmount

Passing no name_ids gives the EmptyResultSet.

    >>> getUtility(IBinaryPackageNameSet).getNotNewByNames(
    ...     [], warty, archive_ids).count()
    0

Check IBinaryPackageRelease.override() behaviour:

The override method does implicitly exactly the same than:

   BinaryPackagerelease.set(component=new_component,
                            section=new_section,
                            priority=new_priority)

but it only sets the not-empty given arguments, so you can override the
attributes exclusively. It only exists to improve the code clarity,
in ftp-master/queue tool and other scripts.

Display the current firefox component and section:

   >>> firefox_bin_release.component.name, firefox_bin_release.section.name
   (u'main', u'base')

Fetch brand new component, section and priority:

   >>> from lp.soyuz.enums import PackagePublishingPriority
   >>> from lp.soyuz.interfaces.component import IComponentSet
   >>> from lp.soyuz.interfaces.section import ISectionSet
   >>> new_comp = getUtility(IComponentSet)['universe']
   >>> new_sec = getUtility(ISectionSet)['mail']
   >>> new_priority = PackagePublishingPriority.IMPORTANT

Override the current firefox with new component/section/priority:

   >>> firefox_bin_release.override(component=new_comp, section=new_sec,
   ...              priority=new_priority)

Check if it got overridden correctly:

   >>> firefox_bin_release.component.name, firefox_bin_release.section.name, firefox_bin_release.priority.name
   (u'universe', u'mail', 'IMPORTANT')

Override again; ensure that only the changed item actually changes:

   >>> new_sec = getUtility(ISectionSet)['net']
   >>> firefox_bin_release.override(section=new_sec)
   >>> (firefox_bin_release.component.name,
   ...  firefox_bin_release.section.name,
   ...  firefox_bin_release.priority.name)
   (u'universe', u'net', 'IMPORTANT')


Abort transaction to avoid error propagation of the new attributes:

   >>> import transaction
   >>> transaction.abort()


== Binary file association ==

BinaryPackageRelease.addFile() associate given `LibraryFileAlias` with
the context binarypackage release.

We will use `SoyuzTestPublisher` for creating a fresh binary package
release.

    >>> login('foo.bar@canonical.com')

    >>> from lp.soyuz.tests.test_publishing import (
    ...      SoyuzTestPublisher)
    >>> test_publisher = SoyuzTestPublisher()
    >>> test_publisher.prepareBreezyAutotest()

    >>> pubs = test_publisher.getPubBinaries()
    >>> a_binary = pubs[0].binarypackagerelease

The just-create package already has a 'DEB' file associtated to
it. We will create a helper function to inspect binary packagefiles.

    >>> def print_files(binary):
    ...     for bin_file in binary.files:
    ...         print bin_file.libraryfile.filename, bin_file.filetype.name

    >>> print_files(a_binary)
    foo-bin_666_all.deb DEB

Additionally to DEB files, UDEB and DDEB extensions are also supported.

    >>> deb = test_publisher.addMockFile('foo-extra_666_all.deb')
    >>> udeb = test_publisher.addMockFile('foo-inst_666_all.udeb')
    >>> ddeb = test_publisher.addMockFile('foo-dbg_666_all.ddeb')

    >>> unused = a_binary.addFile(deb)
    >>> unused = a_binary.addFile(udeb)
    >>> unused = a_binary.addFile(ddeb)

    >>> print_files(a_binary)
    foo-bin_666_all.deb DEB
    foo-extra_666_all.deb DEB
    foo-inst_666_all.udeb UDEB
    foo-dbg_666_all.ddeb DDEB

An error is raised if a file with an unsupported extension is given.

    >>> boing = test_publisher.addMockFile('foo-dbg_666_all.boing')
    >>> unused = a_binary.addFile(boing)
    Traceback (most recent call last):
    ...
    AssertionError: Unsupported file type: foo-dbg_666_all.boing