The PEAK Developers' Center   Diff for "setuptools" UserPreferences
 
HelpContents Search Diffs Info Edit Subscribe XML Print View
Ignore changes in the amount of whitespace

Differences between version dated 2005-11-24 21:23:02 and 2009-10-20 10:09:23 (spanning 33 versions)

Deletions are marked like this.
Additions are marked like this.

ordinary Python packages based on the ``distutils``. Your users don't need to
install or even know about setuptools in order to use them, and you don't
have to include the entire setuptools package in your distributions. By
including just a single `bootstrap module`_ (a 7K .py file), your package will
including just a single `bootstrap module`_ (an 8K .py file), your package will
automatically download and install ``setuptools`` if the user is building your
package from source and doesn't have a suitable version already installed.
 

  the closest thing to CPAN currently available for Python.)
 
* Create `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_ -
  a single-file importable distribution format
  
  a single-file importable distribution format
 
* Include data files inside your package directories, where your code can
  actually use them. (Python 2.4 distutils also supports this feature, but
  setuptools provides the feature for Python 2.3 packages also, and supports

  extensions, using simple "entry points" declared in a project's setup script.
 
In addition to the PyPI downloads, the development version of ``setuptools``
is available from the `Python SVN sandbox`_.
is available from the `Python SVN sandbox`_, and in-development versions of the
`0.6 branch`_ are available as well.
 
.. _0.6 branch: http://svn.python.org/projects/sandbox/branches/setuptools-0.6/#egg=setuptools-dev06
 
.. _Python SVN sandbox: http://svn.python.org/projects/sandbox/trunk/setuptools/#egg=setuptools-dev
 
.. contents:: **Table of Contents**
 
.. _ez_setup.py: `bootstrap module`_
 
 
-----------------
Developer's Guide

Installing ``setuptools``
=========================
 
If you are behind an NTLM-based firewall that prevents Python programs from
accessing the net directly, you may wish to first install and use the `APS
proxy server <http://ntlmaps.sf.net/>`_, which lets you get past such firewalls
in the same way that your web browser(s) do.
 
If you do not have write access to your computer's ``site-packages`` directory,
please also see the EasyInstall documentation on `Non-Root Installation`_ for
more detailed instructions on pre-configuring your system for the best
usability with setuptools and EasyInstall, then return here for the remaining
steps.
 
.. _Non-Root Installation: http://peak.telecommunity.com/DevCenter/EasyInstall#non-root-installation
 
To install setuptools, first download `ez_setup.py`_ and run it; this will
automatically download and install the appropriate egg for your Python version.
(You will need at least Python 2.3.5, or if you are on a 64-bit platform,
Python 2.4.)
Please follow the `EasyInstall Installation Instructions`_ to install the
current stable version of setuptools. In particular, be sure to read the
section on `Custom Installation Locations`_ if you are installing anywhere
other than Python's ``site-packages`` directory.
 
.. _ez_setup.py: `bootstrap module`_
.. _EasyInstall Installation Instructions: http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions
 
You may receive a message telling you about an obsolete version of
setuptools being present; if so, you must be sure to delete it entirely, along
with the old ``pkg_resources`` module if it's present on ``sys.path``.
.. _Custom Installation Locations: http://peak.telecommunity.com/DevCenter/EasyInstall#custom-installation-locations
 
To get the in-development version of setuptools, first install a stable version
using the instructions above. Then run::
If you want the current in-development version of setuptools, you should first
install a stable version, and then run::
 
    ez_setup.py setuptools==dev
 
This will download and install the latest development (i.e. unstable) version
of setuptools from the Python Subversion sandbox.
 
(Note that ``setuptools`` *must* be installed as an egg directory; it will not
operate correctly otherwise. If you are unable to install to a valid
``site-packages`` directory (e.g. a "non-root install" that doesn't conform
to the `Non-Root Installation`_ procedure), you will therefore need to manually
add the setuptools egg to your ``PYTHONPATH``. You won't need to do this for
every egg you install, because the ``pkg_resources`` module can automatically
find eggs and add them to ``sys.path`` at runtime. It's just that the
``setuptools`` egg contains the ``pkg_resources`` runtime, and therefore has to
be manually bootstrapped if you can't install it to a valid ``site-packages``
directory. However, if you are installing as root or you followed the
`Non-Root Installation`_ procedure, you shouldn't have to worry about any of
this.)
 
 
Basic Use
=========

