~launchpad-pqm/launchpad/devel

Archives
========

Representations for IArchive can be fetch via the API for PPAs and
distribution archives.

    >>> cprov_archive = webservice.get("/~cprov/+archive/ppa").jsonBody()
    >>> print cprov_archive['self_link']
    http://.../~cprov/+archive/ppa

    >>> main = webservice.get("/ubuntu/+archive/primary").jsonBody()
    >>> print main['self_link']
    http://.../ubuntu/+archive/primary

We publish a subset of their attributes.

    >>> from lazr.restful.testing.webservice import pprint_entry
    >>> pprint_entry(cprov_archive)
    commercial: False
    dependencies_collection_link: u'http://.../~cprov/+archive/ppa/dependencies'
    description: u'packages to help my friends.'
    displayname: u'PPA for Celso Providelo'
    distribution_link: u'http://.../ubuntu'
    name: u'ppa'
    owner_link: u'http://.../~cprov'
    private: False
    require_virtualized: True
    resource_type_link: u'http://.../#archive'
    self_link: u'http://.../~cprov/+archive/ppa'
    signing_key_fingerprint: None
    web_link: u'http://launchpad.../~cprov/+archive/ppa'

While the Archive signing key is being generated its
'signing_key_fingerprint' attribute is None.

We can quickly assign a random OpenPGP key to Celso's PPA.

    >>> from zope.component import getUtility
    >>> from lp.registry.interfaces.person import IPersonSet

    >>> login('foo.bar@canonical.com')
    >>> foo_bar = getUtility(IPersonSet).getByName('name16')
    >>> [a_key] = foo_bar.gpg_keys
    >>> print a_key.fingerprint
    ABCDEF0123456789ABCDDCBA0000111112345678

    >>> cprov = getUtility(IPersonSet).getByName('cprov')
    >>> cprov.archive.signing_key = a_key
    >>> print cprov.archive.signing_key_fingerprint
    ABCDEF0123456789ABCDDCBA0000111112345678

    >>> logout()

And then the new attribute value is exported as a string.

    >>> cprov_archive = webservice.get("/~cprov/+archive/ppa").jsonBody()
    >>> print cprov_archive['signing_key_fingerprint']
    ABCDEF0123456789ABCDDCBA0000111112345678

Distributions can provide information about their archives.  Looking
at "ubuntutest":

    >>> distros = webservice.get("/distros").jsonBody()
    >>> for entry in distros['entries']:
    ...    print entry['self_link']
    http://.../ubuntu
    http://.../kubuntu
    http://.../ubuntutest
    http://.../debian
    http://.../gentoo

    >>> ubuntutest = distros['entries'][2]
    >>> ubuntu = distros['entries'][0]

"ubuntutest" has a "main_archive" which is always present:

    >>> print ubuntutest['main_archive_link']
    http://.../ubuntutest/+archive/primary

The archive has the following attributes:

    >>> ubuntu_main_archive = webservice.get(
    ...     ubuntutest['main_archive_link']).jsonBody()
    >>> pprint_entry(ubuntu_main_archive)
    commercial: False
    dependencies_collection_link: u'http://.../ubuntutest/+archive/primary/dependencies'
    description: None
    displayname: u'Primary Archive for Ubuntu Test'
    distribution_link: u'http://.../ubuntutest'
    name: u'primary'
    owner_link: u'http://.../~ubuntu-team'
    private: False
    require_virtualized: False
    resource_type_link: u'http://.../#archive'
    self_link: u'http://.../ubuntutest/+archive/primary'
    signing_key_fingerprint: None
    web_link: u'http://launchpad.../ubuntutest/+archive/primary'

A distribution can also provide a list of all its archives:

    >>> print ubuntutest['archives_collection_link']
    http://.../ubuntutest/archives
    >>> archives = webservice.get(
    ...     ubuntutest['archives_collection_link']).jsonBody()
    >>> print_self_link_of_entries(archives)
    http://api.launchpad.dev/beta/ubuntutest/+archive/partner
    http://api.launchpad.dev/beta/ubuntutest/+archive/primary

Attempting to grab a non-existent archive will result in a 404 error:

    >>> bogus_archive = "http://api.launchpad.dev/beta/ubuntutest/+archive/bogus"
    >>> print webservice.get(bogus_archive)
    HTTP/1.1 404 Not Found
    ...
    Object: ..., name: u'bogus'


= Archive Permissions =

Archives have associated permissions.  These are currently either upload
rights or queue administration rights.  The URL to the permissions
takes two forms:
 * <archive>/+upload/username.item
 * <archive>/+queue-admin/username.item
where `item` is a component or a source package name.

This is a permission that allows a team to upload to a component:

    >>> url = '/ubuntu/+archive/primary/+upload/ubuntu-team?type=component&item=main'
    >>> ubuntu_main_permission = webservice.get(url).jsonBody()
    >>> pprint_entry(ubuntu_main_permission)
    archive_link: u'http://.../ubuntu/+archive/primary'
    component_name: u'main'
    date_created: ...
    permission: u'Archive Upload Rights'
    person_link: u'http://.../~ubuntu-team'
    resource_type_link: ...
    self_link: u'http://.../ubuntu/+archive/primary/+upload/ubuntu-team?type=component&item=main'
    source_package_name: None

