~launchpad-pqm/launchpad/devel

== Launchpad pillars ==

A few of the PillarsOfLaunchpad (tm) share a namespace to allow their name
to unambiguously refer to it. This allows us to make email interfaces
easier to use and to shorten some of our URLs. Currently, the objects that
share their name namespace are Product, ProjectGroup and Distribution.

    >>> from lp.registry.interfaces.distribution import IDistribution
    >>> from lp.registry.interfaces.pillar import IPillarNameSet
    >>> from lp.registry.interfaces.product import IProduct
    >>> from lp.registry.interfaces.projectgroup import IProjectGroup
    >>> pillar_set = getUtility(IPillarNameSet)

    >>> 'ubuntu' in pillar_set
    True
    >>> pillar_set['ubuntu'].name
    u'ubuntu'
    >>> IDistribution.providedBy(pillar_set['ubuntu'])
    True

    >>> 'tomcat' in pillar_set
    True
    >>> pillar_set['tomcat'].name
    u'tomcat'
    >>> IProduct.providedBy(pillar_set['tomcat'])
    True

    >>> 'apache' in pillar_set
    True
    >>> pillar_set['apache'].name
    u'apache'
    >>> IProjectGroup.providedBy(pillar_set['apache'])
    True

    >>> 'fnord' in pillar_set
    False
    >>> pillar_set['fnord']
    Traceback (most recent call last):
    ...
    NotFoundError: 'fnord'

Inactive products/projects are not available through PillarNameSet unless we
use the special getByName() method which returns active/inactive pillars..

    >>> 'gimp' in pillar_set
    True
    >>> IProjectGroup.providedBy(pillar_set['gimp'])
    True
    >>> login('mark@example.com')
    >>> pillar_set['gimp'].active = False
    >>> 'gimp' in pillar_set
    False
    >>> pillar_set['gimp']
    Traceback (most recent call last):
    ...
    NotFoundError: 'gimp'
    >>> IProjectGroup.providedBy(pillar_set.getByName('gimp'))
    True

It also works if you use Unicode strings.

    >>> u'launchpad' in pillar_set
    True
    >>> IProduct.providedBy(pillar_set[u'launchpad'])
    True
    >>> pillar_set[u'launchpad'].active = False
    >>> u'launchpad' in pillar_set
    False
    >>> pillar_set[u'launchpad']
    Traceback (most recent call last):
    ...
    NotFoundError: u'launchpad'
    >>> IProduct.providedBy(pillar_set.getByName(u'launchpad'))
    True


== Pillar aliases ==

A pillar can have an arbitrary number of aliases, so that it can be found
under different names.

    >>> firefox = pillar_set['firefox']
    >>> firefox.aliases
    []

    >>> firefox.setAliases(['iceweasel', 'snowchicken'])
    >>> firefox.aliases
    [u'iceweasel', u'snowchicken']

Every time setAliases() is called it should be given the full set of aliases
for that pillar. If one of the pillar's existing aliases is not in the list
given to setAliases(), it is removed.

    >>> firefox.setAliases(['iceweasel'])
    >>> firefox.aliases
    [u'iceweasel']

Just like names, aliases are unique.

    >>> pillar_set['ubuntu'].setAliases(['iceweasel'])
    Traceback (most recent call last):
    ...
    AssertionError: This alias is already in use...

You can look up a given pillar through any of its aliases.

    >>> pillar_set['iceweasel'] == pillar_set['firefox']
    True

And our set of pillars will contain the aliases as well.

    >>> 'iceweasel' in pillar_set
    True

But only if the pillar which they point to is active.

    # Unlink the source packages so the project can be deactivated.
    >>> from lp.testing import unlink_source_packages
    >>> unlink_source_packages(firefox)
    >>> firefox.active = False
    >>> 'iceweasel' in pillar_set
    False

Also, if the pillar is inactive, it can't be retrieved through any of its
aliases, in the same way that it can't be retrieved through its name.

    >>> pillar_set['iceweasel']
    Traceback (most recent call last):
    ...
    NotFoundError:...
    >>> pillar_set['firefox']
    Traceback (most recent call last):
    ...
    NotFoundError:...

    # Make firefox active again, to not upset other tests.
    >>> firefox.active = True

Setting the aliases of a pillar is an operation that requires launchpad.Admin
rights on the pillar.