more information to your setup script to help people find or learn about your
project. And maybe your project will have grown by then to include a few
dependencies, and perhaps some data files and scripts::
        
 
    from setuptools import setup, find_packages
    setup(
        name = "HelloWorld",

them in your own project(s).
 
 
Specifying Your Project's Version
---------------------------------
 
Setuptools can work well with most versioning schemes; there are, however, a
few special things to watch out for, in order to ensure that setuptools and
EasyInstall can always tell what version of your package is newer than another
version. Knowing these things will also help you correctly specify what
versions of other projects your project depends on.
 
A version consists of an alternating series of release numbers and pre-release
or post-release tags. A release number is a series of digits punctuated by
dots, such as ``2.4`` or ``0.5``. Each series of digits is treated
numerically, so releases ``2.1`` and ``2.1.0`` are different ways to spell the
same release number, denoting the first subrelease of release 2. But ``2.10``
is the *tenth* subrelease of release 2, and so is a different and newer release
from ``2.1`` or ``2.1.0``. Leading zeros within a series of digits are also
ignored, so ``2.01`` is the same as ``2.1``, and different from ``2.0.1``.
 
Following a release number, you can have either a pre-release or post-release
tag. Pre-release tags make a version be considered *older* than the version
they are appended to. So, revision ``2.4`` is *newer* than revision ``2.4c1``,
which in turn is newer than ``2.4b1`` or ``2.4a1``. Postrelease tags make
a version be considered *newer* than the version they are appended to. So,
revisions like ``2.4-1`` and ``2.4pl3`` are newer than ``2.4``, but are *older*
than ``2.4.1`` (which has a higher release number).
 
A pre-release tag is a series of letters that are alphabetically before
"final". Some examples of prerelease tags would include ``alpha``, ``beta``,
``a``, ``c``, ``dev``, and so on. You do not have to place a dot before
the prerelease tag if it's immediately after a number, but it's okay to do
so if you prefer. Thus, ``2.4c1`` and ``2.4.c1`` both represent release
candidate 1 of version ``2.4``, and are treated as identical by setuptools.
 
In addition, there are three special prerelease tags that are treated as if
they were the letter ``c``: ``pre``, ``preview``, and ``rc``. So, version
``2.4rc1``, ``2.4pre1`` and ``2.4preview1`` are all the exact same version as
``2.4c1``, and are treated as identical by setuptools.
 
A post-release tag is either a series of letters that are alphabetically
greater than or equal to "final", or a dash (``-``). Post-release tags are
generally used to separate patch numbers, port numbers, build numbers, revision
numbers, or date stamps from the release number. For example, the version
``2.4-r1263`` might denote Subversion revision 1263 of a post-release patch of
version ``2.4``. Or you might use ``2.4-20051127`` to denote a date-stamped
post-release.
 
Notice that after each pre or post-release tag, you are free to place another
release number, followed again by more pre- or post-release tags. For example,
``0.6a9.dev-r41475`` could denote Subversion revision 41475 of the in-
development version of the ninth alpha of release 0.6. Notice that ``dev`` is
a pre-release tag, so this version is a *lower* version number than ``0.6a9``,
which would be the actual ninth alpha of release 0.6. But the ``-r41475`` is
a post-release tag, so this version is *newer* than ``0.6a9.dev``.
 
For the most part, setuptools' interpretation of version numbers is intuitive,
but here are a few tips that will keep you out of trouble in the corner cases:
 
* Don't use ``-`` or any other character than ``.`` as a separator, unless you
  really want a post-release. Remember that ``2.1-rc2`` means you've
  *already* released ``2.1``, whereas ``2.1rc2`` and ``2.1.c2`` are candidates
  you're putting out *before* ``2.1``. If you accidentally distribute copies
  of a post-release that you meant to be a pre-release, the only safe fix is to
  bump your main release number (e.g. to ``2.1.1``) and re-release the project.
 
* Don't stick adjoining pre-release tags together without a dot or number
  between them. Version ``1.9adev`` is the ``adev`` prerelease of ``1.9``,
  *not* a development pre-release of ``1.9a``. Use ``.dev`` instead, as in
  ``1.9a.dev``, or separate the prerelease tags with a number, as in
  ``1.9a0dev``. ``1.9a.dev``, ``1.9a0dev``, and even ``1.9.a.dev`` are
  identical versions from setuptools' point of view, so you can use whatever
  scheme you prefer.
 
* If you want to be certain that your chosen numbering scheme works the way
  you think it will, you can use the ``pkg_resources.parse_version()`` function
  to compare different version numbers::
 
    >>> from pkg_resources import parse_version
    >>> parse_version('1.9.a.dev') == parse_version('1.9a0dev')
    True
    >>> parse_version('2.1-rc2') < parse_version('2.1')
    False
    >>> parse_version('0.6a9dev-r41475') < parse_version('0.6a9')
    True
 
Once you've decided on a version numbering scheme for your project, you can
have setuptools automatically tag your in-development releases with various
pre- or post-release tags. See the following sections for more details:
 
* `Tagging and "Daily Build" or "Snapshot" Releases`_
* `Managing "Continuous Releases" Using Subversion`_
* The `egg_info`_ command
 
 
New and Changed ``setup()`` Keywords
====================================
 

``setuptools``. All of them are optional; you do not have to supply them
unless you need the associated ``setuptools`` feature.
 
``include_package_data``
    If set to ``True``, this tells ``setuptools`` to automatically include any
    data files it finds inside your package directories, that are either under
    CVS or Subversion control, or which are specified by your ``MANIFEST.in``
    file. For more information, see the section below on `Including Data
    Files`_.
 
``exclude_package_data``
    A dictionary mapping package names to lists of glob patterns that should
    be *excluded* from your package directories. You can use this to trim back
    any excess files included by ``include_package_data``. For a complete
    description and examples, see the section below on `Including Data Files`_.
 
``package_data``
    A dictionary mapping package names to lists of glob patterns. For a
    complete description and examples, see the section below on `Including
    Data Files`_.
    Data Files`_. You do not need to use this option if you are using
    ``include_package_data``, unless you need to add e.g. files that are
    generated by your setup script and build process. (And are therefore not
    in source control or are files that you don't want to include in your
    source distribution.)
 
``zip_safe``
    A boolean (True or False) flag specifying whether the project can be

    when the setup script is run, you should add them to ``install_requires``
    **and** ``setup_requires``.)
 
``dependency_links``
    A list of strings naming URLs to be searched when satisfying dependencies.
    These links will be used if needed to install packages specified by
    ``setup_requires`` or ``tests_require``. They will also be written into
    the egg's metadata for use by tools like EasyInstall to use when installing
    an ``.egg`` file.
 
``namespace_packages``
    A list of strings naming the project's "namespace packages". A namespace
    package is a package that may be split across multiple project

    for more information.
 
``test_suite``
    A string naming a ``unittest.TestCase`` subclass (or a module containing
    one or more of them, or a method of such a subclass), or naming a function
    that can be called with no arguments and returns a ``unittest.TestSuite``.
    A string naming a ``unittest.TestCase`` subclass (or a package or module
    containing one or more of them, or a method of such a subclass), or naming
    a function that can be called with no arguments and returns a
    ``unittest.TestSuite``. If the named suite is a module, and the module
    has an ``additional_tests()`` function, it is called and the results are
    added to the tests to be run. If the named suite is a package, any
    submodules and subpackages are recursively added to the overall test suite.
 
    Specifying this argument enables use of the `test`_ command to run the
    specified test suite, e.g. via ``setup.py test``. See the section on the
    `test`_ command below for more details.
 
``tests_require``
    If your project's tests need one or more additional packages besides those
    needed to install it, you can use this option to specify them. It should
    be a string or list of strings specifying what other distributions need to
    be present for the package's tests to run. When you run the ``test``
    command, ``setuptools`` will attempt to obtain these (even going
    so far as to download them using ``EasyInstall``). Note that these
    required projects will *not* be installed on the system where the tests
    are run, but only downloaded to the project's setup directory if they're
    not already installed locally.
 
.. _test_loader:
 
``test_loader``
    If you would like to use a different way of finding tests to run than what
    setuptools normally uses, you can specify a module name and class name in
    this argument. The named class must be instantiable with no arguments, and
    its instances must support the ``loadTestsFromNames()`` method as defined
    in the Python ``unittest`` module's ``TestLoader`` class. Setuptools will
    pass only one test "name" in the `names` argument: the value supplied for
    the ``test_suite`` argument. The loader you specify may interpret this
    string in any way it likes, as there are no restrictions on what may be
    contained in a ``test_suite`` string.
 
    The module name and class name must be separated by a ``:``. The default
    value of this argument is ``"setuptools.command.test:ScanningLoader"``. If
    you want to use the default ``unittest`` behavior, you can specify
    ``"unittest:TestLoader"`` as your ``test_loader`` argument instead. This
    will prevent automatic scanning of submodules and subpackages.
 
    The module and class you specify here may be contained in another package,
    as long as you use the ``tests_require`` option to ensure that the package
    containing the loader class is available when the ``test`` command is run.
 
``eager_resources``
    A list of strings naming resources that should be extracted together, if
    any of them is needed, or if any C extensions included in the project are

 
Anyway, ``find_packages()`` walks the target directory, and finds Python
packages by looking for ``__init__.py`` files. It then filters the list of
packages using the exclusion patterns.
packages using the exclusion patterns.
 
Exclusion patterns are package names, optionally including wildcards. For
example, ``find_packages(exclude=["*.tests"])`` will exclude all packages whose

Services and Plugins`_.
 
 
"Eggsecutable" Scripts
----------------------
 
Occasionally, there are situations where it's desirable to make an ``.egg``
file directly executable. You can do this by including an entry point such
as the following::
 
    setup(
        # other arguments here...
        entry_points = {
            'setuptools.installation': [
                'eggsecutable = my_package.some_module:main_func',
            ]
        }
    )
 
Any eggs built from the above setup script will include a short excecutable
prelude that imports and calls ``main_func()`` from ``my_package.some_module``.
The prelude can be run on Unix-like platforms (including Mac and Linux) by
invoking the egg with ``/bin/sh``, or by enabling execute permissions on the
``.egg`` file. For the executable prelude to run, the appropriate version of
Python must be available via the ``PATH`` environment variable, under its
"long" name. That is, if the egg is built for Python 2.3, there must be a
``python2.3`` executable present in a directory on ``PATH``.
 
This feature is primarily intended to support bootstrapping the installation of
setuptools itself on non-Windows platforms, but may also be useful for other
projects as well.
 
IMPORTANT NOTE: Eggs with an "eggsecutable" header cannot be renamed, or
invoked via symlinks. They *must* be invoked using their original filename, in
order to ensure that, once running, ``pkg_resources`` will know what project
and version is in use. The header script will check this and exit with an
error if the ``.egg`` file has been renamed or is invoked via a symlink that
changes its base name.
 
 
Declaring Dependencies
======================
 

separated by whitespace, but any whitespace or nonstandard characters within a
project name or version identifier must be replaced with ``-``.
 
Version specifiers for a given project are internally sorted into ascending
version order, and used to establish what ranges of versions are acceptable.
Adjacent redundant conditions are also consolidated (e.g. ``">1, >2"`` becomes
``">1"``, and ``"<2,<3"`` becomes ``"<3"``). ``"!="`` versions are excised from
the ranges they fall within. A project's version is then checked for
membership in the resulting ranges. (Note that providing conflicting conditions
for the same version (e.g. "<2,>=2" or "==2,!=2") is meaningless and may
therefore produce bizarre results.)
 
Here are some example requirement specifiers::
 
    docutils >= 0.3

using ``setup.py develop``.)
 
 
Dependencies that aren't in PyPI
--------------------------------
 