This is a permission that allows an individual to upload a source package.

    >>> url = '/ubuntu/+archive/primary/+upload/carlos?type=packagename&item=mozilla-firefox'
    >>> carlos_mozilla_permission = webservice.get(url).jsonBody()
    >>> pprint_entry(carlos_mozilla_permission)
    archive_link: u'http://.../ubuntu/+archive/primary'
    component_name: None
    date_created: ...
    permission: u'Archive Upload Rights'
    person_link: u'http://.../~carlos'
    resource_type_link: ...
    self_link:
        u'http://.../ubuntu/+archive/primary/+upload/carlos?type=packagename&item=mozilla-firefox'
    source_package_name: u'mozilla-firefox'

This is a queue admin right for ubuntu-team:

    >>> url = '/ubuntu/+archive/primary/+queue-admin/ubuntu-team?type=component&item=main'
    >>> ubuntu_main_permission = webservice.get(url).jsonBody()
    >>> pprint_entry(ubuntu_main_permission)
    archive_link: u'http://.../ubuntu/+archive/primary'
    component_name: u'main'
    date_created: ...
    permission: u'Queue Administration Rights'
    person_link: u'http://.../~ubuntu-team'
    resource_type_link: ...
    self_link:
        u'http://.../ubuntu/+archive/primary/+queue-admin/ubuntu-team?type=component&item=main'
    source_package_name: None

And one for an individual:

    >>> url = '/ubuntu/+archive/primary/+queue-admin/name12?type=component&item=universe'
    >>> name16_admin_permission = webservice.get(url).jsonBody()
    >>> pprint_entry(name16_admin_permission)
    archive_link: u'http://.../ubuntu/+archive/primary'
    component_name: u'universe'
    date_created: ...
    permission: u'Queue Administration Rights'
    person_link: u'http://.../~name12'
    resource_type_link: ...
    self_link:
        u'http://.../ubuntu/+archive/primary/+queue-admin/name12?type=component&item=universe'
    source_package_name: None


== Archive Permission Custom Operations ==

Permission collections can be retrieved with custom operations on the
archive.

`getPermissionsForPerson` returns all the permissions that a user has.

    >>> ubuntu_team = user_webservice.get("/~ubuntu-team").jsonBody()
    >>> permissions = user_webservice.named_get(
    ...     ubuntutest['main_archive_link'], 'getPermissionsForPerson',
    ...     person=ubuntu_team['self_link']).jsonBody()

    >>> def permission_entry_sort_key(entry):
    ...      return (entry['permission'],
    ...              entry['person_link'],
    ...              entry['component_name'],
    ...              entry['source_package_name']),

    >>> def show_permission_entries(permissions):
    ...     for entry in sorted(permissions['entries'],
    ...                         key=permission_entry_sort_key):
    ...         print entry['permission']
    ...         print entry['person_link']
    ...         print entry['component_name']
    ...         print entry['source_package_name']

    >>> show_permission_entries(permissions)
    Archive Upload Rights ...~ubuntu-team main None
    Archive Upload Rights ...~ubuntu-team universe None

`getUploadersForPackage` returns all the permissions where someone can
upload a particular package.

    >>> def show_mozilla_permissions():
    ...     permissions = user_webservice.named_get(
    ...         ubuntu['main_archive_link'], 'getUploadersForPackage',
    ...         source_package_name='mozilla-firefox').jsonBody()
    ...     show_permission_entries(permissions)

    >>> show_mozilla_permissions()
    Archive Upload Rights ...~carlos None mozilla-firefox

Passing a bad package name results in an error:

    >>> print user_webservice.named_get(
    ...     ubuntu['main_archive_link'], 'getUploadersForPackage',
    ...     source_package_name="badpackage")
    HTTP/1.1 400 Bad Request
    ...

Colin is a valid member of the team who owns the ubuntu primary archive.

    >>> from canonical.launchpad.testing.pages import webservice_for_person
    >>> from canonical.launchpad.webapp.interfaces import OAuthPermission
    >>> from lp.registry.interfaces.distribution import IDistributionSet

    >>> login(ANONYMOUS)
    >>> cjwatson = getUtility(IPersonSet).getByName('kamion')
    >>> ubuntu_db = getUtility(IDistributionSet).getByName('ubuntu')
    >>> cjwatson.inTeam(ubuntu_db.main_archive.owner)
    True

    >>> logout()

    >>> cjwatson_webservice = webservice_for_person(
    ...     cjwatson, permission=OAuthPermission.WRITE_PUBLIC)


