Merge lp:~allenap/launchpad/dd-initseries-bug-727105-derivation-vocab into lp:launchpad

[Gavin Panella]

This branch adds a named vocabulary ("DistroSeriesDerivation") that
contains the set of distroseries that the context distroseries or
distribution can derive from.

It also fixes adapters for IProductSeries -> IProduct and
IDistroSeries -> IDistribution. The code already exists in the tree
but was not registered or tested.

Support for dir() has also been added to LaunchpadObjectFactory to
help out interactive shenanigans.

This branch will not be committed; it is part of a larger change.

[Aaron Bentley (abentley)]

I don't know why you want to adapt a ProductSeries to a Product or a DistroSeries to a Distribution. It seems weird to me. I don't find any explanation of that in your cover letter. It would be helpful if you used our standard review template-- I'd expect to find this in the "implementation details" section.

With the adapters you've registered, wouldn't IDistribution.providedBy(distro_series) return True? If so, I think the tests are not testing whether the distroseries has been converted to a distribution. Instead of IDistribution.providedBy(distribution), you could do assertEqual(distribution, distro_series.distribution).

I think the comment on LaunchpadObjectFactory.__dir__ is too narrow. While it is helpful to interactive users, it can be used in other ways.

I thought distroseries were generally ordered by version or codename. Why is DistroSeriesDerivationVocabularyFactory using creation date instead?

Getting a list of distroseries by doing set(distribution) is also pretty wacky. I would have expected set(distribution) to fail, because distributions don't seem like they should be iterable.

review: Needs Information

[Gavin Panella (allenap)]

Hi Aaron,

Thanks for looking at this. In answering your questions below I
discovered a situation I had not tested. I've remedied that, and also
managed to make the code a bit tighter, requiring fewer queries. It
seems I wasn't thinking very well while coding this branch.

> I don't know why you want to adapt a ProductSeries to a Product or a
> DistroSeries to a Distribution. It seems weird to me. I don't find any
> explanation of that in your cover letter. It would be helpful if you used our
> standard review template-- I'd expect to find this in the "implementation
> details" section.

It's a convenient way of getting a IDistribution context from anything
that wants to register for it. Having said that, I think this
vocabulary is only ever needed in an IDistroSeries context, so I
/could/ remove the adaption in the vocabulary and thus the adapters.

Also, note I didn't actually write the adapters; the code already
existed and I just registered it. Not sure what it was doing there to
be honest, but it suited my needs (and I did productseries_to_product
for completeness).

Something that factors into my reasoning is my (mild) dislike of:

    if IOneInterface.providedBy(an_argument):
        do_something()
    elif IOtherInterface.providedBy(an_argument):
        do_something_else()
    ...

when we have a component system all ready and running, although I do
admit that it can be expedient to just do things this way.

> With the adapters you've registered, wouldn't
> IDistribution.providedBy(distro_series) return True? If so, I think the tests
> are not testing whether the distroseries has been converted to a distribution.
> Instead of IDistribution.providedBy(distribution), you could do
> assertEqual(distribution, distro_series.distribution).

IDistribution.providedBy(distro_series) is not true. At least, it
shouldn't be if I understand correctly!

I've added the tests you suggest, but maybe I'll end up killing the
adapters altogether.

> I think the comment on LaunchpadObjectFactory.__dir__ is too narrow. While it
> is helpful to interactive users, it can be used in other ways.

I've changed it to:

        """Enumerate the attributes and methods of the wrapped object factory.

        This is especially useful for interactive users."""

Is that the kind of thing you were thinking of?

> I thought distroseries were generally ordered by version or codename. Why is
> DistroSeriesDerivationVocabularyFactory using creation date instead?

I've ordered it the same as DistroSeriesVocabulary, which seems to be
used quite widely.

> Getting a list of distroseries by doing set(distribution) is also pretty
> wacky. I would have expected set(distribution) to fail, because distributions
> don't seem like they should be iterable.