Sample Person has edit rights on firefox, but he'd need admin rights
to be able to set its aliases.

    >>> login('test@canonical.com')
    >>> from canonical.launchpad.webapp.authorization import check_permission
    >>> check_permission('launchpad.Edit', firefox)
    True
    >>> firefox.setAliases(['iceweasel'])
    Traceback (most recent call last):
    ...
    Unauthorized:...

Ditto for the Mozilla project.

    >>> mozilla = pillar_set['mozilla']
    >>> check_permission('launchpad.Edit', mozilla)
    True
    >>> mozilla.setAliases(['moz'])
    Traceback (most recent call last):
    ...
    Unauthorized:...

And the same is true for Colin Watson on the Guadalinex distribution.

    >>> login('colin.watson@ubuntulinux.com')
    >>> guadalinex = pillar_set['guadalinex']
    >>> check_permission('launchpad.Edit', guadalinex)
    True
    >>> guadalinex.setAliases(['guada'])
    Traceback (most recent call last):
    ...
    Unauthorized:...

    # Login as Mark again, to not upset remaining tests.
    >>> login('mark@example.com')


== Searching for Pillars ==

We can also use PillarNameSet to do a search across some of our pillars.
Right now this search is done across Products, ProjectGroups and
Distributions. Products are decorated with ProductWithLicenses to cache the
licenses that were retrieved in PillarSet.search() to reduce the number of
queries.

    >>> for row in pillar_set.search('mozilla', limit=3):
    ...     print ("%s: %s (%s)"
    ...            % (row.__class__.__name__, row.title, row.name))
    ProjectGroup: The Mozilla Project (mozilla)
    ProductWithLicenses: Mozilla Firefox (firefox)
    ProductWithLicenses: Mozilla Thunderbird (thunderbird)

    >>> for row in pillar_set.search('ubuntu', limit=5):
    ...     print ("%s: %s (%s)"
    ...            % (row.__class__.__name__, row.title, row.name))
    Distribution: Ubuntu Linux (ubuntu)
    Distribution: Ubuntu Test (ubuntutest)
    ProductWithLicenses: The Evolution Groupware Application (evolution)
    ProductWithLicenses: Tomcat (tomcat)
    ProductWithLicenses: The Gnome Panel Applets (applets)

We can search by any of the pillar's aliases too.

    >>> for row in pillar_set.search('iceweasel', limit=5):
    ...     print ("%s: %s (%s)"
    ...            % (row.__class__.__name__, row.title, row.name))
    ProductWithLicenses: Mozilla Firefox (firefox)

Note that inactive products and projects won't be included in the results.

    >>> pillar_set['firefox'].active = False
    >>> for row in pillar_set.search('mozilla', limit=3):
    ...     print ("%s: %s (%s)"
    ...            % (row.__class__.__name__, row.title, row.name))
    ProjectGroup: The Mozilla Project (mozilla)
    ProductWithLicenses: Mozilla Thunderbird (thunderbird)

    >>> pillar_set['applets'].active = False
    >>> for row in pillar_set.search('ubuntu', limit=5):
    ...     print ("%s: %s (%s)"
    ...            % (row.__class__.__name__, row.title, row.name))
    Distribution: Ubuntu Linux (ubuntu)
    Distribution: Ubuntu Test (ubuntutest)
    ProductWithLicenses: The Evolution Groupware Application (evolution)
    ProductWithLicenses: Tomcat (tomcat)
    Distribution: GuadaLinex: Linux for Andalucia (guadalinex)


== PillarName objects ==

PillarName objects have a pillar attribute that returns the object referenced
by that pillar name

    >>> from lp.registry.interfaces.distribution import IDistributionSet
    >>> from lp.registry.interfaces.projectgroup import IProjectGroupSet
    >>> from lp.registry.model.pillar import PillarName

    >>> ubuntu = getUtility(IDistributionSet).getByName('ubuntu')
    >>> gnome = getUtility(IProjectGroupSet).getByName('gnome')
    >>> ubuntu_pillarname = PillarName.selectOneBy(name='ubuntu')
    >>> ubuntu_pillarname.pillar == ubuntu
    True
    >>> gnome_pillarname = PillarName.selectOneBy(name='gnome')
    >>> gnome_pillarname.pillar == gnome
    True