Metadata-Version: 1.0
Name: d2to1
Version: 0.2.1
Summary: Allows using distutils2-like setup.cfg files for a package's metadata
with a distribute/setuptools setup.py
Home-page: http://pypi.python.org/pypi/d2to1
Author: Erik M. Bray
Author-email: embray@stsci.edu
License: BSD
Description: Introduction
        ==============
        d2to1 (the 'd' is for 'distutils') allows using distutils2-like setup.cfg files
        for a package's metadata with a distribute/setuptools setup.py script.  It
        works by providing a distutils2-formatted setup.cfg file containing all of a
        package's metadata, and a very minimal setup.py which will slurp its arguments
        from the setup.cfg.
        
        Note: distutils2 has been merged into the CPython standard library, where it is
        now known as 'packaging'.  This project was started before that change was
        finalized.  So all references to distutils2 should also be assumed to refer to
        packaging.
        
        Rationale
        ===========
        I'm currently in the progress of redoing the packaging of a sizeable number of
        projects.  I wanted to use distutils2-like setup.cfg files for all these
        projects, as they will hopefully be the future, and I much prefer them overall
        to using an executable setup.py.  So forward-support for distutils2 is
        appealing both as future-proofing, and simply the aesthetics of using a flat text file to describe a project's metadata.
        
        However, I did not want any of these projects to require distutils2 for
        installation yet--it is too unstable, and not widely installed.  So projects
        should still be installable using the familiar `./setup.py install`, for
        example.  Furthermore, not all use cases required by some of the packages I
        support are fully supported by distutils2 yet.  Hopefully they will be
        eventually, either through the distutils2 core or through extensions.  But in
        the meantime d2to1 will try to keep up with the state of the art and "best
        practices" for distutils2 distributions, while adding support in areas that
        it's lacking.
        
        Usage
        =======
        d2to1 requires a distribution to use distribute or setuptools.  Your
        distribution must include a distutils2-like setup.cfg file, and a minimal
        setup.py script.  For details on writing the setup.cfg, see the `distutils2
        documentation`_.  A simple sample can be found in d2to1's own setup.cfg (it
        uses its own machinery to install itself)::
        
        [metadata]
        name = d2to1
        version = 0.1.1
        author = Erik M. Bray
        author-email = embray at stsci.edu
        summary = Allows using distutils2-like setup.cfg files for a package's metadata
        with a distribute/setuptools setup.py
        description-file = README
        license = BSD
        requires-dist = setuptools
        classifier =
        Development Status :: 4 - Beta
        Environment :: Plugins
        Framework :: Setuptools Plugin
        Intended Audience :: Developers
        License :: OSI Approved :: BSD License
        Operating System :: OS Independent
        Programming Language :: Python
        Topic :: Software Development :: Build Tools
        Topic :: Software Development :: Libraries :: Python Modules
        Topic :: System :: Archiving :: Packaging
        
        [files]
        packages = d2to1
        
        The minimal setup.py should look something like this::
        
        #!/usr/bin/env python
        
        try:
        from setuptools import setup
        except ImportError:
        from distribute_setup import use_setuptools
        use_setuptools()
        from setuptools import setup
        
        setup(
        setup_requires=['d2to1'],
        d2to1=True
        )
        
        Note that it's important to specify d2to1=True or else the d2to1 functionality
        will not be enabled.  It is also possible to set d2to1='some_file.cfg' to
        specify the (relative) path of the setup.cfg file to use.  But in general this
        functionality should not be necessary.
        
        It should also work fine if additional arguments are passed to `setup()`,
        but it should be noted that they will be clobbered by any options in the
        setup.cfg file.
        
        Caveats
        =========
        - The requires-dist option in setup.cfg is implemented through the
        distribute/setuptools install_requires option, rather than the broken
        "requires" keyword in normal distutils.
        - Not all features of distutils2 are supported yet.  If something doesn't seem
        to be working, it's probably not implemented yet.
        - Does not support distutils2 resources, and probably won't since it relies
        heavily on the sysconfig module only available in Python 3.2 and up.  This is
        one area in which d2to1 should really be seen as a transitional tool.  I
        don't really want to include a backport like distutils2 does.  In the
        meantime, package_data and data_files may still be used under the [files]
        section of setup.cfg.
        
        .. _distutils2 documentation: http://distutils2.notmyidea.org/setupcfg.html
        
        Changes
        =========
        
        0.2.1 (2011-06-15)
        ------------------
        
        - Reimplemented command hooks without monkey-patching and more reliably in
        general (though it's still a flaming hack).  The previous monkey patch-based
        solution would break if d2to1 were entered multiple times, which could happen
        in some scenarios
        
        
        0.2.0 (2011-06-14)
        ------------------
        
        - Version bump to start using micro-version numbers for bug fixes only, now
        that the my primary feature goals are complete
        
        
        0.1.5 (2011-06-02)
        ------------------
        
        - Adds support for the data_files option under [files].  Though this is
        considered deprecated and may go away at some point, it can be useful in the
        absence of resources support
        - Adds support for command pre/post-hooks.  Warning: this monkey-patches
        distutils.dist.Distribution a little bit... :(
        - Adds (slightly naive) support for PEP 345-style version specifiers in
        requires-dist (environment markers not supported yet)
        - Fixed a bug where not enough newlines were inserted between description files
        
        
        0.1.4 (2011-05-24)
        ------------------
        
        - Adds support for custom command classes specified in the 'commands' option
        under the [global] section in setup.cfg
        - Adds preliminary support for custom compilers specified in the 'compilers'
        option under the [global] section in setup.cfg.  This functionality doesn't
        exist in distutils/setuptools/distribute, so adding support for it is a
        flaming hack.  It hasn't really been tested beyond seeing that the custom
        compilers come up in `setup.py build_ext --help-compiler`, so any real-world
        testing of this feature would be appreciated
        
        
        0.1.3 (2011-04-20)
        ------------------
        
        - Adds zest.releaser entry points for updating the version number in a
        setup.cfg file; only useful if you use zest.releaser--otherwise harmless
        (might eventually move this functionality out into a separate product)
        - Though version 0.1.2 worked in Python3, use_2to3 wasn't added to the setup.py
        so 2to3 had to be run manually
        - Fixed a crash on projects that don't have a description-file option
        
        0.1.2 (2011-04-13)
        ------------------
        
        - Fixed the self-installation--it did not work if a d2to1 version was not
        already installed, due to the use of `pkg_resources.require()`
        - Adds nominal Python3 support
        - Fixes the 'classifier' option in setup.cfg
        
        0.1.1 (2011-04-12)
        ------------------
        
        - Fixed an unhelpful error message when a setup_hook fails to import
        - Made d2to1 able to use its own machinery to install itself
        
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Plugins
Classifier: Framework :: Setuptools Plugin
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Archiving :: Packaging