Yeah, it does read a bit oddly. I'm not the author (I think...) of
Distribution.__iter__() so I can't say why that was decided. I've
spent far too long on this branch as it is to revisit that decision,
so do you mind if I leave it as it is?

[Aaron Bentley (abentley)]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 11-03-11 12:57 PM, Gavin Panella wrote:
>> I don't know why you want to adapt a ProductSeries to a Product or a
>> DistroSeries to a Distribution. It seems weird to me. I don't find any
>> explanation of that in your cover letter. It would be helpful if you used our
>> standard review template-- I'd expect to find this in the "implementation
>> details" section.
>
> It's a convenient way of getting a IDistribution context from anything
> that wants to register for it.

That's a definition of an adapter, but it doesn't explain the motivation
for providing this adaptation.

> Having said that, I think this
> vocabulary is only ever needed in an IDistroSeries context, so I
> /could/ remove the adaption in the vocabulary and thus the adapters.

That would seem like a more straightforward way of doing things.

> Also, note I didn't actually write the adapters; the code already
> existed and I just registered it.

Instead of going "We haven't used it" and deleting it? :-)

> Not sure what it was doing there to
> be honest, but it suited my needs (and I did productseries_to_product
> for completeness).
>
> Something that factors into my reasoning is my (mild) dislike of:
>
> if IOneInterface.providedBy(an_argument):
> do_something()
> elif IOtherInterface.providedBy(an_argument):
> do_something_else()

I share that dislike, but I don't see how that applies to this context.

This is a situation where you're passing in objects of the wrong type
and adapting them to objects of the correct type. Why not just pass in
objects of the correct type?

> IDistribution.providedBy(distro_series) is not true. At least, it
> shouldn't be if I understand correctly!

I have checked, by downloading your branch and tweaking the test, and
you're right, it doesn't.

> I've changed it to:
>
> """Enumerate the attributes and methods of the wrapped object factory.
>
> This is especially useful for interactive users."""
>
> Is that the kind of thing you were thinking of?

Sure, that's good.

>> Getting a list of distroseries by doing set(distribution) is also pretty
>> wacky. I would have expected set(distribution) to fail, because distributions
>> don't seem like they should be iterable.
>
> Yeah, it does read a bit oddly. I'm not the author (I think...) of
> Distribution.__iter__() so I can't say why that was decided.

Distribution.__iter__ is implemented in terms of Distribution.series, so
I recommend using that instead.

> I've
> spent far too long on this branch as it is to revisit that decision,
> so do you mind if I leave it as it is?

I think switching your client code to use Distribution.series is a very
small hardship, so I'd prefer if you changed it. I didn't mean that you
should remove Distribution.__iter__.

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk16d5IACgkQ0F+nu1YWqI2rXACfX367xjl2QOscPS0Iv+8DKaFU
sBkAnAzeL6esmFNZd/FxI1VqO3rAp9c6
=PCpH
-----END PGP SIGNATURE-----

[Gavin Panella (allenap)]

> > It's a convenient way of getting a IDistribution context from anything
> > that wants to register for it.
>
> That's a definition of an adapter, but it doesn't explain the motivation
> for providing this adaptation.

I don't see the harm in doing it, but that's perhaps because I've not
really experienced a situation where this kind of thing has led to
problems later on.

>
> > Having said that, I think this vocabulary is only ever needed in
> > an IDistroSeries context, so I /could/ remove the adaption in the
> > vocabulary and thus the adapters.
>
> That would seem like a more straightforward way of doing things.

All the vocabulary needs is a distribution to function, yet it will
currently only be used in a distroseries context. It seems strange to
require a distroseries when I could just say "give me anything that
can be adapted to a distribution".

Anyway, I've made it work only for distroseries now.

>
> > Also, note I didn't actually write the adapters; the code already
> > existed and I just registered it.
>
> Instead of going "We haven't used it" and deleting it? :-)

I was wrong; that code is actually used as the basis for other
adapters.