If your project depends on packages that aren't registered in PyPI, you may
still be able to depend on them, as long as they are available for download
as an egg, in the standard distutils ``sdist`` format, or as a single ``.py``
file. You just need to add some URLs to the ``dependency_links`` argument to
``setup()``.
 
The URLs must be either:
 
1. direct download URLs, or
2. the URLs of web pages that contain direct download links
 
In general, it's better to link to web pages, because it is usually less
complex to update a web page than to release a new version of your project.
You can also use a SourceForge ``showfiles.php`` link in the case where a
package you depend on is distributed via SourceForge.
 
If you depend on a package that's distributed as a single ``.py`` file, you
must include an ``"#egg=project-version"`` suffix to the URL, to give a project
name and version number. (Be sure to escape any dashes in the name or version
by replacing them with underscores.) EasyInstall will recognize this suffix
and automatically create a trivial ``setup.py`` to wrap the single ``.py`` file
as an egg.
 
The ``dependency_links`` option takes the form of a list of URL strings. For
example, the below will cause EasyInstall to search the specified page for
eggs or source distributions, if the package's dependencies aren't already
installed::
 
    setup(
        ...
        dependency_links = [
            "http://peak.telecommunity.com/snapshots/"
        ],
    )
 
 
.. _Declaring Extras:
 
 

The distutils have traditionally allowed installation of "data files", which
are placed in a platform-specific location. However, the most common use case
for data files distributed with a package is for use *by* the package, usually
by including the data files in the package directory. Setuptools supports this
by allowing a ``package_data`` argument to ``setup()``, e.g.::
by including the data files in the package directory.
 
Setuptools offers three ways to specify data files to be included in your
packages. First, you can simply use the ``include_package_data`` keyword,
e.g.::
 
    from setuptools import setup, find_packages
    setup(
        ...
        include_package_data = True
    )
 
This tells setuptools to install any data files it finds in your packages. The
data files must be under CVS or Subversion control, or else they must be
specified via the distutils' ``MANIFEST.in`` file. (They can also be tracked
by another revision control system, using an appropriate plugin. See the
section below on `Adding Support for Other Revision Control Systems`_ for
information on how to write such plugins.)
 