`newPackageUploader` is a factory function that adds a new permission
for a person to upload a package.

    >>> name12 = webservice.get("/~name12").jsonBody()
    >>> response = cjwatson_webservice.named_post(
    ...     ubuntu['main_archive_link'], 'newPackageUploader', {},
    ...     person=name12['self_link'],
    ...     source_package_name='mozilla-firefox')
    >>> print response
    HTTP/1.1 201 Created
    ...

    >>> new_permission = user_webservice.get(
    ...     response.getHeader('Location')).jsonBody()
    >>> print new_permission['self_link']
    http://.../ubuntu/+archive/primary/+upload/name12?type=packagename&item=mozilla-firefox

    >>> show_mozilla_permissions()
    Archive Upload Rights ...~carlos None mozilla-firefox
    Archive Upload Rights ...~name12 None mozilla-firefox

deletePackageUploader() removes that permission:

    >>> print cjwatson_webservice.named_post(
    ...     ubuntu['main_archive_link'], 'deletePackageUploader', {},
    ...     person=name12['self_link'],
    ...     source_package_name='mozilla-firefox')
    HTTP/1.1 200 Ok
    ...

And we can see that it's gone:

    >>> show_mozilla_permissions()
    Archive Upload Rights ...~carlos None mozilla-firefox

getUploadersForComponent returns all the permissions where someone can
upload to a particular component:

    >>> def show_component_permissions(component=None):
    ...     permissions = user_webservice.named_get(
    ...         ubuntu['main_archive_link'], 'getUploadersForComponent',
    ...         component_name=component).jsonBody()
    ...     show_permission_entries(permissions)

    >>> show_component_permissions("main")
    Archive Upload Rights ...~ubuntu-team main None

Passing a bad component name results in an error:

    >>> print cjwatson_webservice.named_get(
    ...     ubuntu['main_archive_link'], 'getUploadersForComponent',
    ...     component_name="badcomponent")
    HTTP/1.1 400 Bad Request
    ...

If you don't specify the component, you get all the uploaders for
all components.

    >>> show_component_permissions()
    Archive Upload Rights ...~ubuntu-team main None
    Archive Upload Rights ...~ubuntu-team universe None

newComponentUploader adds a new permission for a person to upload to a
component.

    >>> response = cjwatson_webservice.named_post(
    ...     ubuntu['main_archive_link'], 'newComponentUploader', {},
    ...     person=name12['self_link'],
    ...     component_name='restricted')
    >>> print response
    HTTP/1.1 201 Created
    ...

    >>> new_permission = user_webservice.get(
    ...     response.getHeader('Location')).jsonBody()
    >>> print new_permission['self_link']
    http://.../ubuntu/+archive/primary/+upload/name12?type=component&item=restricted

    >>> show_component_permissions()
    Archive Upload Rights ...~name12 restricted None
    Archive Upload Rights ...~ubuntu-team main None
    Archive Upload Rights ...~ubuntu-team restricted None
    Archive Upload Rights ...~ubuntu-team universe None

We can use ``checkUpload`` to verify that a person can upload a 
sourcepackage.

    >>> grumpy = user_webservice.get("/ubuntu/grumpy").jsonBody()
    >>> response = user_webservice.named_get(
    ...     ubuntu['main_archive_link'], 'checkUpload', 
    ...     distroseries=grumpy['self_link'],
    ...     sourcepackagename='mozilla-firefox', pocket='Release',
    ...     component='restricted', person=name12['self_link'])
    >>> print(response)
    HTTP/1.1 200 Ok
    ...

deleteComponentUploader() removes that permission:

    >>> print cjwatson_webservice.named_post(
    ...     ubuntu['main_archive_link'], 'deleteComponentUploader', {},
    ...     person=name12['self_link'],
    ...     component_name='restricted')
    HTTP/1.1 200 Ok
    ...

And we can see that it's gone:

    >>> show_component_permissions()
    Archive Upload Rights ...~ubuntu-team main None
    Archive Upload Rights ...~ubuntu-team restricted None
    Archive Upload Rights ...~ubuntu-team universe None

And ``checkUpload`` now also no longer passes:

    >>> grumpy = user_webservice.get("/ubuntu/grumpy").jsonBody()
    >>> response = user_webservice.named_get(
    ...     ubuntu['main_archive_link'], 'checkUpload', 
    ...     distroseries=grumpy['self_link'],
    ...     sourcepackagename='mozilla-firefox', pocket='Release',
    ...     component='main', person=name12['self_link'])
    >>> print(response)
    HTTP/1.1 403 Forbidden
    ...
    The signer of this package has no upload rights to
    this distribution's primary archive.  Did you mean to upload to a PPA?


Only the archive owners can add or remove component-uploaders.

    >>> no_priv = webservice.get("/~no-priv").jsonBody()

    >>> print user_webservice.named_post(
    ...     cprov_archive['self_link'], 'newComponentUploader', {},
    ...     person=no_priv['self_link'], component_name='main')
    HTTP/1.1 401 Unauthorized
    ...

    >>> cprov_webservice = webservice_for_person(
    ...     cprov, permission=OAuthPermission.WRITE_PUBLIC)

    >>> print cprov_webservice.named_post(
    ...     cprov_archive['self_link'], 'newComponentUploader', {},
    ...     person=no_priv['self_link'], component_name='main')
    HTTP/1.1 201 Created
    ...

    >>> print cprov_webservice.named_post(
    ...     cprov_archive['self_link'], 'deleteComponentUploader', {},
    ...     person=no_priv['self_link'],
    ...     component_name='main')
    HTTP/1.1 200 Ok
    ...