>
> > Not sure what it was doing there to
> > be honest, but it suited my needs (and I did productseries_to_product
> > for completeness).
> >
> > Something that factors into my reasoning is my (mild) dislike of:
> >
> > if IOneInterface.providedBy(an_argument):
> > do_something()
> > elif IOtherInterface.providedBy(an_argument):
> > do_something_else()
>
> I share that dislike, but I don't see how that applies to this context.

If I don't use adapters but want to keep the ability to work in a
distribution or distroseries context I can't really see a way around
the IFoo.providedBy(...) stuff.

Well, I could getattr(context, "distribution", context) but I suspect that
might an order of magnitude worse again :)

>
> This is a situation where you're passing in objects of the wrong type
> and adapting them to objects of the correct type. Why not just pass in
> objects of the correct type?

Because it's a named vocabulary. You get the context in which it is
used. I don't think there is an opportunity to select what gets
passed.

> Distribution.__iter__ is implemented in terms of Distribution.series, so
> I recommend using that instead.

Done.

Thanks again!

[Robert Collins (lifeless)]

On Tue, Mar 15, 2011 at 4:12 AM, Gavin Panella
<email address hidden> wrote:
>> >     if IOneInterface.providedBy(an_argument):
>> >         do_something()
>> >     elif IOtherInterface.providedBy(an_argument):
>> >         do_something_else()
>>
>> I share that dislike, but I don't see how that applies to this context.
>
> If I don't use adapters but want to keep the ability to work in a
> distribution or distroseries context I can't really see a way around
> the IFoo.providedBy(...) stuff.
>
> Well, I could getattr(context, "distribution", context) but I suspect that
> might an order of magnitude worse again :)

There are a few general patterns that can be used here:
 - delegation:
   an_argument.do_something() -> trust it will dtrt.
   an_argument can have a range of techniques to have do_something
implemented appropropriately.
 - multiple dispatch: register (in advance) how you want to dispatch
things, and then dispatch off a tuple of types rather than just the
type of an_argument:
   do_something(an_argument, self) -> will handle the type consideration for you
 - adaption - a primitive form of multiple dispatch - cast or acquire
into a known type and then call a method on it:
 IPillar(an_argument).do_something
 - case statements: the thing we all dislike :)

adaption makes me nervous unless there is /clearly/ and /forevermore/
One Sensible Answer : and distroseries -> distribution violates the
second condition: for a derived distribution, there are multiple
reasonable answers to 'I need a distribution for this distroseries' -
there is .distribution, and there is .parent_series.distribution.

Generally speaking, I reach for delegation as the first tool to hand
in these sorts of situations, though it may not be the right tool for
this specific situation.

HTH,
Rob

[Gavin Panella (allenap)]

> adaption makes me nervous unless there is /clearly/ and
> /forevermore/ One Sensible Answer

I like this rule; I'll try and keep it in mind. Thanks.

[Aaron Bentley (abentley)]

Sorry for the delay. I thought Graham had approved it, but that was something else.

I like the change as far as it goes, but it seems you've retained the adaptation even though now it's no longer needed by your vocabulary. If that was an oversight, consider this approved. Otherwise, I'd like to understand why.

[Gavin Panella (allenap)]

The adaption has gone, but I left in a couple of trivial-ish tests for distroseries_to_distribution() and productseries_to_product(). That code no longer has anything else to do with this branch, but they are still valid tests of code that isn't otherwise tested directly.

[Aaron Bentley (abentley)]

review: Approve

=== modified file 'lib/lp/registry/adapters.py'
--- lib/lp/registry/adapters.py	2011-01-04 16:08:57 +0000
+++ lib/lp/registry/adapters.py	2011-03-30 16:10:58 +0000
@@ -6,8 +6,7 @@
 __metaclass__ = type
 
 __all__ = [
-    'distroseries_to_launchpadusage',
-    'distroseries_to_serviceusage',
+    'distroseries_to_distribution',
     'PollSubset',
     'productseries_to_product',
     ]

