← Back to branch summary

~launchpad-pqm/launchpad/devel

« back to all changes in this revision

Viewing changes to lib/lp/soyuz/doc/archive.txt

  • Committer: Launchpad Patch Queue Manager
  • Date: 2011-01-04 17:29:42 UTC
  • mfrom: (12156.1.4 bug-693357)
  • Revision ID: launchpad@pqm.canonical.com-20110104172942-9yf0831n1y4mn27b
[r=jcsackett, sinzui][ui=none][bug=693357] Remove has_existing_ppa and
        has_ppa_with_published_packages from IPerson and change
        IArchiveSet.getPPAOwnedByPerson to perform the same tasks.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/lp/soyuz/doc/archive.txt
1
 
= Personal Package Archives =
 
1
Personal Package Archives
 
2
=========================
2
3
 
3
4
An Archive models a Debian Archive, providing operations like
4
5
publication lookups and the complete publishing-pipeline from database
120
121
    ...
121
122
    Unauthorized: (..., 'buildd_secret', 'launchpad.Commercial')
122
123
 
123
 
Commercial Member, a commercial admin but not an admin, can set 'buildd_secret'.
 
124
Commercial Member, a commercial admin but not an admin, can set
 
125
'buildd_secret'.
124
126
 
125
127
    >>> login("commercial-member@canonical.com")
126
128
    >>> cprov_private_ppa.buildd_secret = 'not so secret at all'
282
284
    False
283
285
 
284
286
 
285
 
== Published Source and Binary Lookup ==
 
287
Published Source and Binary Lookup
 
288
----------------------------------
286
289
 
287
290
IArchive implements a published source & binary lookup methods,
288
291
returning I{Source, Binary}PackagePublishingHistory objects.
444
447
    3
445
448
 
446
449
 
447
 
=== Binary publication lookups ===
 
450
Binary publication lookups
 
451
--------------------------
448
452
 
449
453
'getPublishedOnDiskBinaries' returns only unique publications, i.e., it
450
454
excludes architecture-independent duplications which is necessary for
674
678
    >>> status_lookup.count()
675
679
    2
676
680
 
677
 
== getBuildCounters ==
 
681
getBuildCounters
 
682
----------------
678
683
 
679
684
IArchive.getBuildCounters() allows callsites to quickly present
680
685
the number of builds in a pre-defined status for a given IArchive.
714
719
    total 17
715
720
 
716
721
 
717
 
== getBuildSummariesForSourceIds() ==
 
722
getBuildSummariesForSourceIds()
 
723
-------------------------------
718
724
 
719
725
IArchive.getBuildSummariesForSourceIds() allows callsites to get an update
720
726
on the build statuses for a set of source publishing record ids. This
760
766
     - i386 build of foobar 1.0 in ubuntu warty RELEASE
761
767
 
762
768
 
763
 
== No public access to IArchiveView methods ==
 
769
No public access to IArchiveView methods
 
770
----------------------------------------
764
771
 
765
772
Both the getBuildCounters() and getBuildSummariesForSourceIds() methods are
766
773
not publically available, but available only to users who have permission to
826
833
    Unauthorized: (..., 'getBuildSummariesForSourceIds', 'launchpad.View')
827
834
 
828
835
 
829
 
== Package Counters ==
 
836
Package Counters
 
837
----------------
830
838
 
831
839
IArchive provides properties to calculate the number and the size of
832
840
the packages (sources and binaries) currently published in the
883
891
Now we will emulate a duplicated reference to the same 'orig.tar.gz',
884
892
upstream tarball, as if it was part of two different SourcePackageRelease.
885
893
 
886
 
    >>> from canonical.launchpad.interfaces.librarian import ILibraryFileAliasSet
 
894
    >>> from canonical.launchpad.interfaces.librarian import (
 
895
    ...     ILibraryFileAliasSet,
 
896
    ...     )
887
897
    >>> huge_firefox_orig_file = getUtility(ILibraryFileAliasSet)[3]
888
898
    >>> cprov_cdrkit_src = cprov_archive.getPublishedSources(
889
899
    ...     name='cdrkit')[0]
933
943
    2
934
944
 
935
945
 
936
 
== Getting an Archive's source-package releases ==
 
946
Getting an Archive's source-package releases
 
947
--------------------------------------------
937
948
 
938
949
The method getSourcePackageReleases() is provided to return the unique
939
950
source-package releases for the archive. By default, all releases will
952
963
For further details see the `TestGetSourcePackageReleases` unit-test.
953
964
 