If you add a new permission for someone to upload to a PPA, you must specify
the 'main' component, or an error is returned:

    >>> response = cprov_webservice.named_post(
    ...     cprov_archive['self_link'], 'newComponentUploader', {},
    ...     person=name12['self_link'], component_name='restricted')
    >>> print response
    HTTP/1.1 400 Bad Request
    ...
    Component for PPAs should be 'main'

getQueueAdminsForComponent returns all the permissions where someone
can administer distroseries queues in a particular component.

    >>> def show_admins_for_component(component):
    ...     permissions = webservice.named_get(
    ...         ubuntu['main_archive_link'], 'getQueueAdminsForComponent',
    ...         component_name=component).jsonBody()
    ...     show_permission_entries(permissions)

    >>> show_admins_for_component("main")
    Queue Administration Rights ...~name12 main None
    Queue Administration Rights ...~ubuntu-team main None

getComponentsForQueueAdmin returns all the permissions relating to components
where the user is able to administer distroseries queues.

    >>> def show_components_for_admin(person):
    ...     permissions = webservice.named_get(
    ...         ubuntu['main_archive_link'], 'getComponentsForQueueAdmin',
    ...         person=person['self_link']).jsonBody()
    ...     show_permission_entries(permissions)

    >>> show_components_for_admin(name12)
    Queue Administration Rights ...~name12 main None
    Queue Administration Rights ...~name12 multiverse None
    Queue Administration Rights ...~name12 restricted None
    Queue Administration Rights ...~name12 universe None

newQueueAdmin adds a new permission for a person to administer distroseries
queues in a particular component.

    >>> response = webservice.named_post(
    ...     ubuntu['main_archive_link'], 'newQueueAdmin', {},
    ...     person=name12['self_link'],
    ...     component_name='partner')
    >>> print response
    HTTP/1.1 201 Created
    ...

    >>> new_permission = webservice.get(
    ...     response.getHeader('Location')).jsonBody()
    >>> print new_permission['self_link']
    http://.../ubuntu/+archive/primary/+queue-admin/name12?type=component&item=partner

    >>> show_components_for_admin(name12)
    Queue Administration Rights ...~name12 main None
    Queue Administration Rights ...~name12 multiverse None
    Queue Administration Rights ...~name12 partner None
    Queue Administration Rights ...~name12 restricted None
    Queue Administration Rights ...~name12 universe None

deleteQueueAdmin removes that permission.

    >>> print webservice.named_post(
    ...     ubuntu['main_archive_link'], 'deleteQueueAdmin', {},
    ...     person=name12['self_link'],
    ...     component_name='partner')
    HTTP/1.1 200 Ok
    ...

And we can see that it's gone:

    >>> show_components_for_admin(name12)
    Queue Administration Rights ...~name12 main None
    Queue Administration Rights ...~name12 multiverse None
    Queue Administration Rights ...~name12 restricted None
    Queue Administration Rights ...~name12 universe None

== Malformed archive permission URLs ==

Malformed URLs are handled reasonably well.

The type of item for which we seek the archive permission is missing. The
latter can thus not be found.

    >>> missing_type_url = '/ubuntu/+archive/primary/+upload/name12?item=firefox'
    >>> this_will_fail = webservice.get(missing_type_url)
    >>> print this_will_fail
    HTTP/1.1 404 Not Found
    ...

The ultimate item type ('Integer') is wrong. The archive permission is hence
not found.

    >>> wrong_type_url = '/ubuntu/+archive/primary/+upload/name12?type=packageset&item=firefox&type=Integer'
    >>> this_will_fail = webservice.get(missing_type_url)
    >>> print this_will_fail
    HTTP/1.1 404 Not Found
    ...

The item name is missing. The archive permission is hence not found.

    >>> missing_item_url = '/ubuntu/+archive/primary/+upload/name12?type=packageset'
    >>> this_will_fail = webservice.get(missing_type_url)
    >>> print this_will_fail
    HTTP/1.1 404 Not Found
    ...

The ultimate item name ('vapourware') is wrong. The archive permission is hence
not found.

    >>> wrong_type_url = '/ubuntu/+archive/primary/+upload/name12?type=packageset&item=firefox&item=vapourware'
    >>> this_will_fail = webservice.get(missing_type_url)
    >>> print this_will_fail
    HTTP/1.1 404 Not Found
    ...


= Getting Build counts for an IArchive =

IArchive exposes the getBuildCounters() method, enabling this data to be
used and displayed via XHR.

    >>> build_counters = webservice.named_get(
    ...     ubuntu['main_archive_link'], 'getBuildCounters').jsonBody()
    >>> for key, val in build_counters.items():
    ...     print "%s: %s" % (key, val)
    failed: 5
    superseded: 3
    total: 18
    pending: 2
    succeeded: 8