=== added file 'lib/lp/registry/tests/test_adapters.py'
--- lib/lp/registry/tests/test_adapters.py	1970-01-01 00:00:00 +0000
+++ lib/lp/registry/tests/test_adapters.py	2011-03-30 16:10:58 +0000
@@ -0,0 +1,36 @@
+# Copyright 2011 Canonical Ltd.  This software is licensed under the
+# GNU Affero General Public License version 3 (see the file LICENSE).
+
+"""Tests for adapters."""
+
+__metaclass__ = type
+
+from canonical.testing.layers import DatabaseFunctionalLayer
+from lp.registry.adapters import (
+    distroseries_to_distribution,
+    productseries_to_product,
+    )
+from lp.registry.interfaces.distribution import IDistribution
+from lp.registry.interfaces.product import IProduct
+from lp.testing import TestCaseWithFactory
+
+
+class TestAdapters(TestCaseWithFactory):
+
+    layer = DatabaseFunctionalLayer
+
+    def test_distroseries_to_distribution(self):
+        # distroseries_to_distribution() returns an IDistribution given an
+        # IDistroSeries.
+        distro_series = self.factory.makeDistroSeries()
+        distribution = distroseries_to_distribution(distro_series)
+        self.assertTrue(IDistribution.providedBy(distribution))
+        self.assertEqual(distribution, distro_series.distribution)
+
+    def test_productseries_to_product(self):
+        # productseries_to_product() returns an IProduct given an
+        # IProductSeries.
+        product_series = self.factory.makeProductSeries()
+        product = productseries_to_product(product_series)
+        self.assertTrue(IProduct.providedBy(product))
+        self.assertEqual(product, product_series.product)