954
965
 
955
 
== Sources available for deletions ==
 
966
Sources available for deletions
 
967
-------------------------------
956
968
 
957
969
'getSourcesForDeletion' is the base for '+delete-packages' page on PPA
958
970
context it allows us to lookup for `ISourcePackagePublishingHistory`
1031
1043
    >>> flush_database_caches()
1032
1044
 
1033
1045
 
1034
 
== Build Lookup ==
 
1046
Build Lookup
 
1047
------------
1035
1048
 
1036
1049
It also implements a build lookup method, which supports, 'name',
1037
1050
'status' and 'pocket'.
1087
1100
    1
1088
1101
 
1089
1102
 
1090
 
== Archive dependencies ==
 
1103
Archive dependencies
 
1104
--------------------
1091
1105
 
1092
1106
An Archive can depend on one or more other archives, such
1093
1107
relationships affects mainly its builds, which will be querying build
1282
1296
    ...
1283
1297
    AssertionError: This dependency does not exist.
1284
1298
 
1285
 
== Creating a package copy request from an IArchive ==
 
1299
Creating a package copy request from an IArchive
 
1300
------------------------------------------------
1286
1301
 
1287
1302
The IArchive interface includes a convenience method for creating a
1288
1303
package copy request:
1318
1333
    status: NEW
1319
1334
    ...
1320
1335
 
1321
 
== IArchiveSet Utility ==
 
1336
IArchiveSet Utility
 
1337
-------------------
1322
1338
 
1323
1339
This utility provides useful methods to deal with IArchive in other
1324
1340
parts of the system.
1351
1367
An archive is also associated with a distribution.  This can be found on
1352
1368
the distribution property.  The default distribution is "ubuntu":
1353
1369
 
1354
 
     >>> sandbox_archive.distribution.name
1355
 
     u'ubuntu'
 
1370
    >>> sandbox_archive.distribution.name
 
1371
    u'ubuntu'
1356
1372
 
1357
1373
An Archive can be retrieved via IPerson.archive property:
1358
1374
 
1628
1644
    >>> jblack_ppas.count()
1629
1645
    0
1630
1646
 
1631
 
Another similar method, getPPAOwnedByPersonUser(), will return the named PPA
1632
 
owned by the person, or if the person is not supplied will default to the
 
1647
Another similar method, getPPAOwnedByPerson(), will return the named PPA
 
1648
owned by the person, or if a name is not supplied will default to the
1633
1649
first PPA that the person created.
1634
1650
 
1635
 
    >>> print archive_set.getPPAOwnedByPerson(cprov).displayname
1636
 
    PPA for Celso Providelo
1637
 
 
1638
 
    >>> print archive_set.getPPAOwnedByPerson(cprov, name="ppa").displayname
1639
 
    PPA for Celso Providelo
 
1651
    >>> ppa_owner = factory.makePerson(
 
1652
    ...     name="ppa-owner", displayname="PPA Owner")
 
1653
    >>> login_person(ppa_owner)
 
1654
 
 
1655
If no PPAs match the search criteria, and a name is not given, then
 
1656
None is returned.
 
1657
 
 
1658
    >>> print archive_set.getPPAOwnedByPerson(ppa_owner)
 
1659
    None
 
1660
 
 
1661
    >>> zoobuntu = factory.makeDistribution(name='zoobuntu')
 
1662
    >>> ppa1 = factory.makeArchive(
 
1663
    ...     owner=ppa_owner, name="first-ppa", distribution=zoobuntu)
 
1664
    >>> ppa2 = factory.makeArchive(
 
1665
    ...     owner=ppa_owner, name="second-ppa", distribution=zoobuntu)
 
1666
 
 
1667
    >>> print archive_set.getPPAOwnedByPerson(ppa_owner).displayname
 
1668
    PPA named first-ppa for PPA Owner
 
1669
 
 
1670
    >>> print archive_set.getPPAOwnedByPerson(
 
1671
    ...     ppa_owner, name="second-ppa").displayname
 
1672
    PPA named second-ppa for PPA Owner
1640
1673
 
1641
1674
If the named PPA does not exist, a NoSuchPPA exception is raised.
1642
1675
 
1643
 
    >>> print archive_set.getPPAOwnedByPerson(cprov, name="goat").displayname
 
1676
    >>> print archive_set.getPPAOwnedByPerson(
 
1677
    ...     ppa_owner, name="goat").displayname