If you want finer-grained control over what files are included (for example, if
you have documentation files in your package directories and want to exclude
them from installation), then you can also use the ``package_data`` keyword,
e.g.::
 
    from setuptools import setup, find_packages
    setup(

        ...
        packages = find_packages('src'), # include all packages under src
        package_dir = {'':'src'}, # tell distutils packages are under src
        
 
        package_data = {
            # If any package contains *.txt files, include them:
            '': ['*.txt'],

Python 2.4; there is `some documentation for the feature`__ available on the
python.org website.)
 
__ http://docs.python.org/dist/node11.html
__ http://docs.python.org/dist/node11.html
 
Sometimes, the ``include_package_data`` or ``package_data`` options alone
aren't sufficient to precisely define what files you want included. For
example, you may want to include package README files in your revision control
system and source distributions, but exclude them from being installed. So,
setuptools offers an ``exclude_package_data`` option as well, that allows you
to do things like this::
 
    from setuptools import setup, find_packages
    setup(
        ...
        packages = find_packages('src'), # include all packages under src
        package_dir = {'':'src'}, # tell distutils packages are under src
 
        include_package_data = True, # include everything in source control
 
        # ...but exclude README.txt from all packages
        exclude_package_data = { '': ['README.txt'] },
    )
 
The ``exclude_package_data`` option is a dictionary mapping package names to
lists of wildcard patterns, just like the ``package_data`` option. And, just
as with that option, a key of ``''`` will apply the given pattern(s) to all
packages. However, any files that match these patterns will be *excluded*
from installation, even if they were listed in ``package_data`` or were
included as a result of using ``include_package_data``.
 
In summary, the three options allow you to:
 
``include_package_data``
    Accept all data files and directories matched by ``MANIFEST.in`` or found
    in source control.
 
``package_data``
    Specify additional patterns to match files and directories that may or may
    not be matched by ``MANIFEST.in`` or found in source control.
 
``exclude_package_data``
    Specify patterns for data files and directories that should *not* be
    included when a package is installed, even if they would otherwise have
    been included due to the use of the preceding options.
 
NOTE: Due to the way the distutils build process works, a data file that you
include in your project and then stop including may be "orphaned" in your
project's build directories, requiring you to run ``setup.py clean --all`` to
fully remove them. This may also be important for your users and contributors
if they track intermediate revisions of your project using Subversion; be sure
to let them know when you make changes that remove files from inclusion so they
can run ``setup.py clean --all``.
 
 
Accessing Data Files at Runtime

There are several options to control the precise behavior of the ``develop``
command; see the section on the `develop`_ command below for more details.
 
Note that you can also apply setuptools commands to non-setuptools projects,
using commands like this::
 
Distributing a ``setuptools``-based package
===========================================
   python -c "import setuptools; execfile('setup.py')" develop
 
That is, you can simply list the normal setup commands and options following
the quoted part.
 
 
Distributing a ``setuptools``-based project
===========================================
 
Using ``setuptools``... Without bundling it!
---------------------------------------------

distributions, and then upload them both to PyPI, where they'll be easily
found by other projects that depend on them.
 
(By the way, if you need to distribute a specific version of ``setuptools``,
you can specify the exact version and base download URL as parameters to the
``use_setuptools()`` function. See the function's docstring for details.)
 
 
What Your Users Should Know
---------------------------
 
In general, a setuptools-based project looks just like any distutils-based
project -- as long as your users have an internet connection and are installing
to ``site-packages``, that is. But for some users, these conditions don't
apply, and they may become frustrated if this is their first encounter with
a setuptools-based project. To keep these users happy, you should review the
following topics in your project's installation instructions, if they are
relevant to your project and your target audience isn't already familiar with
setuptools and ``easy_install``.
 
Network Access
    If your project is using ``ez_setup``, you should inform users of the need
    to either have network access, or to preinstall the correct version of
    setuptools using the `EasyInstall installation instructions`_. Those
    instructions also have tips for dealing with firewalls as well as how to
    manually download and install setuptools.
 
Custom Installation Locations
    You should inform your users that if they are installing your project to
    somewhere other than the main ``site-packages`` directory, they should
    first install setuptools using the instructions for `Custom Installation
    Locations`_, before installing your project.
 
Your Project's Dependencies
    If your project depends on other projects that may need to be downloaded
    from PyPI or elsewhere, you should list them in your installation
    instructions, or tell users how to find out what they are. While most
    users will not need this information, any users who don't have unrestricted
    internet access may have to find, download, and install the other projects
    manually. (Note, however, that they must still install those projects
    using ``easy_install``, or your project will not know they are installed,
    and your setup script will try to download them again.)
 
    If you want to be especially friendly to users with limited network access,
    you may wish to build eggs for your project and its dependencies, making
    them all available for download from your site, or at least create a page
    with links to all of the needed eggs. In this way, users with limited
    network access can manually download all the eggs to a single directory,
    then use the ``-f`` option of ``easy_install`` to specify the directory
    to find eggs in. Users who have full network access can just use ``-f``
    with the URL of your download page, and ``easy_install`` will find all the
    needed eggs using your links directly. This is also useful when your
    target audience isn't able to compile packages (e.g. most Windows users)
    and your package or some of its dependencies include C code.
 
Subversion or CVS Users and Co-Developers
    Users and co-developers who are tracking your in-development code using
    CVS, Subversion, or some other revision control system should probably read
    this manual's sections regarding such development. Alternately, you may
    wish to create a quick-reference guide containing the tips from this manual
    that apply to your particular situation. For example, if you recommend
    that people use ``setup.py develop`` when tracking your in-development
    code, you should let them know that this needs to be run after every update
    or commit.
 
    Similarly, if you remove modules or data files from your project, you
    should remind them to run ``setup.py clean --all`` and delete any obsolete
    ``.pyc`` or ``.pyo``. (This tip applies to the distutils in general, not
    just setuptools, but not everybody knows about them; be kind to your users
    by spelling out your project's best practices rather than leaving them
    guessing.)
 
Creating System Packages
    Some users want to manage all Python packages using a single package
    manager, and sometimes that package manager isn't ``easy_install``!
    Setuptools currently supports ``bdist_rpm``, ``bdist_wininst``, and
    ``bdist_dumb`` formats for system packaging. If a user has a locally-
    installed "bdist" packaging tool that internally uses the distutils
    ``install`` command, it should be able to work with ``setuptools``. Some
    examples of "bdist" formats that this should work with include the
    ``bdist_nsi`` and ``bdist_msi`` formats for Windows.
 
    However, packaging tools that build binary distributions by running
    ``setup.py install`` on the command line or as a subprocess will require
    modification to work with setuptools. They should use the
    ``--single-version-externally-managed`` option to the ``install`` command,
    combined with the standard ``--root`` or ``--record`` options.
    See the `install command`_ documentation below for more details. The
    ``bdist_deb`` command is an example of a command that currently requires
    this kind of patching to work with setuptools.
 
    If you or your users have a problem building a usable system package for
    your project, please report the problem via the `mailing list`_ so that
    either the "bdist" tool in question or setuptools can be modified to
    resolve the issue.
 
 
 
Managing Multiple Projects
--------------------------

package, it means that the package has no meaningful contents in its
``__init__.py``, and that it is merely a container for modules and subpackages.
 
The ``pkg_resources`` runtime will automatically ensure that the contents of
namespace packages that are spread over multiple eggs or directories are
combined into a single virtual package.
The ``pkg_resources`` runtime will then automatically ensure that the contents
of namespace packages that are spread over multiple eggs or directories are
combined into a single "virtual" package.
 
The ``namespace_packages`` argument to ``setup()`` lets you declare your
project's namespace packages, so that they will be included in your project's
metadata. Then, the runtime will automatically detect this when it adds the
distribution to ``sys.path``, and ensure that the packages are properly merged.
 
The argument should list the namespace packages that the egg participates in.
For example, the ZopeInterface project might do this::
metadata. The argument should list the namespace packages that the egg
participates in. For example, the ZopeInterface project might do this::
 
    setup(
        # ...

 
because it contains a ``zope.interface`` package that lives in the ``zope``
namespace package. Similarly, a project for a standalone ``zope.publisher``
would also declare the ``zope`` namespace package.
would also declare the ``zope`` namespace package. When these projects are
installed and used, Python will see them both as part of a "virtual" ``zope``
package, even though they will be installed in different locations.
 
Namespace packages don't have to be top-level packages. For example, Zope 3's
``zope.app`` package is a namespace package, and in the future PEAK's

Note, by the way, that your project's source tree must include the namespace
packages' ``__init__.py`` files (and the ``__init__.py`` of any parent
packages), in a normal Python package layout. These ``__init__.py`` files
should not contain any code or data, because only *one* egg's ``__init__.py``
files will be used to construct the parent packages in memory at runtime, and
there is no guarantee which egg will be used.
 
For example, if both ``zope.interface`` and ``zope.publisher`` have been
installed from separate distributions, it is unspecified which of the two
distributions' ``zope/__init__.py`` files will be used to create the ``zope``
package in memory. Therefore, it is better not to have any code or data in
a namespace package's ``__init__`` module, so as to prevent any complications.
 
(This is one reason the concept is called a "namespace package": it is a
package that exists *only* to provide a namespace under which other modules or
packages are gathered. In Java, for example, namespace packages are often used
just to avoid naming collisions between different projects, using package names
like ``org.apache`` as a namespace for packages that are part of apache.org
projects.)
*must* contain the line::
 
    __import__('pkg_resources').declare_namespace(__name__)
 
This code ensures that the namespace package machinery is operating and that
the current package is registered as a namespace package.
 
You must NOT include any other code and data in a namespace package's
``__init__.py``. Even though it may appear to work during development, or when
projects are installed as ``.egg`` files, it will not work when the projects
are installed using "system" packaging tools -- in such cases the
``__init__.py`` files will not be installed, let alone executed.
 
You must include the ``declare_namespace()`` line in the ``__init__.py`` of
*every* project that has contents for the namespace package in question, in
order to ensure that the namespace will be declared regardless of which
project's copy of ``__init__.py`` is loaded first. If the first loaded
``__init__.py`` doesn't declare it, it will never *be* declared, because no
other copies will ever be loaded!)
 
 
TRANSITIONAL NOTE
~~~~~~~~~~~~~~~~~
 
Setuptools 0.6a automatically calls ``declare_namespace()`` for you at runtime,
but the 0.7a versions will *not*. This is because the automatic declaration
feature has some negative side effects, such as needing to import all namespace
packages during the initialization of the ``pkg_resources`` runtime, and also
the need for ``pkg_resources`` to be explicitly imported before any namespace
packages work at all. Beginning with the 0.7a releases, you'll be responsible
for including your own declaration lines, and the automatic declaration feature
will be dropped to get rid of the negative side effects.
 
During the remainder of the 0.6 development cycle, therefore, setuptools will
warn you about missing ``declare_namespace()`` calls in your ``__init__.py``
files, and you should correct these as soon as possible before setuptools 0.7a1
is released. Namespace packages without declaration lines will not work
correctly once a user has upgraded to setuptools 0.7a1, so it's important that
you make this change now in order to avoid having your code break in the field.
Our apologies for the inconvenience, and thank you for your patience.
 
 
 
Tagging and "Daily Build" or "Snapshot" Releases

egg distributions by adding one or more of the following to the project's
"official" version identifier:
 
* An identifying string, such as "build" or "dev", or a manually-tracked build
  or revision number (``--tag-build=STRING, -bSTRING``)
* A manually-specified pre-release tag, such as "build" or "dev", or a
  manually-specified post-release tag, such as a build or revision number
  (``--tag-build=STRING, -bSTRING``)
 
* A "last-modified revision number" string generated automatically from
* A "last-modified revision number" string generated automatically from
  Subversion's metadata (assuming your project is being built from a Subversion
  "working copy") (``--tag-svn-revision, -r``)
 
* An 8-character representation of the build date (``--tag-date, -d``)
* An 8-character representation of the build date (``--tag-date, -d``), as
  a postrelease tag
 
You can add these tags by adding ``egg_info`` and the desired options to
the command line ahead of the ``sdist`` or ``bdist`` commands that you want
to generate a daily build or snapshot for. See the section below on the
`egg_info`_ command for more details.
 
Also, if you are creating builds frequently, and either building them in a
(Also, before you release your project, be sure to see the section above on
`Specifying Your Project's Version`_ for more information about how pre- and
post-release tags affect how setuptools and EasyInstall interpret version
numbers. This is important in order to make sure that dependency processing
tools will know which versions of your project are newer than others.)
 
Finally, if you are creating builds frequently, and either building them in a
downloadable location or are copying them to a distribution server, you should
probably also check out the `rotate`_ command, which lets you automatically
delete all but the N most-recently-modified distributions matching a glob

(And, if you already have one, you might consider deleting it the next time
you would otherwise have to change it.)
 