=== added file 'lib/lp/registry/tests/test_distroseries_vocabularies.py'
--- lib/lp/registry/tests/test_distroseries_vocabularies.py	1970-01-01 00:00:00 +0000
+++ lib/lp/registry/tests/test_distroseries_vocabularies.py	2011-03-30 16:10:58 +0000
@@ -0,0 +1,183 @@
+# Copyright 2011 Canonical Ltd.  This software is licensed under the
+# GNU Affero General Public License version 3 (see the file LICENSE).
+
+"""Tests for distroseries vocabularies in `lp.registry.vocabularies`."""
+
+__metaclass__ = type
+
+from datetime import (
+    datetime,
+    timedelta,
+    )
+
+from pytz import utc
+from testtools.matchers import Equals
+from zope.component import getUtility
+from zope.schema.interfaces import (
+    IVocabulary,
+    IVocabularyFactory,
+    IVocabularyTokenized,
+    )
+from zope.security.proxy import removeSecurityProxy
+
+from canonical.database.sqlbase import flush_database_caches
+from canonical.testing.layers import DatabaseFunctionalLayer
+from lp.registry.interfaces.distroseries import IDistroSeriesSet
+from lp.registry.vocabularies import DistroSeriesDerivationVocabularyFactory
+from lp.testing import (
+    StormStatementRecorder,
+    TestCaseWithFactory,
+    )
+from lp.testing.matchers import HasQueryCount
+
+
+class TestDistroSeriesDerivationVocabularyFactory(TestCaseWithFactory):
+    """Tests for `DistroSeriesDerivationVocabularyFactory`."""
+
+    layer = DatabaseFunctionalLayer
+
+    def setUp(self):
+        super(TestDistroSeriesDerivationVocabularyFactory, self).setUp()
+        self.vocabulary_factory = DistroSeriesDerivationVocabularyFactory
+        self.all_distroseries = getUtility(IDistroSeriesSet).search()
+
+    def test_registration(self):
+        # DistroSeriesDerivationVocabularyFactory is registered as a named
+        # utility for IVocabularyFactory.
+        self.assertEqual(
+            getUtility(IVocabularyFactory, name="DistroSeriesDerivation"),
+            DistroSeriesDerivationVocabularyFactory)
+
+    def test_interfaces(self):
+        # DistroSeriesDerivationVocabularyFactory instances provide
+        # IVocabulary and IVocabularyTokenized.
+        distroseries = self.factory.makeDistroSeries()
+        vocabulary = self.vocabulary_factory(distroseries)
+        self.assertProvides(vocabulary, IVocabulary)
+        self.assertProvides(vocabulary, IVocabularyTokenized)
+
+    def test_distribution_with_non_derived_series(self):
+        # Given a distribution with series, none of which are derived, the
+        # vocabulary factory returns a vocabulary for all distroseries in all
+        # distributions *except* the given distribution.
+        distroseries = self.factory.makeDistroSeries()
+        vocabulary = self.vocabulary_factory(distroseries)
+        expected_distroseries = (
+            set(self.all_distroseries).difference(
+                distroseries.distribution.series))
+        observed_distroseries = set(term.value for term in vocabulary)
+        self.assertEqual(expected_distroseries, observed_distroseries)
+
+    def test_distribution_with_derived_series(self):
+        # Given a distribution with series, one or more of which are derived,
+        # the vocabulary factory returns a vocabulary for all distroseries of
+        # the distribution from which the derived series have been derived.
+        parent_distroseries = self.factory.makeDistroSeries()
+        # Create a sibling to the parent.
+        self.factory.makeDistroSeries(
+            distribution=parent_distroseries.distribution)
+        distroseries = self.factory.makeDistroSeries(
+            parent_series=parent_distroseries)
+        vocabulary = self.vocabulary_factory(distroseries)
+        expected_distroseries = set(parent_distroseries.distribution.series)
+        observed_distroseries = set(term.value for term in vocabulary)
+        self.assertEqual(expected_distroseries, observed_distroseries)
+
+    def test_distribution_with_derived_series_of_self(self):
+        # Given a distribution with series derived from other of its series
+        # (which shouldn't happen), the vocabulary factory returns a
+        # vocabulary for all distroseries in all distributions *except* the
+        # given distribution.
+        parent_distroseries = self.factory.makeDistroSeries()
+        distroseries = self.factory.makeDistroSeries(
+            distribution=parent_distroseries.distribution,
+            parent_series=parent_distroseries)
+        vocabulary = self.vocabulary_factory(distroseries)
+        expected_distroseries = (
+            set(self.all_distroseries).difference(
+                distroseries.distribution.series))
+        observed_distroseries = set(term.value for term in vocabulary)
+        self.assertEqual(expected_distroseries, observed_distroseries)
+
+    def test_distroseries(self):
+        # Given a distroseries, the vocabulary factory returns the vocabulary
+        # the same as for its distribution.
+        distroseries = self.factory.makeDistroSeries()
+        vocabulary = self.vocabulary_factory(distroseries)
+        expected_distroseries = (
+            set(self.all_distroseries).difference(
+                distroseries.distribution.series))
+        observed_distroseries = set(term.value for term in vocabulary)
+        self.assertEqual(expected_distroseries, observed_distroseries)
+
+    def test_ordering(self):
+        # The vocabulary is sorted by distribution display name then by the
+        # date the distroseries was created, newest first.
+        now = datetime.now(utc)
+        two_days_ago = now - timedelta(2)
+        six_days_ago = now - timedelta(7)
+
+        aaa = self.factory.makeDistribution(displayname="aaa")
+        aaa_series_older = self.factory.makeDistroSeries(
+            name="aaa-series-older", distribution=aaa)
+        removeSecurityProxy(aaa_series_older).date_created = six_days_ago
+        aaa_series_newer = self.factory.makeDistroSeries(
+            name="aaa-series-newer", distribution=aaa)
+        removeSecurityProxy(aaa_series_newer).date_created = two_days_ago
+
+        bbb = self.factory.makeDistribution(displayname="bbb")
+        bbb_series_older = self.factory.makeDistroSeries(
+            name="bbb-series-older", distribution=bbb)
+        removeSecurityProxy(bbb_series_older).date_created = six_days_ago
+        bbb_series_newer = self.factory.makeDistroSeries(
+            name="bbb-series-newer", distribution=bbb)
+        removeSecurityProxy(bbb_series_newer).date_created = two_days_ago
+
+        ccc = self.factory.makeDistribution(displayname="ccc")
+        ccc_series = self.factory.makeDistroSeries(distribution=ccc)
+
+        vocabulary = self.vocabulary_factory(ccc_series)
+        expected_distroseries = [
+            aaa_series_newer, aaa_series_older,
+            bbb_series_newer, bbb_series_older]
+        observed_distroseries = list(term.value for term in vocabulary)
+        # observed_distroseries will contain distroseries from the sample
+        # data, so we must only look at the set of distroseries we have
+        # created.
+        observed_distroseries = [
+            series for series in observed_distroseries
+            if series in expected_distroseries]
+        self.assertEqual(expected_distroseries, observed_distroseries)
+
+    def test_queries_for_distribution_with_non_derived_series(self):
+        for index in range(10):
+            self.factory.makeDistroSeries()
+        distribution = self.factory.makeDistribution()
+        distroseries = self.factory.makeDistroSeries(
+            distribution=distribution)
+        flush_database_caches()
+        # Reload distroseries and distribution; these will reasonably already
+        # be loaded before using the vocabulary.
+        distroseries.distribution
+        # Getting terms issues two queries: one to search for parent serieses
+        # (of which there are none) and a second for all serieses.
+        with StormStatementRecorder() as recorder:
+            self.vocabulary_factory(distroseries).terms
+            self.assertThat(recorder, HasQueryCount(Equals(2)))
+
+    def test_queries_for_distribution_with_derived_series(self):
+        for index in range(10):
+            self.factory.makeDistroSeries()
+        distribution = self.factory.makeDistribution()
+        parent_distroseries = self.factory.makeDistroSeries()
+        distroseries = self.factory.makeDistroSeries(
+            parent_series=parent_distroseries,
+            distribution=distribution)
+        flush_database_caches()
+        # Reload distroseries and distribution; these will reasonably already
+        # be loaded before using the vocabulary.
+        distroseries.distribution
+        # Getting terms issues one query to find parent serieses.
+        with StormStatementRecorder() as recorder:
+            self.vocabulary_factory(distroseries).terms
+            self.assertThat(recorder, HasQueryCount(Equals(1)))