1644
1678
    Traceback (most recent call last):
1645
1679
    ...
1646
1680
    NoSuchPPA: No such ppa: 'goat'.
1647
1681
 
 
1682
A list of statuses may be optionally used, which cause the search to
 
1683
only select PPAs with one of those statuses.  The first PPA will not
 
1684
be selected and the second is returned.
 
1685
 
 
1686
    >>> ppa1.status = ArchiveStatus.DELETED
 
1687
    >>> ppa2.status = ArchiveStatus.ACTIVE
 
1688
    >>> print archive_set.getPPAOwnedByPerson(
 
1689
    ...     ppa_owner, statuses=[ArchiveStatus.ACTIVE]).displayname
 
1690
    PPA named second-ppa for PPA Owner
 
1691
 
 
1692
The parameter has_packages can be specified to filter based on whether
 
1693
the PPA has published packages.
 
1694
 
 
1695
    >>> spph = factory.makeSourcePackagePublishingHistory(
 
1696
    ...     archive=ppa2, status=PackagePublishingStatus.PUBLISHED)
 
1697
    >>> print archive_set.getPPAOwnedByPerson(
 
1698
    ...     ppa_owner, has_packages=True).displayname
 
1699
    PPA named second-ppa for PPA Owner
 
1700
 
1648
1701
The method getPrivatePPAs() will return a result set of all PPAs that are
1649
1702
private.
1650
1703
 
1856
1909
    total      1
1857
1910
 
1858
1911
 
1859
 
== A general way to get specific archives for a distribution ==
 
1912
A general way to get specific archives for a distribution
 
1913
---------------------------------------------------------
1860
1914
 
1861
1915
IArchiveSet also includes the helper method `getArchivesForDistribution`
1862
1916
which can be used to get archives of a specific purpose(s) for a distribution
1999
2053
    true-copy        copy-owner2   False    False
2000
2054
    ultimate-copy    copy-owner1   False    True
2001
2055
 
2002
 
If exclude_disabled is set to True no disabled archives will be 
 
2056
If exclude_disabled is set to True no disabled archives will be
2003
2057
included:
2004
2058
 
2005
2059
    >>> foobar = getUtility(IPersonSet).getByName('name16')
2025
2079
    team-archive     t1            True     True
2026
2080
    ultimate-copy    copy-owner1   False    True
2027
2081
 
2028
 
A separate argument allows forcing the inclusion of all disabled archives 
2029
 
the user has access to, so it doesn't include the archive 
 
2082
A separate argument allows forcing the inclusion of all disabled archives
 
2083
the user has access to, so it doesn't include the archive
2030
2084
of juergen that is disabled.
2031
2085
 
2032
2086
    >>> ubuntu_copy_archives = archive_set.getArchivesForDistribution(
2039
2093
    ultimate-copy    copy-owner1   False    True
2040
2094
 
2041
2095
 
2042
 
== Getting publishing records across a set of Archives ==
 
2096
Getting publishing records across a set of Archives
 
2097
---------------------------------------------------
2043
2098
 
2044
2099
The IArchiveSet utility provides a getPublicationsInArchives() method
2045
2100
that can be used to find the current publishing records for a source
2056
2111
    ...         pub.archive.displayname)
2057
2112
    mozilla-firefox - 0.9 in Primary Archive for Ubuntu Linux
2058
2113
 
2059
 
== Archive Permission Checking ==
 
2114
Archive Permission Checking
 
2115
---------------------------
2060
2116
 
2061
 
IArchive has two public methods, checkArchivePermission() and canAdministerQueue()
2062
 
that check a user's permission to upload and/or administer a
2063
 
distroseries upload queue respectively.  See archivepermission.txt
2064
 
for more details.
 
2117
IArchive has two public methods, checkArchivePermission() and
 
2118
canAdministerQueue() that check a user's permission to upload and/or
 
2119
administer a distroseries upload queue respectively.  See
 
2120
archivepermission.txt for more details.
2065
2121
 
2066
2122
    >>> ubuntu_team = getUtility(IPersonSet).getByName('ubuntu-team')
2067
2123
    >>> carlos = getUtility(IPersonSet).getByName('carlos')
2072
2128
    >>> ubuntu.main_archive.canAdministerQueue(carlos, main_component)
2073
2129
    False
2074
2130
 
2075
 
    >>> ubuntu.main_archive.checkArchivePermission(ubuntu_team, main_component)
 