Unlike the distutils, ``setuptools`` regenerates the source distribution
``MANIFEST`` file every time you build a source distribution, as long as you
*don't* have a ``MANIFEST.in`` file. If you do have a ``MANIFEST.in`` (e.g.
because you aren't using CVS or Subversion), then you'll have to follow the
normal distutils procedures for managing what files get included in a source
distribution, and setuptools' enhanced algorithms will *not* be used.
 
(Note, by the way, that if you're using some other revision control system, you
might consider submitting a patch to the ``setuptools.command.sdist`` module
so we can include support for it, too.)
(NOTE: other revision control systems besides CVS and Subversion can be
supported using plugins; see the section below on `Adding Support for Other
Revision Control Systems`_ for information on how to write such plugins.)
 
If you need to include automatically generated files, or files that are kept in
an unsupported revision control system, you'll need to create a ``MANIFEST.in``
file to specify any files that the default file location algorithm doesn't
catch. See the distutils documentation for more information on the format of
the ``MANIFEST.in`` file.
 
But, be sure to ignore any part of the distutils documentation that deals with
``MANIFEST`` or how it's generated from ``MANIFEST.in``; setuptools shields you
from these issues and doesn't work the same way in any case. Unlike the
distutils, setuptools regenerates the source distribution manifest file
every time you build a source distribution, and it builds it inside the
project's ``.egg-info`` directory, out of the way of your main project
directory. You therefore need not worry about whether it is up-to-date or not.
 
Indeed, because setuptools' approach to determining the contents of a source
distribution is so much simpler, its ``sdist`` command omits nearly all of
the options that the distutils' more complex ``sdist`` process requires. For
all practical purposes, you'll probably use only the ``--formats`` option, if
you use any option at all.
 
(By the way, if you're using some other revision control system, you might
consider creating and publishing a `revision control plugin for setuptools`_.)
 
 
.. _revision control plugin for setuptools: `Adding Support for Other Revision Control Systems`_
 
 
Making your package available for EasyInstall

will know that ``1.0a1`` supersedes any interim snapshots from Subversion, and
handle upgrades accordingly.
 
Note, by the way, that this means that you need to remove these settings from
``setup.cfg`` when you make an official release. This is easy to do if you
are developing on the trunk and using tags or branches for your releases - just
make the change after branching or tagging the release, so the trunk will still
produce development snapshots.
 
Also notice that this procedure means that the project version number you
specify in ``setup.py`` should always be the *next* version of your software,
not the last released version.
 
