Metadata-Version: 1.1
Name: buildout.dumppickedversions2
Version: 1.0.3
Summary: Dump buildout 2 picked versions.
Home-page: https://github.com/eightmedia/buildout.dumppickedversions2
Author: Jaap Roes
Author-email: jaap@eight.nl
License: MIT
Description: 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
            zc.buildout = 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
            zc.buildout = 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
            zc.buildout = 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]
            theiregg = N.N
            zc.buildout = 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]
            theiregg = N.N
            zc.buildout = 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.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
        
Keywords: buildout extension dump picked versions
Platform: UNKNOWN
Classifier: Framework :: Buildout
Classifier: Intended Audience :: Developers
