buildout.dumppickedversions2 1.1
Dump buildout 2 picked versions.
License: MIT
Keywords: buildout extension dump picked versions

buildout.dumppickedversions2
============================

``buildout.dumppickedversions2`` is a simple buildout extension
that mimicks the features of ``buildout.dumppickedversions`` for
buildout version 2.0.1 or later.

The problem and it's solution
-----------------------------

After upgrading buildout to version 2 you'll notice that use of
``buildout.dumppickedversions`` has been disabled. This has been
done because part of the features of ``buildout.dumppickedversions``
have been integrated into buildout.

However the overwriting behavior of ``buildout.dumppickedversions``
has not been integrated. This extension monkey patches the built-in 
version dumping so it behaves more like ``buildout.dumppickedversions``.

An added benefit is that the configuration options haven't been
changed. This means that upgrading you buildout file is a simple 
addition of the number two to ``extensions = buildout.dumppickedversions``.

``buildout.dumppickedversions2`` requires zc.buildout 2.0.1 or later.

buildout.dumppickedversions2 options
------------------------------------

dump-picked-versions-file
    A file name you want ``buildout.dumppickedversions`` to write to.
    If not given ``buildout.dumppickedversions`` will dump the versions to the 
    screen. The latter behavior is now built into buildout and can be enabled
    without an extension by setting ``show-picked-versions`` to ``true``.

overwrite-picked-versions-file
    If set to ``true``, ``buildout.dumppickedversions`` will overwrite the file 
    defined in ``dump-picked-versions-file`` if it exists. This value
    defaults to True.

Detailed Documentation
======================
Let's create an egg to use it in our tests::

    >>> mkdir('myegg')
    >>> write('myegg', 'setup.py',
    ... '''
    ... from distutils.core import setup
    ... setup(name='myegg', version='1.0')
    ... ''')
    >>> write('myegg', 'README', '')
    >>> print system(buildout + ' setup myegg bdist_egg')
    Running setup script 'myegg/setup.py'.
    ...

Create a buildout and use buildout.dumppickedversions2::

    >>> write('buildout.cfg',
    ... '''
    ... [buildout]
    ... extensions = buildout.dumppickedversions2
    ... parts = myegg
    ... find-links = https://pypi.python.org/simple/zc.recipe.egg/
    ...              %s
    ... [myegg]
    ... recipe = zc.recipe.egg
    ... eggs = myegg
    ... ''' % join('myegg', 'dist'))

Running the buildout will print information about picked versions::

    >>> print system(join('bin', 'buildout'))
    Develop distribution: buildout.dumppickedversions2 N.N
    ...
    Versions had to be automatically picked.
    The following part definition lists the versions picked:
    [versions]
    myegg = N.N
    setuptools = N.N
    zc.recipe.egg = N.N
    ...

To dump picked versions to a file, we just add an ``dump-picked-versions-file`` 
option and give a file name::
    
    >>> write('buildout.cfg',
    ... '''
    ... [buildout]
    ... extensions = buildout.dumppickedversions2
    ... dump-picked-versions-file = versions.cfg
    ... parts = myegg
    ... find-links = https://pypi.python.org/simple/zc.recipe.egg/
    ...              %s
    ... [myegg]
    ... recipe = zc.recipe.egg
    ... eggs = myegg 
    ... ''' % join('myegg', 'dist'))
    
    >>> print system(buildout)
    Develop distribution: buildout.dumppickedversions2 N.N
    ...
    Updating myegg.
    Picked versions have been written to versions.cfg
    ...

And here is the content of the file versions.cfg::
    
    >>> cat('versions.cfg')
    [versions]
    myegg = N.N
    setuptools = N.N
    zc.recipe.egg = N.N

Next time we run the buildout the file will be overwritten::

    >>> print system(buildout)
    Develop distribution: buildout.dumppickedversions2 N.N
    ...
    Picked versions have been written to versions.cfg
    ...

    >>> cat('versions.cfg')
    [versions]
    myegg = N.N
    setuptools = N.N
    zc.recipe.egg = N.N

Let's create a new egg to use it in our tests, it will require
another egg::

    >>> mkdir('theiregg')
    >>> write('theiregg', 'setup.py',
    ... '''
    ... from distutils.core import setup
    ... setup(name='theiregg', version='1.0', install_requires='myegg')
    ... ''')
    >>> write('theiregg', 'README', '')
    >>> print system(buildout + ' setup theiregg bdist_egg')
    Running setup script 'theiregg/setup.py'.
    ...

Create a buildout that uses this new egg::

    >>> write('buildout.cfg',
    ... '''
    ... [buildout]
    ... extensions = buildout.dumppickedversions2
    ... parts = theiregg
    ... find-links = https://pypi.python.org/simple/zc.recipe.egg/
    ...              %s
    ...              %s
    ... [theiregg]
    ... recipe = zc.recipe.egg
    ... eggs = theiregg
    ... ''' % (join('theiregg', 'dist'), join('myegg', 'dist')))

Running the buildout will print information about picked versions
and who required them::

    >>> print system(join('bin', 'buildout'))
    Develop distribution: buildout.dumppickedversions2 N.N
    ...
    Versions had to be automatically picked.
    The following part definition lists the versions picked:
    [versions]
    setuptools = N.N
    theiregg = N.N
    zc.recipe.egg = N.N
    <BLANKLINE>
    # Required by:
    # theiregg==N.N
    myegg = N.N
    ...

This also works when writing to a file::

    >>> write('buildout.cfg',
    ... '''
    ... [buildout]
    ... extensions = buildout.dumppickedversions2
    ... dump-picked-versions-file = versions.cfg
    ... parts = theiregg
    ... find-links = https://pypi.python.org/simple/zc.recipe.egg/
    ...              %s
    ...              %s
    ... [theiregg]
    ... recipe = zc.recipe.egg
    ... eggs = theiregg
    ... ''' % (join('theiregg', 'dist'), join('myegg', 'dist')))

    >>> print system(buildout)
    Develop distribution: buildout.dumppickedversions2 N.N
    ...
    Updating theiregg.
    Picked versions have been written to versions.cfg
    ...

And here is the content of the file versions.cfg::
    
    >>> cat('versions.cfg')
    [versions]
    setuptools = N.N
    theiregg = N.N
    zc.recipe.egg = N.N
    <BLANKLINE>
    # Required by:
    # theiregg==N.N
    myegg = N.N

When we don't want to overwrite the file we just add an 
``overwrite-picked-versions-file`` and set it to false::

    >>> write('buildout.cfg',
    ... '''
    ... [buildout]
    ... extensions = buildout.dumppickedversions2
    ... dump-picked-versions-file = versions.cfg
    ... overwrite-picked-versions-file = false
    ... parts = myegg
    ... find-links = https://pypi.python.org/simple/zc.recipe.egg/
    ...              %s
    ... [myegg]
    ... recipe = zc.recipe.egg
    ... eggs = myegg 
    ... ''' % join('myegg', 'dist'))
    
    >>> print system(buildout)
    Develop distribution: buildout.dumppickedversions2 N.N
    ...
    Skipped: File versions.cfg already exists.
    ...

1.1 (2013-06-14)
----------------

- Uses the new pickedversions plugin API when it becomes available


1.0.3 (2013-02-26)
------------------

- Now includes "required by" data


1.0.2 (2013-02-22)
------------------

- Explicitly require buildout 2.0.1


1.0.1 (2013-02-19)
------------------

- Fixed an issue with the namespace


1.0 (2013-02-19)
----------------

- Initial version

Author
======

- Jaap Roes

Thanks
======

- Mustapha Benali, Original author of buildout.dumppickedversions