(Alternately, you can leave out the ``tag_build=.dev``, and always use the
(Note: the project version number you specify in ``setup.py`` should always be
the *next* version of your software, not the last released version.
Alternately, you can leave out the ``tag_build=.dev``, and always use the
*last* release as a version number, so that your post-1.0 builds are labelled
``1.0-r1263``, indicating a post-1.0 patchlevel. Most projects so far,
however, seem to prefer to think of their project as being a future version

as described in this section, it's a good idea to run ``setup.py develop``
after each Subversion checkin or update, because your project's version number
will be changing, and your script wrappers need to be updated accordingly.
 
Also, if the project's requirements have changed, the ``develop`` command will
take care of fetching the updated dependencies, building changed extensions,
etc. You should also inform your users of the need to run this command, if
they are working from a Subversion checkout, rather than using EasyInstall to
periodically fetch the latest version.
etc. Be sure to also remind any of your users who check out your project
from Subversion that they need to run ``setup.py develop`` after every update
in order to keep their checkout completely in sync.
 
 
Making "Official" (Non-Snapshot) Releases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
When you make an official release, creating source or binary distributions,
you will need to override the tag settings from ``setup.cfg``, so that you
don't end up registering versions like ``foobar-0.7a1.dev-r34832``. This is
easy to do if you are developing on the trunk and using tags or branches for
your releases - just make the change to ``setup.cfg`` after branching or
tagging the release, so the trunk will still produce development snapshots.
 
Alternately, if you are not branching for releases, you can override the
default version options on the command line, using something like::
 
    python setup.py egg_info -RDb "" sdist bdist_egg register upload
 
The first part of this command (``egg_info -RDb ""``) will override the
configured tag information, before creating source and binary eggs, registering
the project with PyPI, and uploading the files. Thus, these commands will use
the plain version from your ``setup.py``, without adding the Subversion
revision number or build designation string.
 
Of course, if you will be doing this a lot, you may wish to create a personal
alias for this operation, e.g.::
 
    python setup.py alias -u release egg_info -RDb ""
 
You can then use it like this::
 
    python setup.py release sdist bdist_egg register upload
 
Or of course you can create more elaborate aliases that do all of the above.
See the sections below on the `egg_info`_ and `alias`_ commands for more ideas.
 
 
 
Distributing Extensions compiled with Pyrex

and that your source releases will be similarly usable with or without Pyrex.
 
 
 
 
-----------------
Command Reference
-----------------

    a requirement can be met using a distribution that is already available in
    a directory on ``sys.path``, it will not be copied to the staging area.
 
``--egg-path=DIR``
    Force the generated ``.egg-link`` file to use a specified relative path
    to the source directory. This can be useful in circumstances where your
    installation directory is being shared by code running under multiple
    platforms (e.g. Mac and Windows) which have different absolute locations
    for the code under development, but the same *relative* locations with
    respect to the installation directory. If you use this option when
    installing, you must supply the same relative path when uninstalling.
 
In addition to the above options, the ``develop`` command also accepts all of
the same options accepted by ``easy_install``. If you've configured any
``easy_install`` settings in your ``setup.cfg`` (or other distutils config

them in a ``[develop]`` section or on the command line.
 
 
``easy_install`` - Find and install packages
============================================
 
This command runs the `EasyInstall tool
<http://peak.telecommunity.com/DevCenter/EasyInstall>`_ for you. It is exactly
equivalent to running the ``easy_install`` command. All command line arguments
following this command are consumed and not processed further by the distutils,
so this must be the last command listed on the command line. Please see
the EasyInstall documentation for the options reference and usage examples.
Normally, there is no reason to use this command via the command line, as you
can just use ``easy_install`` directly. It's only listed here so that you know
it's a distutils command, which means that you can:
 
* create command aliases that use it,
* create distutils extensions that invoke it as a subcommand, and
* configure options for it in your ``setup.cfg`` or other distutils config
  files.
 
 
.. _egg_info:
 
``egg_info`` - Create egg metadata and set build tags

metadata directory (used by the ``bdist_egg``, ``develop``, and ``test``
commands), and it allows you to temporarily change a project's version string,
to support "daily builds" or "snapshot" releases. It is run automatically by
the ``sdist``, ``bdist_egg``, ``develop``, and ``test`` commands in order to
update the project's metadata, but you can also specify it explicitly in order
to temporarily change the project's version string.
the ``sdist``, ``bdist_egg``, ``develop``, ``register``, and ``test`` commands
in order to update the project's metadata, but you can also specify it
explicitly in order to temporarily change the project's version string while
executing other commands. (It also generates the``.egg-info/SOURCES.txt``
manifest file, which is used when you are building source distributions.)
 
In addition to writing the core egg metadata defined by ``setuptools`` and
required by ``pkg_resources``, this command can be extended to write other
metadata files as well, by defining entry points in the ``egg_info.writers``
group. See the section on `Adding new EGG-INFO Files`_ below for more details.
Note that using additional metadata writers may require you to include a
``setup_requires`` argument to ``setup()`` in order to ensure that the desired
writers are available on ``sys.path``.
 
 
Release Tagging Options
-----------------------
 
The following options can be used to modify the project's version string for
all remaining commands on the setup command line. The options are processed

    always leave off --tag-build and then use one or both of the following
    options.)
 
    If you have a default build tag set in your ``setup.cfg``, you can suppress
    it on the command line using ``-b ""`` or ``--tag-build=""`` as an argument
    to the ``egg_info`` command.
 
``--tag-svn-revision, -r``
    If the current directory is a Subversion checkout (i.e. has a ``.svn``
    subdirectory, this appends a string of the form "-rNNNN" to the project's

    If there is no ``PKG-INFO`` file, or the version number contained therein
    does not end with ``-r`` and a number, then ``-r0`` is used.
 
``--no-svn-revision, -R``
    Don't include the Subversion revision in the version number. This option
    is included so you can override a default setting put in ``setup.cfg``.
 
``--tag-date, -d``
    Add a date stamp of the form "-YYYYMMDD" (e.g. "-20050528") to the
    project's version number.
 
``--no-date, -D``
    Don't include a date stamp in the version number. This option is included
    so you can override a default setting in ``setup.cfg``.
 
 
(Note: Because these options modify the version number used for source and
binary distributions of your project, you should first make sure that you know
how the resulting version numbers will be interpreted by automated tools
like EasyInstall. See the section above on `Specifying Your Project's
Version`_ for an explanation of pre- and post-release tags, as well as tips on
how to choose and verify a versioning scheme for your your project.)
 
For advanced uses, there is one other option that can be set, to change the
location of the project's ``.egg-info`` directory. Commands that need to find
the project's source directory or metadata should get it from this setting:
 
 
Other ``egg_info`` Options
--------------------------
 
``--egg-base=SOURCEDIR, -e SOURCEDIR``
    Specify the directory that should contain the .egg-info directory. This
    should normally be the root of your project's source tree (which is not

    ``package_dir`` argument to the ``setup()`` function, if any. If there is
    no ``package_dir`` set, this option defaults to the current directory.
 
In addition to writing the core egg metadata defined by ``setuptools`` and
required by ``pkg_resources``, this command can be extended to write other
metadata files as well, by defining entry points in the ``egg_info.writers``
group. See the section on `Adding new EGG-INFO Files`_ below for more details.
Note that using additional metadata writers may require you to include a
``setup_requires`` argument to ``setup()`` in order to ensure that the desired
writers are available on ``sys.path``.
 
``egg_info`` Examples
---------------------
 
Creating a dated "nightly build" snapshot egg::
 
    python setup.py egg_info --tag-date --tag-build=DEV bdist_egg
 
Creating and uploading a release with no version tags, even if some default
tags are specified in ``setup.cfg``::
 
    python setup.py egg_info -RDb "" sdist bdist_egg register upload
 
(Notice that ``egg_info`` must always appear on the command line *before* any
commands that you want the version changes to apply to.)
 
 
.. _install command:
 
``install`` - Run ``easy_install`` or old-style installation
============================================================
 
The setuptools ``install`` command is basically a shortcut to run the
``easy_install`` command on the current project. However, for convenience
in creating "system packages" of setuptools-based projects, you can also
use this option:
 
``--single-version-externally-managed``
    This boolean option tells the ``install`` command to perform an "old style"
    installation, with the addition of an ``.egg-info`` directory so that the
    installed project will still have its metadata available and operate
    normally. If you use this option, you *must* also specify the ``--root``
    or ``--record`` options (or both), because otherwise you will have no way
    to identify and remove the installed files.
 
This option is automatically in effect when ``install`` is invoked by another
distutils command, so that commands like ``bdist_wininst`` and ``bdist_rpm``
will create system packages of eggs. It is also automatically in effect if
you specify the ``--root`` option.
 
 
``install_egg_info`` - Install an ``.egg-info`` directory in ``site-packages``
==============================================================================
 
Setuptools runs this command as part of ``install`` operations that use the
``--single-version-externally-managed`` options. You should not invoke it
directly; it is documented here for completeness and so that distutils
extensions such as system package builders can make use of it. This command
has only one option:
 
``--install-dir=DIR, -d DIR``
    The parent directory where the ``.egg-info`` directory will be placed.
    Defaults to the same as the ``--install-dir`` option specified for the
    ``install_lib`` command, which is usually the system ``site-packages``
    directory.
 
This command assumes that the ``egg_info`` command has been given valid options
via the command line or ``setup.cfg``, as it will invoke the ``egg_info``
command and use its options to locate the project's source ``.egg-info``
directory.
 
 
.. _rotate:

    you will use a glob pattern like ``.zip`` or ``.egg`` to match files of
    the specified type. Note that each supplied pattern is treated as a
    distinct group of files for purposes of selecting files to delete.
    
 
``--keep=COUNT, -k COUNT``
    Number of matching distributions to keep. For each group of files
    identified by a pattern specified with the ``--match`` option, delete all

the `configuration file options`_ to change where the options are saved. For
example, this command does the same as above, but saves the compiler setting
to the site-wide (global) distutils configuration::
    
 
    setup.py build --compiler=mingw32 saveopts -g
 
Note that it doesn't matter where you place the ``saveopts`` command on the
command line; it will still save all the options specified for all commands.
For example, this is another valid way to spell the last example::
 
    setup.py saveopts -g build --compiler=mingw32
    setup.py saveopts -g build --compiler=mingw32
 
Note, however, that all of the commands specified are always run, regardless of
where ``saveopts`` is placed on the command line.

    Save settings to the global ``distutils.cfg`` file inside the ``distutils``
    package directory. You must have write access to that directory to use
    this option. You also can't combine this option with ``-u`` or ``-f``.
    
 
``--user-config, -u``
    Save settings to the current user's ``~/.pydistutils.cfg`` (POSIX) or
    ``$HOME/pydistutils.cfg`` (Windows) file. You can't combine this option

 
**Example 2**. Remove any setting for the distutils default package
installation directory (short option names)::
  
 
    setup.py setopt -c install -o install_lib -r
 
 

 
To use this command, your project's tests must be wrapped in a ``unittest``
test suite by either a function, a ``TestCase`` class or method, or a module
containing ``TestCase`` classes. Note that many test systems including
``doctest`` support wrapping their non-``unittest`` tests in ``TestSuite``
objects. So, if you are using a test package that does not support this, we
suggest you encourage its developers to implement test suite support, as this
is a convenient and standard way to aggregate a collection of tests to be run
under a common test harness.
or package containing ``TestCase`` classes. If the named suite is a module,
and the module has an ``additional_tests()`` function, it is called and the
result (which must be a ``unittest.TestSuite``) is added to the tests to be
run. If the named suite is a package, any submodules and subpackages are
recursively added to the overall test suite. (Note: if your project specifies
a ``test_loader``, the rules for processing the chosen ``test_suite`` may
differ; see the `test_loader`_ documentation for more details.)
 
Note that many test systems including ``doctest`` support wrapping their
non-``unittest`` tests in ``TestSuite`` objects. So, if you are using a test
package that does not support this, we suggest you encourage its developers to
implement test suite support, as this is a convenient and standard way to
aggregate a collection of tests to be run under a common test harness.
 
By default, tests will be run in the "verbose" mode of the ``unittest``
package's text test runner, but you can get the "quiet" mode (just dots) if

    setup.py bdist_egg upload # create an egg and upload it
    setup.py sdist upload # create a source distro and upload it
    setup.py sdist bdist_egg upload # create and upload both
    
 
Note that to upload files for a project, the corresponding version must already
be registered with PyPI, using the distutils ``register`` command. It's
usually a good idea to include the ``register`` command at the start of the

    Sign each uploaded file using GPG (GNU Privacy Guard). The ``gpg`` program
    must be available for execution on the system ``PATH``.
 
``--identity=NAME, -i NAME``
    Specify the identity or key name for GPG to use when signing. The value of
    this option will be passed through the ``--local-user`` option of the
    ``gpg`` program.
 
``--show-response``
    Display the full response text from server; this is useful for debugging
    PyPI problems.
 
``--repository=URL, -r URL``
    The URL of the repository to upload to. Defaults to
    http://www.python.org/pypi (i.e., the main PyPI installation).
    http://pypi.python.org/pypi (i.e., the main PyPI installation).
 
 
------------------------------------

----------------------------
 
Sometimes, your commands may need additional arguments to the ``setup()``
script. You can enable this by defining entry points in the
call. You can enable this by defining entry points in the
``distutils.setup_keywords`` group. For example, if you wanted a ``setup()``
argument called ``bar_baz``, you might add something like this to your
distutils extension project's setup script::

 
Also note that as with commands, it is not necessary to subclass or monkeypatch
the distutils ``Distribution`` class in order to add your arguments; it is
sufficient to define the entry points in your extension, as long as the setup
script lists your extension in its ``setup_requires`` argument.
sufficient to define the entry points in your extension, as long as any setup
script using your extension lists your project in its ``setup_requires``
argument.
 
 
Adding new EGG-INFO Files

those methods' docstrings for more details.
 
 
Adding Support for Other Revision Control Systems
-------------------------------------------------
 
If you would like to create a plugin for ``setuptools`` to find files in other
source control systems besides CVS and Subversion, you can do so by adding an
entry point to the ``setuptools.file_finders`` group. The entry point should
be a function accepting a single directory name, and should yield
all the filenames within that directory (and any subdirectories thereof) that
are under revision control.
 
For example, if you were going to create a plugin for a revision control system
called "foobar", you would write a function something like this::
 
    def find_files_for_foobar(dirname):
        # loop to yield paths that start with `dirname`
 
And you would register it in a setup script using something like this::
 
    entry_points = {
        "setuptools.file_finders": [
            "foobar = my_foobar_module:find_files_for_foobar"
        ]
    }
 
Then, anyone who wants to use your plugin can simply install it, and their
local setuptools installation will be able to find the necessary files.
 
It is not necessary to distribute source control plugins with projects that
simply use the other source control system, or to specify the plugins in
``setup_requires``. When you create a source distribution with the ``sdist``
command, setuptools automatically records what files were found in the
``SOURCES.txt`` file. That way, recipients of source distributions don't need
to have revision control at all. However, if someone is working on a package
by checking out with that system, they will need the same plugin(s) that the
original author is using.
 
A few important points for writing revision control file finders:
 
* Your finder function MUST return relative paths, created by appending to the
  passed-in directory name. Absolute paths are NOT allowed, nor are relative
  paths that reference a parent directory of the passed-in directory.
 
* Your finder function MUST accept an empty string as the directory name,
  meaning the current directory. You MUST NOT convert this to a dot; just
  yield relative paths. So, yielding a subdirectory named ``some/dir`` under
  the current directory should NOT be rendered as ``./some/dir`` or
  ``/somewhere/some/dir``, but *always* as simply ``some/dir``
 
* Your finder function SHOULD NOT raise any errors, and SHOULD deal gracefully
  with the absence of needed programs (i.e., ones belonging to the revision
  control system itself. It *may*, however, use ``distutils.log.warn()`` to
  inform the user of the missing program(s).
 
 
A Note Regarding Dependencies
-----------------------------
 
If the project *containing* your distutils/setuptools extension(s) depends on
any projects other than setuptools, you *must* also declare those dependencies
as part of your project's ``setup_requires`` keyword, so that they will
already be built (and at least temprorarily installed) before your extension
project is built.
 
So, if for example you create a project Foo that includes a new file finder
plugin, and Foo depends on Bar, then you *must* list Bar in both the
``install_requires`` **and** ``setup_requires`` arguments to ``setup()``.
 
If you don't do this, then in certain edge cases you may cause setuptools to
try to go into infinite recursion, trying to build your dependencies to resolve
your dependencies, while still building your dependencies. (It probably won't
happen on your development machine, but it *will* happen in a full build
pulling everything from revision control on a clean machine, and then you or
your users will be scratching their heads trying to figure it out!)
 
 
Subclassing ``Command``
-----------------------
 

Release Notes/Change History
----------------------------
 
0.6c11
 * Fix "bdist_wininst upload" trying to upload same file twice
 
0.6c10
 * Fix for the Python 2.6.3 build_ext API change
 
 * Ensure C libraries (as opposed to extensions) are also built when doing
   bdist_egg
 
 * Support for SVN 1.6
 
0.6c9
 * Fixed a missing files problem when using Windows source distributions on
   non-Windows platforms, due to distutils not handling manifest file line
   endings correctly.
 
 * Updated Pyrex support to work with Pyrex 0.9.6 and higher.
 
 * Minor changes for Jython compatibility, including skipping tests that can't
   work on Jython.
 
 * Fixed not installing eggs in ``install_requires`` if they were also used for
   ``setup_requires`` or ``tests_require``.
 
 * Fixed not fetching eggs in ``install_requires`` when running tests.
 
 * Allow ``ez_setup.use_setuptools()`` to upgrade existing setuptools
   installations when called from a standalone ``setup.py``.
 
 * Added a warning if a namespace package is declared, but its parent package
   is not also declared as a namespace.
 
 * Support Subversion 1.5
 
 * Removed use of deprecated ``md5`` module if ``hashlib`` is available
 
 * Fixed ``bdist_wininst upload`` trying to upload the ``.exe`` twice
 
 * Fixed ``bdist_egg`` putting a ``native_libs.txt`` in the source package's
   ``.egg-info``, when it should only be in the built egg's ``EGG-INFO``.
 
 * Ensure that _full_name is set on all shared libs before extensions are
   checked for shared lib usage. (Fixes a bug in the experimental shared
   library build support.)
 
 * Fix to allow unpacked eggs containing native libraries to fail more
   gracefully under Google App Engine (with an ``ImportError`` loading the
   C-based module, instead of getting a ``NameError``).
 
0.6c7
 * Fixed ``distutils.filelist.findall()`` crashing on broken symlinks, and
   ``egg_info`` command failing on new, uncommitted SVN directories.
 
 * Fix import problems with nested namespace packages installed via
   ``--root`` or ``--single-version-externally-managed``, due to the
   parent package not having the child package as an attribute.
 
0.6c6
 * Added ``--egg-path`` option to ``develop`` command, allowing you to force
   ``.egg-link`` files to use relative paths (allowing them to be shared across
   platforms on a networked drive).
 
 * Fix not building binary RPMs correctly.
 
 * Fix "eggsecutables" (such as setuptools' own egg) only being runnable with
   bash-compatible shells.
 
 * Fix ``#!`` parsing problems in Windows ``.exe`` script wrappers, when there
   was whitespace inside a quoted argument or at the end of the ``#!`` line
   (a regression introduced in 0.6c4).
 
 * Fix ``test`` command possibly failing if an older version of the project
   being tested was installed on ``sys.path`` ahead of the test source
   directory.
 
 * Fix ``find_packages()`` treating ``ez_setup`` and directories with ``.`` in
   their names as packages.
 
0.6c5
 * Fix uploaded ``bdist_rpm`` packages being described as ``bdist_egg``
   packages under Python versions less than 2.5.
 
 * Fix uploaded ``bdist_wininst`` packages being described as suitable for
   "any" version by Python 2.5, even if a ``--target-version`` was specified.
 
0.6c4
 * Overhauled Windows script wrapping to support ``bdist_wininst`` better.
   Scripts installed with ``bdist_wininst`` will always use ``#!python.exe`` or
   ``#!pythonw.exe`` as the executable name (even when built on non-Windows
   platforms!), and the wrappers will look for the executable in the script's
   parent directory (which should find the right version of Python).
 
 * Fix ``upload`` command not uploading files built by ``bdist_rpm`` or
   ``bdist_wininst`` under Python 2.3 and 2.4.
 
 * Add support for "eggsecutable" headers: a ``#!/bin/sh`` script that is
   prepended to an ``.egg`` file to allow it to be run as a script on Unix-ish
   platforms. (This is mainly so that setuptools itself can have a single-file
   installer on Unix, without doing multiple downloads, dealing with firewalls,
   etc.)
 
 * Fix problem with empty revision numbers in Subversion 1.4 ``entries`` files
 
 * Use cross-platform relative paths in ``easy-install.pth`` when doing
   ``develop`` and the source directory is a subdirectory of the installation
   target directory.
 
 * Fix a problem installing eggs with a system packaging tool if the project
   contained an implicit namespace package; for example if the ``setup()``
   listed a namespace package ``foo.bar`` without explicitly listing ``foo``
   as a namespace package.
 
0.6c3
 * Fixed breakages caused by Subversion 1.4's new "working copy" format
 
0.6c2
 * The ``ez_setup`` module displays the conflicting version of setuptools (and
   its installation location) when a script requests a version that's not
   available.
 
 * Running ``setup.py develop`` on a setuptools-using project will now install
   setuptools if needed, instead of only downloading the egg.
 
0.6c1
 * Fixed ``AttributeError`` when trying to download a ``setup_requires``
   dependency when a distribution lacks a ``dependency_links`` setting.
 
 * Made ``zip-safe`` and ``not-zip-safe`` flag files contain a single byte, so
   as to play better with packaging tools that complain about zero-length
   files.
 
 * Made ``setup.py develop`` respect the ``--no-deps`` option, which it
   previously was ignoring.
 
 * Support ``extra_path`` option to ``setup()`` when ``install`` is run in
   backward-compatibility mode.
 
 * Source distributions now always include a ``setup.cfg`` file that explicitly
   sets ``egg_info`` options such that they produce an identical version number
   to the source distribution's version number. (Previously, the default
   version number could be different due to the use of ``--tag-date``, or if
   the version was overridden on the command line that built the source
   distribution.)
 
0.6b4
 * Fix ``register`` not obeying name/version set by ``egg_info`` command, if
   ``egg_info`` wasn't explicitly run first on the same command line.
 
 * Added ``--no-date`` and ``--no-svn-revision`` options to ``egg_info``
   command, to allow suppressing tags configured in ``setup.cfg``.
 
 * Fixed redundant warnings about missing ``README`` file(s); it should now
   appear only if you are actually a source distribution.
 
0.6b3
 * Fix ``bdist_egg`` not including files in subdirectories of ``.egg-info``.
 
 * Allow ``.py`` files found by the ``include_package_data`` option to be
   automatically included. Remove duplicate data file matches if both
   ``include_package_data`` and ``package_data`` are used to refer to the same
   files.
 
0.6b1
 * Strip ``module`` from the end of compiled extension modules when computing
   the name of a ``.py`` loader/wrapper. (Python's import machinery ignores
   this suffix when searching for an extension module.)
 
0.6a11
 * Added ``test_loader`` keyword to support custom test loaders
 
 * Added ``setuptools.file_finders`` entry point group to allow implementing
   revision control plugins.
 
 * Added ``--identity`` option to ``upload`` command.
 
 * Added ``dependency_links`` to allow specifying URLs for ``--find-links``.
 
 * Enhanced test loader to scan packages as well as modules, and call
   ``additional_tests()`` if present to get non-unittest tests.
 
 * Support namespace packages in conjunction with system packagers, by omitting
   the installation of any ``__init__.py`` files for namespace packages, and
   adding a special ``.pth`` file to create a working package in
   ``sys.modules``.
 
 * Made ``--single-version-externally-managed`` automatic when ``--root`` is
   used, so that most system packagers won't require special support for
   setuptools.
 
 * Fixed ``setup_requires``, ``tests_require``, etc. not using ``setup.cfg`` or
   other configuration files for their option defaults when installing, and
   also made the install use ``--multi-version`` mode so that the project
   directory doesn't need to support .pth files.
 
 * ``MANIFEST.in`` is now forcibly closed when any errors occur while reading
   it. Previously, the file could be left open and the actual error would be
   masked by problems trying to remove the open file on Windows systems.
 
0.6a10
 * Fixed the ``develop`` command ignoring ``--find-links``.
 
0.6a9
 * The ``sdist`` command no longer uses the traditional ``MANIFEST`` file to
   create source distributions. ``MANIFEST.in`` is still read and processed,
   as are the standard defaults and pruning. But the manifest is built inside
   the project's ``.egg-info`` directory as ``SOURCES.txt``, and it is rebuilt
   every time the ``egg_info`` command is run.
 
 * Added the ``include_package_data`` keyword to ``setup()``, allowing you to
   automatically include any package data listed in revision control or
   ``MANIFEST.in``
 
 * Added the ``exclude_package_data`` keyword to ``setup()``, allowing you to
   trim back files included via the ``package_data`` and
   ``include_package_data`` options.
 
 * Fixed ``--tag-svn-revision`` not working when run from a source
   distribution.
 
 * Added warning for namespace packages with missing ``declare_namespace()``
 
 * Added ``tests_require`` keyword to ``setup()``, so that e.g. packages
   requiring ``nose`` to run unit tests can make this dependency optional
   unless the ``test`` command is run.
 
 * Made all commands that use ``easy_install`` respect its configuration
   options, as this was causing some problems with ``setup.py install``.
 
 * Added an ``unpack_directory()`` driver to ``setuptools.archive_util``, so
   that you can process a directory tree through a processing filter as if it
   were a zipfile or tarfile.
 
 * Added an internal ``install_egg_info`` command to use as part of old-style
   ``install`` operations, that installs an ``.egg-info`` directory with the
   package.
 
 * Added a ``--single-version-externally-managed`` option to the ``install``
   command so that you can more easily wrap a "flat" egg in a system package.
 
 * Enhanced ``bdist_rpm`` so that it installs single-version eggs that
   don't rely on a ``.pth`` file. The ``--no-egg`` option has been removed,
   since all RPMs are now built in a more backwards-compatible format.
 
 * Support full roundtrip translation of eggs to and from ``bdist_wininst``
   format. Running ``bdist_wininst`` on a setuptools-based package wraps the
   egg in an .exe that will safely install it as an egg (i.e., with metadata
   and entry-point wrapper scripts), and ``easy_install`` can turn the .exe
   back into an ``.egg`` file or directory and install it as such.
 
 
0.6a8
 * Fixed some problems building extensions when Pyrex was installed, especially
   with Python 2.4 and/or packages using SWIG.

 
0.6a5
 * Fixed missing gui/cli .exe files in distribution. Fixed bugs in tests.
 
 
0.6a3
 * Added ``gui_scripts`` entry point group to allow installing GUI scripts
   on Windows and other platforms. (The special handling is only for Windows;

0.6a1
 * Added support for building "old-style" RPMs that don't install an egg for
   the target package, using a ``--no-egg`` option.
   
 
 * The ``build_ext`` command now works better when using the ``--inplace``
   option and multiple Python versions. It now makes sure that all extensions
   match the current Python version, even if newer copies were built for a

 * The vestigial ``depends`` command has been removed. It was never finished
   or documented, and never would have worked without EasyInstall - which it
   pre-dated and was never compatible with.
     
 
0.5a12
 * The zip-safety scanner now checks for modules that might be used with
   ``python -m``, and marks them as unsafe for zipping, since Python 2.4 can't

 * Initial release.
 
 
============
Mailing list
============
Mailing List and Bug Tracker
============================
 
Please use the `distutils-sig mailing list`_ for questions and discussion about setuptools.
Please use the `distutils-sig mailing list`_ for questions and discussion about
setuptools, and the `setuptools bug tracker`_ ONLY for issues you have
confirmed via the list are actual bugs, and which you have reduced to a minimal
set of steps to reproduce.
 
.. _distutils-sig mailing list: http://mail.python.org/pipermail/distutils-sig/
.. _setuptools bug tracker: http://bugs.python.org/setuptools/
 

PythonPowered
ShowText of this page
EditText of this page
FindPage by browsing, title search , text search or an index
Or try one of these actions: AttachFile, DeletePage, LikePages, LocalSiteMap, SpellCheck