=== modified file 'lib/lp/registry/vocabularies.py'
--- lib/lp/registry/vocabularies.py	2011-03-07 02:32:57 +0000
+++ lib/lp/registry/vocabularies.py	2011-03-30 16:10:58 +0000
@@ -31,6 +31,7 @@
     'DistributionOrProductOrProjectGroupVocabulary',
     'DistributionOrProductVocabulary',
     'DistributionVocabulary',
+    'DistroSeriesDerivationVocabularyFactory',
     'DistroSeriesVocabulary',
     'FeaturedProjectVocabulary',
     'FilteredDistroSeriesVocabulary',
@@ -38,23 +39,23 @@
     'KarmaCategoryVocabulary',
     'MilestoneVocabulary',
     'NonMergedPeopleAndTeamsVocabulary',
+    'person_team_participations_vocabulary_factory',
     'PersonAccountToMergeVocabulary',
     'PersonActiveMembershipVocabulary',
     'ProductReleaseVocabulary',
     'ProductSeriesVocabulary',
     'ProductVocabulary',
+    'project_products_vocabulary_factory',
     'ProjectGroupVocabulary',
     'SourcePackageNameVocabulary',
+    'UserTeamsParticipationPlusSelfVocabulary',
     'UserTeamsParticipationVocabulary',
-    'UserTeamsParticipationPlusSelfVocabulary',
     'ValidPersonOrClosedTeamVocabulary',
     'ValidPersonOrTeamVocabulary',
     'ValidPersonVocabulary',
     'ValidTeamMemberVocabulary',
     'ValidTeamOwnerVocabulary',
     'ValidTeamVocabulary',
