Egg Recipe API for other Recipes

================================

It is common for recipes to accept a collection of egg specifications

and generate scripts based on the resulting working sets.  The egg

recipe provides an API that other recipes can use.

A recipe can reuse the egg recipe, supporting the eggs, find-links,

index, extra-paths, and python options.  This is done by creating an

egg recipe instance in a recipes's contructor.  In the recipe's

install script, the egg-recipe instance's working_set method is used

to collect the requested eggs and working set.

To illustrate, we create a sample recipe that is a very thin layer

around the egg recipe:

    >>> mkdir(sample_buildout, 'sample')

    >>> write(sample_buildout, 'sample', 'sample.py',

    ... """

    ... import logging, os

    ... import zc.recipe.egg

    ...

    ... class Sample:

    ...

    ...     def __init__(self, buildout, name, options):

    ...         self.egg = zc.recipe.egg.Scripts(buildout, name, options)

    ...         self.name = name

    ...         self.options = options

    ...

    ...     def install(self):

    ...         extras = self.options['extras'].split()

    ...         requirements, ws = self.egg.working_set(extras)

    ...         print 'Part:', self.name

    ...         print 'Egg requirements:'

    ...         for r in requirements:

    ...             print r

    ...         print 'Working set:'

    ...         for d in ws:

    ...             print d

    ...         print 'extra paths:', self.egg.extra_paths

    ...         return ()

    ...

    ...     update = install

    ... """)

Here we instantiated the egg recipe in the constructor, saving it in

an attribute.  This also initialized the options dictionary.

In our install method, we called the working_set method on the

instance we saved.  The working_set method takes an optional sequence

of extra requirements to be included in the working set.

    >>> write(sample_buildout, 'sample', 'setup.py',

    ... """

    ... from setuptools import setup

    ...

    ... setup(

    ...     name = "sample",

    ...     entry_points = {'zc.buildout': ['default = sample:Sample']},

    ...     install_requires = 'zc.recipe.egg',

    ...     )

    ... """)

    >>> write(sample_buildout, 'sample', 'README.txt', " ")

    >>> write(sample_buildout, 'buildout.cfg',

    ... """

    ... [buildout]

    ... develop = sample

    ... parts = sample-part

    ...

    ... [sample-part]

    ... recipe = sample

    ... eggs = demo<0.3

    ... find-links = %(server)s

    ... index = %(server)sindex

    ... extras = other

    ... """ % dict(server=link_server))

    >>> import os

    >>> os.chdir(sample_buildout)

    >>> buildout = os.path.join(sample_buildout, 'bin', 'buildout')

    >>> print system(buildout + ' -q'),

    Part: sample-part

    Egg requirements:

    demo<0.3

    Working set:

    demo 0.2

    other 1.0

    demoneeded 1.2c1

    extra paths: []

We can see that the options were augmented with additional data

computed by the egg recipe by looking at .installed.cfg:

    >>> cat(sample_buildout, '.installed.cfg')

    ... # doctest: +NORMALIZE_WHITESPACE

    [buildout]

    installed_develop_eggs = /sample-buildout/develop-eggs/sample.egg-link

    parts = sample-part

    <BLANKLINE>

    [sample-part]

    __buildout_installed__ =

    __buildout_signature__ = sample-6aWMvV2EJ9Ijq+bR8ugArQ==

            zc.recipe.egg-cAsnudgkduAa/Fd+WJIM6Q==

            setuptools-0.6-py2.4.egg

            zc.buildout-+rYeCcmFuD1K/aB77XTj5A==

    _b = /sample-buildout/bin

    _d = /sample-buildout/develop-eggs

    _e = /sample-buildout/eggs

    bin-directory = /sample-buildout/bin

    develop-eggs-directory = /sample-buildout/develop-eggs

    eggs = demo<0.3

    eggs-directory = /sample-buildout/eggs

    executable = /usr/local/bin/python2.3

    extras = other

    find-links = http://localhost:27071/

    index = http://localhost:27071/index

    python = buildout

    recipe = sample

If we use the extra-paths option:

    >>> write(sample_buildout, 'buildout.cfg',

    ... """

    ... [buildout]

    ... develop = sample

    ... parts = sample-part

    ...

    ... [sample-part]

    ... recipe = sample

    ... eggs = demo<0.3

    ... find-links = %(server)s

    ... index = %(server)sindex

    ... extras = other

    ... extra-paths = /foo/bar

    ...               /spam/eggs

    ... """ % dict(server=link_server))

Then we'll see that reflected in the extra_paths attribute in the egg

recipe instance:

    >>> print system(buildout + ' -q'),

    Part: sample-part

    Egg requirements:

    demo<0.3

    Working set:

    demo 0.2

    other 1.0

    demoneeded 1.2c1

    extra paths: ['/foo/bar', '/spam/eggs']