The optional param exclude_needsbuild is also provided:

    >>> build_counters = webservice.named_get(
    ...     ubuntu['main_archive_link'], 'getBuildCounters',
    ...     include_needsbuild=False).jsonBody()
    >>> for key, val in build_counters.items():
    ...     print "%s: %s" % (key, val)
    failed: 5
    superseded: 3
    total: 17
    pending: 1
    succeeded: 8

== Getting published sources and binaries for an IArchive ==

IArchive exposes the getPublishedSources() and getPublishedBinaries()
methods.

    >>> response = webservice.named_get(
    ...     cprov_archive['self_link'], 'getPublishedSources')
    >>> print response.getheader('status')
    200 Ok
    >>> response = webservice.named_get(
    ...     cprov_archive['self_link'], 'getPublishedBinaries')
    >>> print response.getheader('status')
    200 Ok

If either method is called with the version parameter, the name must
be specified too, otherwise it is considered a bad webservice
request.

    >>> response = webservice.named_get(
    ...     cprov_archive['self_link'], 'getPublishedSources', version='1.0')
    >>> print response.getheader('status')
    400 Bad Request
    >>> response = webservice.named_get(
    ...     cprov_archive['self_link'], 'getPublishedBinaries',
    ...     version='1.0')
    >>> print response.getheader('status')
    400 Bad Request


== Package copying/synchronisation ==

IArchive contains 2 custom operations to copy packages from another archive.
These are syncSource() and syncSources(). Both are wrappers of the
`PackageCopier` infrastructure, see more information in
scripts/packagecopier.py.

For testing purpose we will create some publications.

    >>> login('foo.bar@canonical.com')
    >>> from lp.soyuz.tests.test_publishing import SoyuzTestPublisher
    >>> test_publisher = SoyuzTestPublisher()
    >>> hoary = ubuntu_db.getSeries('hoary')
    >>> test_publisher.addFakeChroots(hoary)
    >>> ignore = test_publisher.setUpDefaultDistroSeries(hoary)

'package1' (with two versions) and 'package2' publications in the
ubuntu primary archive.

    >>> ignore = test_publisher.getPubSource(
    ...     sourcename="package1", version="1.0",
    ...     archive=ubuntu_db.main_archive)

    >>> from lp.soyuz.enums import (
    ...     PackagePublishingStatus)
    >>> ignore = test_publisher.getPubSource(
    ...     sourcename="package1", version="1.1",
    ...     archive=ubuntu_db.main_archive,
    ...     status=PackagePublishingStatus.PUBLISHED)

    >>> ignore = test_publisher.getPubSource(
    ...     sourcename="package2", version="1.0",
    ...     archive=ubuntu_db.main_archive)

A test publication in Celso's PPA.

    >>> ignore = test_publisher.getPubSource(
    ...     sourcename="package3", version="1.0", archive=cprov.archive)

Setup done, let's log out and continue with the tests.

    >>> logout()

syncSource() copies a single package with a specific version from another
archive.  It will prevent unauthorised changes to an archive.  Here we are
using user_webservice, which has no privileges, and trying to copy to
the Ubuntu main archive:

    >>> print user_webservice.named_post(
    ...     ubuntu['main_archive_link'], 'syncSource', {},
    ...     source_name='package3', version='1.0',
    ...     from_archive=cprov_archive['self_link'], to_pocket='release',
    ...     to_series="hoary")
    HTTP/1.1 401 Unauthorized
    ...

When accessed via Colin's key that can perform writes, the API will
respond positively.

    >>> print cjwatson_webservice.named_post(
    ...     ubuntu['main_archive_link'], 'syncSource', {},
    ...     source_name='package3', version='1.0',
    ...     from_archive=cprov_archive['self_link'], to_pocket='release',
    ...     to_series="hoary")
    HTTP/1.1 200 Ok
    ...

Now copy "package1" version 1.0 from the main archive into cprov's
PPA. The 'admin_write' key created for Colin isn't allowed to modify
Celso's PPA.

    >>> print cjwatson_webservice.named_post(
    ...     cprov_archive['self_link'], 'syncSource', {},
    ...     source_name='package1', version='1.0',
    ...     from_archive=ubuntu['main_archive_link'], to_pocket='release',
    ...     to_series="hoary")
    HTTP/1.1 401 Unauthorized
    ...

Only a key created by Celso with write permissions will allow this
operation.

    >>> cprov_webservice = webservice_for_person(
    ...     cprov, permission=OAuthPermission.WRITE_PUBLIC)

    >>> print cprov_webservice.named_post(
    ...     cprov_archive['self_link'], 'syncSource', {},
    ...     source_name='package1', version='1.0',
    ...     from_archive=ubuntu['main_archive_link'], to_pocket='release',
    ...     to_series="hoary")
    HTTP/1.1 200 Ok
    ...