-    'person_team_participations_vocabulary_factory',
-    'project_products_vocabulary_factory',
     ]
 
 
@@ -73,11 +74,16 @@
     LeftJoin,
     Not,
     Or,
+    Select,
     SQL,
     )
+from storm.info import ClassAlias
 from zope.component import getUtility
 from zope.interface import implements
-from zope.schema.interfaces import IVocabularyTokenized
+from zope.schema.interfaces import (
+    IVocabulary,
+    IVocabularyTokenized,
+    )
 from zope.schema.vocabulary import (
     SimpleTerm,
     SimpleVocabulary,
@@ -1432,7 +1438,8 @@
         for series in sorted(series, key=attrgetter('sortkey')):
             yield self.toTerm(series)
 
-    def toTerm(self, obj):
+    @staticmethod
+    def toTerm(obj):
         """See `IVocabulary`."""
         # NB: We use '/' as the separator because '-' is valid in
         # a distribution.name
@@ -1474,6 +1481,114 @@
         return objs
 
 
+class DistroSeriesDerivationVocabularyFactory:
+    """A vocabulary source for series to derive from.
+
+    Once a distribution has a series that has derived from a series in another
+    distribution, all other derived series must also derive from a series in
+    the same distribution.
+
+    A distribution can have non-derived series. Any of these can be changed to
+    derived at a later date, but as soon as this happens, the above rule
+    applies.
+
+    It is permissible for a distribution to have both derived and non-derived
+    series at the same time.
+    """
+
+    implements(IVocabulary, IVocabularyTokenized)
+
+    def __init__(self, context):
+        """See `IVocabularyFactory.__call__`."""
+        assert IDistroSeries.providedBy(context)
+        self.distribution = context.distribution
+
+    def find_terms(self, *where):
+        """Return a `tuple` of terms matching the given criteria.
+
+        The terms are returned in order. The `Distribution`s related to those
+        terms are preloaded at the same time.
+        """
+        query = IStore(DistroSeries).find(
+            (DistroSeries, Distribution),
+            DistroSeries.distribution == Distribution.id,
+            *where)
+        query = query.order_by(
+            Distribution.displayname,
+            Desc(DistroSeries.date_created))
+        return tuple(
+            DistroSeriesVocabulary.toTerm(series)
+            for (series, distribution) in query)
+
+    @cachedproperty
+    def terms(self):
+        """Terms for the series the context can derive from, in order.
+
+        The order is the same as for `DistroSeriesVocabulary`.
+        """
+        parent = ClassAlias(DistroSeries, "parent")
+        child = ClassAlias(DistroSeries, "child")
+        parent_distributions = Select(
+            parent.distributionID, And(
+                parent.distributionID != self.distribution.id,
+                child.distributionID == self.distribution.id,
+                child.parent_seriesID == parent.id))
+        terms = self.find_terms(
+            DistroSeries.distributionID.is_in(parent_distributions))
+        if len(terms) == 0:
+            terms = self.find_terms(
+                DistroSeries.distribution != self.distribution)
+        return terms
+
+    @cachedproperty
+    def terms_by_value(self):
+        """Mapping of terms by value."""
+        return dict((term.value, term) for term in self.terms)
+
+    @cachedproperty
+    def terms_by_token(self):
+        """Mapping of terms by token."""
+        return dict((term.token, term) for term in self.terms)
+
+    def __iter__(self):
+        """Returns an iterator over the terms in the vocabulary.
+
+        See `IIterableVocabulary`.
+        """
+        return iter(self.terms)
+
+    def __len__(self):
+        """The number of terms.
+
+        See `IIterableVocabulary`.
+        """
+        return len(self.terms)
+
+    def getTerm(self, value):
+        """Return the `ITerm` object for the term 'value'.
+
+        See `IBaseVocabulary`.
+        """
+        try:
+            return self.terms_by_value[value]
+        except KeyError:
+            raise LookupError(value)
+
+    def __contains__(self, value):
+        """Return whether the value is available in this source.
+
+        See `ISource`.
+        """
+        return (value in self.terms_by_value)
+
+    def getTermByToken(self, token):
+        """See `IVocabularyTokenized`."""
+        try:
+            return self.terms_by_token[token]
+        except KeyError:
+            raise LookupError(token)
+
+
 class PillarVocabularyBase(NamedSQLObjectHugeVocabulary):
     """Active `IPillar` objects vocabulary."""
     displayname = 'Needs to be overridden'

=== modified file 'lib/lp/registry/vocabularies.zcml'
--- lib/lp/registry/vocabularies.zcml	2010-11-30 22:55:58 +0000
+++ lib/lp/registry/vocabularies.zcml	2011-03-30 16:10:58 +0000
@@ -30,6 +30,18 @@
 
 
   <securedutility
+      name="DistroSeriesDerivation"
+      component=".vocabularies.DistroSeriesDerivationVocabularyFactory"
+      provides="zope.schema.interfaces.IVocabularyFactory">
+    <allow interface="zope.schema.interfaces.IVocabularyFactory"/>
+  </securedutility>
+
+  <class class=".vocabularies.DistroSeriesDerivationVocabularyFactory">
+    <allow interface="zope.schema.interfaces.IVocabularyTokenized"/>
+  </class>
+
+
+  <securedutility
     name="FeaturedProject"
     component="lp.registry.vocabularies.FeaturedProjectVocabulary"
     provides="zope.schema.interfaces.IVocabularyFactory"

=== modified file 'lib/lp/testing/factory.py'
--- lib/lp/testing/factory.py	2011-03-28 20:54:50 +0000
+++ lib/lp/testing/factory.py	2011-03-30 16:10:58 +0000
@@ -36,19 +36,19 @@
     isSequenceType,
     )
 import os
