= Soyuz Files =

Soyuz keeps a collection of source and binary packages classified as
SourcePackageRelease and BinaryPackageRelease respectively, each of
those records may contain one or more files according its type.

Those files are stored in the Librarian and related to their parent
object via a BinaryPackageFile or SourcePackageReleaseFile.

SourcePackageReleaseFile or BinaryPackageFile are available via the
'files' attribute on its parent.

 >>> from zope.component import getUtility
 >>> from lp.services.webapp.testing import verifyObject

 >>> from lp.services.librarian.interfaces import ILibraryFileAlias
 >>> from lp.registry.interfaces.distribution import IDistributionSet
 >>> from lp.soyuz.interfaces.files import (
 ...     IBinaryPackageFile,
 ...     ISourcePackageReleaseFile,
 ...     )

 >>> warty = getUtility(IDistributionSet)['ubuntu']['warty']


== Source Files ==

An ISourcePackageRelease contains the file that make up the source
package for that release:

   * An '.orig.tar.gz' file containing the upstream source distribution.
   * A '.diff.tar.gz' file containing the patches applied to the
     upstream source.
   * A '.dsc' package description file.

 >>> warty_firefox_srcpkg = warty.getSourcePackage(
 ...     'mozilla-firefox').currentrelease

 >>> srcfile = warty_firefox_srcpkg.files[0]

 >>> verifyObject(ISourcePackageReleaseFile, srcfile)
 True

 >>> verifyObject(ILibraryFileAlias, srcfile.libraryfile)
 True

 >>> srcfile.libraryfile.filename
 u'firefox_0.9.2.orig.tar.gz'

 >>> srcfile.libraryfile.http_url
 'http://.../3/firefox_0.9.2.orig.tar.gz'


== Binary Files ==

An IBinaryPackageRelease contains only one file which is the
instalable debian-format file:

   * An '.deb'

 >>> warty_i386_pmount_binpkg = warty['i386'].getBinaryPackage(
 ...    'pmount')['2:1.9-1']

 >>> warty_i386_pmount_binpkg.name
 u'pmount'

 >>> debfile = warty_i386_pmount_binpkg.files[0]

 >>> verifyObject(IBinaryPackageFile, debfile)
 True

 >>> verifyObject(ILibraryFileAlias, debfile.libraryfile)
 True

 >>> debfile.libraryfile.filename
 u'pmount_1.9-1_all.deb'

 >>> debfile.libraryfile.http_url
 'http://.../37/pmount_1.9-1_all.deb'


== Utilities ==

There is a utility class IBinaryPackageFileSet that will return
BinaryPackageFile records.

    >>> from lp.soyuz.interfaces.files import (
    ...     IBinaryPackageFileSet)
    >>> file_set = getUtility(IBinaryPackageFileSet)

It only contains one method, getByPackageUploadIDs(), that will return
all the BinaryPackageFiles that are associated with the supplied
PackageUpload IDs.

    >>> ids = (2,)
    >>> binary_package_files = file_set.getByPackageUploadIDs(ids)
    >>> for binary_package_file in binary_package_files:
    ...     print binary_package_file.libraryfile.filename
    pmount_1.0-1_all.deb

Additional IDs may also be passed and if they don't have any
BinaryPackageFiles they are ignored and don't affect the results.

    >>> ids = (1,2,3,4,5)
    >>> binary_package_files = file_set.getByPackageUploadIDs(ids)
    >>> for binary_package_file in binary_package_files:
    ...     print binary_package_file.libraryfile.filename
    pmount_1.0-1_all.deb

If no IDs or None is passed, an empty list is returned.

    >>> file_set.getByPackageUploadIDs([])
    []

    >>> file_set.getByPackageUploadIDs(None)
    []

There is also a utility called SourcePackageReleaseFileSet which has the
same method, getByPackageUploadIDs(), and performs the same function.

    >>> import operator
    >>> from lp.soyuz.interfaces.files import (
    ...     ISourcePackageReleaseFileSet)
    >>> source_file_set = getUtility(ISourcePackageReleaseFileSet)
    >>> ids = (15,)
    >>> source_files = source_file_set.getByPackageUploadIDs(ids)
    >>> for source_file in sorted(source_files,
    ...     key=operator.attrgetter('id')):
    ...     print source_file.libraryfile.filename
    firefox_0.9.2.orig.tar.gz
    iceweasel-1.0.dsc

As with the same method for binary files, it will ignore IDs for which
there are no uploads:

    >>> ids = (14, 15)
    >>> source_files = source_file_set.getByPackageUploadIDs(ids)
    >>> for source_file in sorted(source_files,
    ...     key=operator.attrgetter('id')):
    ...     print source_file.libraryfile.filename
    firefox_0.9.2.orig.tar.gz
    iceweasel-1.0.dsc

If no IDs or None is passed, an empty list is returned.

    >>> source_file_set.getByPackageUploadIDs([])
    []

    >>> source_file_set.getByPackageUploadIDs(None)
    []