syncSources() allows the caller to specify a list of sources to copy all at
once.  The latest versions that are found in the from_archive are
"synchronised" to the context archive.  If a particular version already
exists then nothing is copied.

    >>> print cprov_webservice.named_post(
    ...     cprov_archive['self_link'], 'syncSources', {},
    ...     source_names=['package1', 'package2'],
    ...     from_archive=ubuntu['main_archive_link'], to_pocket='release',
    ...     to_series="warty")
    HTTP/1.1 200 Ok
    ...

The operation is still successful if there is nothing to copy, as you
would expect from a 'sync-like' method.

    >>> already_copied = cprov_webservice.named_post(
    ...     cprov_archive['self_link'], 'syncSources', {},
    ...     source_names=['package1', 'package2'],
    ...     from_archive=ubuntu['main_archive_link'], to_pocket='release',
    ...     to_series="warty")
    >>> print already_copied
    HTTP/1.1 200 Ok
    ...

Within the web application, the CannotCopy exception means that there
was an oversight in the code that called syncSources()--that method
shouldn't have been called in the first place. The CannotCopy
exception therefore results in an OOPS. But within the web service,
syncSources is invoked directly by the client, and any problems are
the client's fault. Therefore, there's no need to record an OOPS.

    >>> print already_copied.getheader('X-Lazr-Oopsid')
    None

'syncSources' behaves trasactionally, i.e. it will only synchronise
all packages or none of them if there was a problem.

    # Create an 'allowed' source publication with binaries in main_archive.
    # It can be successfully synchronised to Celso's PPA.
    >>> login('foo.bar@canonical.com')
    >>> allowed_source = test_publisher.getPubSource(
    ...     sourcename="allowed", version="1.0",
    ...     archive=ubuntu_db.main_archive)
    >>> ignore = test_publisher.getPubBinaries(pub_source=allowed_source)
    >>> logout()

'package1' has no binaries to be copied, so when we attempt to copy
'allowed' and 'package1' with binaries an error is returned.

    >>> print cprov_webservice.named_post(
    ...     cprov_archive['self_link'], 'syncSources', {},
    ...     source_names=['allowed', 'package1'],
    ...     from_archive=ubuntu['main_archive_link'], to_pocket='release',
    ...     to_series="warty", include_binaries=True)
    HTTP/1.1 400 Bad Request
    ...
    package1 1.1 in hoary (source has no binaries to be copied)

Even if the error was only when processing 'package1', the 'allowed'
source was not synchronised to Celso's PPA.

    >>> cprov_webservice.named_get(
    ...     cprov_archive['self_link'], 'getPublishedSources',
    ...     source_name="allowed").jsonBody()['total_size']
    0

Keys with insufficient permissions on Celso's PPA context are not
allowed to call the method at all.

    >>> print user_webservice.named_post(
    ...     cprov_archive['self_link'], 'syncSources', {},
    ...     source_names=['package1', 'package2'],
    ...     from_archive=ubuntu['main_archive_link'], to_pocket='release',
    ...     to_series="warty")
    HTTP/1.1 401 Unauthorized
    ...

    >>> print cjwatson_webservice.named_post(
    ...     cprov_archive['self_link'], 'syncSources', {},
    ...     source_names=['package1', 'package2'],
    ...     from_archive=ubuntu['main_archive_link'], to_pocket='release',
    ...     to_series="warty")
    HTTP/1.1 401 Unauthorized
    ...

== Non-virtualized archives ==

Modifying the require_virtualized flag through the API is not allowed except for
admins and commercial admins.

    >>> import simplejson
    >>> def modify_archive(service, archive):
    ...     headers = {'Content-type': 'application/json'}
    ...     return service(
    ...         archive['self_link'], 'PUT', simplejson.dumps(archive),
    ...         headers)

    >>> login('foo.bar@canonical.com')
    >>> admin_person = getUtility(IPersonSet).getByName('mark')
    >>> admin_webservice = webservice_for_person(
    ...     admin_person, permission=OAuthPermission.WRITE_PUBLIC)
    >>> logout()

    >>> mark_archive = webservice.get("/~mark/+archive/ppa").jsonBody()
    >>> mark_archive['require_virtualized'] = False
    >>> response = modify_archive(admin_webservice, mark_archive)
    >>> webservice.get("/~mark/+archive/ppa").jsonBody()['require_virtualized']
    False

Attempting to modify this flag without the necessary permissions will fail.

    >>> print modify_archive(user_webservice, mark_archive)
    HTTP/1.1 400 Bad Request
    ...
    http_etag: You tried to modify a read-only attribute.

== Private archives ==

Create a private PPA for Celso with a private source publication.

    >>> login('foo.bar@canonical.com')
    >>> cprov_private_ppa_db = factory.makeArchive(
    ...     private=True, owner=cprov, distribution=ubuntu_db, name="p3a",
    ...     description="packages to help my friends.")
    >>> private_publication = test_publisher.createSource(
    ...     cprov_private_ppa_db, 'foocomm', '1.0-1')
    >>> private_publication.status = (
    ...     PackagePublishingStatus.PUBLISHED)

    >>> logout()