2131
    >>> ubuntu.main_archive.checkArchivePermission(
 
2132
    ...     ubuntu_team, main_component)
2076
2133
    True
2077
2134
 
2078
2135
    >>> ubuntu.main_archive.canAdministerQueue(ubuntu_team, main_component)
2079
2136
    True
2080
2137
 
2081
 
checkArchivePermission() can also check someone's permission to upload a specific
2082
 
source package.  Carlos, who does not have permission to upload to any
2083
 
Ubuntu components, has permission to upload "mozilla-firefox".
 
2138
checkArchivePermission() can also check someone's permission to upload
 
2139
a specific source package.  Carlos, who does not have permission to
 
2140
upload to any Ubuntu components, has permission to upload
 
2141
"mozilla-firefox".
2084
2142
 
2085
 
    >>> from lp.registry.interfaces.sourcepackagename import ISourcePackageNameSet
 
2143
    >>> from lp.registry.interfaces.sourcepackagename import (
 
2144
    ...     ISourcePackageNameSet,
 
2145
    ...     )
2086
2146
    >>> mozilla = getUtility(
2087
2147
    ...     ISourcePackageNameSet).queryByName("mozilla-firefox")
2088
2148
    >>> ubuntu.main_archive.checkArchivePermission(carlos, mozilla)
2093
2153
    >>> ubuntu.main_archive.checkArchivePermission(cprov, mozilla)
2094
2154
    False
2095
2155
 
2096
 
checkArchivePermission() also works in the same way for PPAs.  By default, it allows
2097
 
anyone in the PPA owning team to upload.
 
2156
checkArchivePermission() also works in the same way for PPAs.  By
 
2157
default, it allows anyone in the PPA owning team to upload.
2098
2158
 
2099
2159
    >>> cprov_archive.checkArchivePermission(cprov)
2100
2160
    True
2245
2305
    True
2246
2306
 
2247
2307
 
2248
 
== Rebuild archives ==
 
2308
Rebuild archives
 
2309
----------------
2249
2310
 
2250
2311
For further information about how ArchiveRebuild works see
2251
2312
archive-rebuilds.txt. Here we will just document why the creation and
2316
2377
    test-rebuild-one
2317
2378
 
2318
2379
 
2319
 
== Synchronising sources from other archives ==
 
2380
Synchronising sources from other archives
 
2381
-----------------------------------------
2320
2382
 
2321
2383
IArchive.syncSources is a convenience wrapper around the copying code
2322
2384
in lp.soyuz.scripts.packagecopier.  It allows the caller to
2523
2585
    python
2524
2586
 
2525
2587
 
2526
 
== Publish flag ==
 
2588
Publish flag
 
2589
------------
2527
2590
 
2528
2591
Every archive has a "publish" flag that governs whether it should be
2529
2592
published or not. Upon creation that flag is false for copy archives but
2562
2625
    False
2563
2626
 
2564
2627
 
2565
 
== The name uniqueness constraints for archives ==
 
2628
The name uniqueness constraints for archives
 
2629
--------------------------------------------
2566
2630
 
2567
2631
The names of archives other than PPAs must be unique for a given
2568
2632
distribution. Trying to create an archive with the same name and
2642
2706
    distribution.
2643
2707
 
2644
2708
 
2645
 
== Looking up named PPAs ==
 
2709
Looking up named PPAs
 
2710
---------------------
2646
2711
 
2647
2712
Additionally to the locked 'archive' property, `IPerson` also offers
2648
2713
`ppas` property and `getPPAByName` method.
2674
2739
    NoSuchPPA: No such ppa: 'not-found'.
2675
2740
 
2676
2741
 
2677
 
== Editable displayname ==
 
2742
Editable displayname
 
2743
--------------------
2678
2744
 
2679
2745
If 'displayname' is omitted on archive created, a default form is
2680
2746
automatically used.
2706
2772
    >>> new_ppa.displayname = 'My testing packages for jaunty'
2707
2773
 
2708
2774
 
2709
 
== Signing-key propagation ==
 
2775
Signing-key propagation
 
2776
-----------------------
2710
2777
 
2711
2778
Signing keys are, by default, shared between PPAs owned by the same
2712
2779
user/team.
2751
2818
    True
2752
2819
 
2753
2820
 
2754
 
== Download counts ==
 
2821
Download counts
 
2822
---------------
2755
2823
 
2756
2824
Counts of downloads per binary package release, day and country are kept
2757
2825
up to date by a log-processing script. Archives have a method to get the