-from pytz import UTC
 from random import randint
 from StringIO import StringIO
 from textwrap import dedent
 from threading import local
-import transaction
 from types import InstanceType
 import warnings
 
 from bzrlib.merge_directive import MergeDirective2
 from bzrlib.plugins.builder.recipe import BaseRecipeBranch
 import pytz
+from pytz import UTC
 import simplejson
+import transaction
 from twisted.python.util import mergeFunctionMetadata
 from zope.component import (
     ComponentLookupError,
@@ -279,10 +279,8 @@
     time_counter,
     )
 from lp.translations.enums import RosettaImportStatus
-from lp.translations.interfaces.side import (
-    TranslationSide,
-    )
 from lp.translations.interfaces.potemplate import IPOTemplateSet
+from lp.translations.interfaces.side import TranslationSide
 from lp.translations.interfaces.translationfileformat import (
     TranslationFileFormat,
     )
@@ -3992,6 +3990,12 @@
         else:
             return attr
 
+    def __dir__(self):
+        """Enumerate the attributes and methods of the wrapped object factory.
+
+        This is especially useful for interactive users."""
+        return dir(self._factory)
+
 
 def remove_security_proxy_and_shout_at_engineer(obj):
     """Remove an object's security proxy and print a warning.

=== modified file 'lib/lp/testing/tests/test_factory.py'
--- lib/lp/testing/tests/test_factory.py	2010-12-02 16:13:51 +0000
+++ lib/lp/testing/tests/test_factory.py	2011-03-30 16:10:58 +0000
@@ -611,6 +611,14 @@
             sequence='2000-1234', cvestate=CveStatus.DEPRECATED)
         self.assertEqual(CveStatus.DEPRECATED, cve.status)
 
+    # dir() support.
+    def test_dir(self):
+        # LaunchpadObjectFactory supports dir() even though all of its
+        # attributes are pseudo-attributes.
+        self.assertEqual(
+            dir(self.factory._factory),
+            dir(self.factory))
+
 
 class TestFactoryWithLibrarian(TestCaseWithFactory):