Now we need a webservice with rights to read private data in order to
be able to access Celso's private PPA.

    >>> cprov_webservice = webservice_for_person(
    ...     cprov, permission=OAuthPermission.WRITE_PRIVATE)

Note that the 'description' and the 'signing_key_fingerprint'
attributes are only exposed when the requestor has View permission in
the IArchive context, in this case only Celso has it.

    >>> pprint_entry(user_webservice.get("/~cprov/+archive/p3a").jsonBody())
    commercial: False
    dependencies_collection_link: u'http://.../~cprov/+archive/p3a/dependencies'
    description: u'tag:launchpad.net:2008:redacted'
    displayname: u'PPA named p3a for Celso Providelo'
    distribution_link: u'http://.../ubuntu'
    name: u'p3a'
    owner_link: u'http://.../~cprov'
    private: True
    require_virtualized: True
    resource_type_link: u'http://.../#archive'
    self_link: u'http://.../~cprov/+archive/p3a'
    signing_key_fingerprint: u'tag:launchpad.net:2008:redacted'
    web_link: u'http://launchpad.../~cprov/+archive/p3a'

    >>> pprint_entry(cprov_webservice.get("/~cprov/+archive/p3a").jsonBody())
    commercial: False
    dependencies_collection_link: u'http://.../~cprov/+archive/p3a/dependencies'
    description: u'packages to help my friends.'
    displayname: u'PPA named p3a for Celso Providelo'
    distribution_link: u'http://.../ubuntu'
    name: u'p3a'
    owner_link: u'http://.../~cprov'
    private: True
    require_virtualized: True
    resource_type_link: u'http://.../#archive'
    self_link: u'http://.../~cprov/+archive/p3a'
    signing_key_fingerprint: u'ABCDEF0123456789ABCDDCBA0000111112345678'
    web_link: u'http://launchpad.../~cprov/+archive/p3a'

== Creating subscriptions to a (private) archive ==

IArchive exposes the newSubscription() method, enabling new subscriptions
to be created via AJAX.

Archive subscriptions can only be created for private archives. If we
try creating a subscription for mark's archive (which is public), a
bad request will result:

    >>> login('foo.bar@canonical.com')
    >>> mark_db = getUtility(IPersonSet).getByName('mark')
    >>> mark_webservice = webservice_for_person(
    ...     mark_db, permission=OAuthPermission.WRITE_PUBLIC)
    >>> logout()
    >>> mark = mark_webservice.get("/~mark").jsonBody()
    >>> mark_archive = mark_webservice.get(
    ...     "/~mark/+archive/ppa").jsonBody()
    >>> response = mark_webservice.named_post(
    ...     mark_archive['self_link'], 'newSubscription',
    ...     subscriber=cprov_archive['owner_link'])
    >>> print response
    HTTP/1.1 400 Bad Request
    ...
    Only private archives can have subscriptions.

First we'll subscribe mark to cprov's archive:

    >>> mark = webservice.get("/~mark").jsonBody()
    >>> cprov_private_ppa = cprov_webservice.get(
    ...     "/~cprov/+archive/p3a").jsonBody()
    >>> response = cprov_webservice.named_post(
    ...     cprov_private_ppa['self_link'], 'newSubscription',
    ...     subscriber=mark['self_link'])

    >>> print response
    HTTP/1.1 201 Created
    ...

    >>> print response.getHeader('Location')
    http://.../~cprov/+archive/p3a/+subscriptions/mark

We publish a subset of the IArchiveSubscriber attributes.

    >>> new_subscription = cprov_webservice.get(
    ...     response.getHeader('Location')).jsonBody()
    >>> pprint_entry(new_subscription)
    archive_link: u'http://api.launchpad.dev/beta/~cprov/+archive/p3a'
    date_created: ...
    date_expires: None
    description: None
    registrant_link: u'http://api.launchpad.dev/beta/~cprov'
    resource_type_link: u'http://api.launchpad.dev/beta/#archive_subscriber'
    self_link: u'http://api.../~cprov/+archive/p3a/+subscriptions/mark'
    status: u'Active'
    subscriber_link: u'http://api.launchpad.dev/beta/~mark'
    web_link: u'http://launchpad.../~cprov/+archive/p3a/+subscriptions/mark'

Other webservice users cannot view the subscription.

    >>> response = user_webservice.get(
    ...     response.getHeader('Location'))
    >>> print response
    HTTP/1.1 401 Unauthorized
    ...

Similarly, other webservice users cannot create a new subscription
as the calling user must have append privileges on the archive
to use this method.

    >>> response = user_webservice.named_post(
    ...     cprov_archive['self_link'], 'newSubscription',
    ...     subscriber=cprov_private_ppa['owner_link'])
    >>> print response
    HTTP/1.1 401 Unauthorized
    ...

A second subscription cannot be created for the same user/team when there
is already a current subscription:

    >>> response = cprov_webservice.named_post(
    ...     cprov_private_ppa['self_link'], 'newSubscription',
    ...     subscriber=mark['self_link'])
    >>> print response
    HTTP/1.1 400 Bad Request
    ...
    Mark Shuttleworth already has a current subscription
    for 'PPA named p3a for Celso Providelo'.


== Modifying privacy ==

Modifying the privacy flag through the API is not allowed except for
admins and commercial admins.

    >>> mark_archive = webservice.get("/~mark/+archive/ppa").jsonBody()
    >>> mark_archive['private'] = True
    >>> print modify_archive(user_webservice, mark_archive)
    HTTP/1.1 401 Unauthorized
    ...
    (<Archive at ...>, 'private', 'launchpad.Commercial')


=== Copying private file to public archives ===

Copying private sources to public archives works fine with
`syncSource` or `syncSources` operations.

We use `syncSource` to copy 'foocomm - 1.0-1' source from Celso's
private PPA to the ubuntu primary archive.

    >>> print cprov_webservice.named_post(
    ...     ubuntu['main_archive_link'], 'syncSource', {},
    ...     source_name='foocomm', version='1.0-1', to_pocket='release',
    ...     from_archive=cprov_private_ppa['self_link'],
    ...     to_series="hoary")
    HTTP/1.1 200 Ok
    ...

In the same way we can use 'syncSources' for syncing an subsequent
version.

    >>> login('foo.bar@canonical.com')
    >>> subsequent_version = test_publisher.createSource(
    ...     cprov_private_ppa_db, 'foocomm', '1.0-2')
    >>> subsequent_version.status = (
    ...     PackagePublishingStatus.PUBLISHED)
    >>> logout()

    >>> print cprov_webservice.named_post(
    ...     ubuntu['main_archive_link'], 'syncSources', {},
    ...     source_names=['foocomm'], to_pocket='release',
    ...     from_archive=cprov_private_ppa['self_link'],
    ...     to_series="hoary")
    HTTP/1.1 200 Ok
    ...

Although if we try to copy an old version, by repeating the copy an
error is returned.

    >>> print cprov_webservice.named_post(
    ...     ubuntu['main_archive_link'], 'syncSource', {},
    ...     source_name='foocomm', version='1.0-2', to_pocket='release',
    ...     from_archive=cprov_private_ppa['self_link'],
    ...     to_series="hoary")
    HTTP/1.1 400 Bad Request
    ...
    foocomm 1.0-2 in hoary
    (same version already uploaded and waiting in ACCEPTED queue)


= Archive dependencies =

Archives can specify dependencies on pockets and components of other
archives. Found at <dependentarchive.id>/+dependency/<dependencyarchive.id>,
these IArchiveDependency records can be retrieved through the API.

First we'll add an explicit dependency on the primary archive to
cprov's PPA. We can't do this through the webservice yet.

    >>> from lp.registry.interfaces.pocket import PackagePublishingPocket
    >>> from lp.soyuz.interfaces.component import IComponentSet
    >>> login('foo.bar@canonical.com')
    >>> dep = cprov.archive.addArchiveDependency(
    ...     cprov.archive.distribution.main_archive,
    ...     PackagePublishingPocket.RELEASE,
    ...     component=getUtility(IComponentSet)['universe'])
    >>> logout()

We can then request that dependency, and see that we get all of its
attributes.

    >>> cprov_main_dependency = webservice.named_get(
    ...     '/~cprov/+archive/ppa', 'getArchiveDependency',
    ...     dependency=ubuntu['main_archive_link']).jsonBody()
    >>> pprint_entry(cprov_main_dependency)
    archive_link: u'http://.../~cprov/+archive/ppa'
    component_name: u'universe'
    date_created: ...
    dependency_link: u'http://.../ubuntu/+archive/primary'
    pocket: u'Release'
    resource_type_link: u'http://.../#archive_dependency'
    self_link: u'http://.../~cprov/+archive/ppa/+dependency/1'
    title: u'Primary Archive for Ubuntu Linux - RELEASE (main, universe)'

Asking for an archive on which there is no dependency returns None.

    >>> debian = webservice.get('/debian').jsonBody()
    >>> webservice.named_get(
    ...     '/~cprov/+archive/ppa', 'getArchiveDependency',
    ...     dependency=debian['main_archive_link']).jsonBody()

Archives will also give us a list of their custom dependencies.

    >>> print_self_link_of_entries(
    ...     webservice.get('/~cprov/+archive/ppa/dependencies').jsonBody())
    http://.../~cprov/+archive/ppa/+dependency/1

Crafting a URL to a non-dependency 404s:

    >>> print webservice.get(
    ...     '/~cprov/+archive/ppa/+dependency/2')
    HTTP/1.1 404 Not Found
    ...

A 404 also occurs if we ask for an archive that doesn't exist.

    >>> print webservice.get(
    ...     '/~cprov/+archive/ppa/+dependency/123456')
    HTTP/1.1 404 Not Found
    ...

And even if we ask for a non-integral archive ID.

    >>> print webservice.get(
    ...     '/~cprov/+archive/ppa/+dependency/foo')
    HTTP/1.1 404 Not Found
    ...