diff --git a/bin/compile b/bin/compile
index 51024d2fb3ab8dcc192ed59ef8ed47117f5c3edd..9b7f7b873dd5b8a37fb93fa3214bfd9d9e264d5c 100755
--- a/bin/compile
+++ b/bin/compile
@@ -28,7 +28,7 @@ PROFILE_PATH="$BUILD_DIR/.profile.d/python.sh"
DEFAULT_PYTHON_VERSION="python-2.7.3"
PYTHON_EXE="/app/.heroku/python/bin/python"
PIP_VERSION="1.3.1"
-DISTRIBUTE_VERSION="0.6.35"
+DISTRIBUTE_VERSION="0.6.36"
# Sanitizing environment variables.
unset GIT_DIR PYTHONHOME PYTHONPATH LD_LIBRARY_PATH LIBRARY_PATH
diff --git a/vendor/distribute-0.6.35/CHANGES.txt b/vendor/distribute-0.6.36/CHANGES.txt
similarity index 97%
rename from vendor/distribute-0.6.35/CHANGES.txt
rename to vendor/distribute-0.6.36/CHANGES.txt
index cae946e0dc7f610a68cf437b6011a91403570b99..16461a21aab0ae7ef393cd1dd573f3109ad985a8 100644
--- a/vendor/distribute-0.6.35/CHANGES.txt
+++ b/vendor/distribute-0.6.36/CHANGES.txt
@@ -2,6 +2,17 @@
CHANGES
=======
+------
+0.6.36
+------
+
+* Pull Request #35: In `Buildout issue 64
+ <https://github.com/buildout/buildout/issues/64>`_, it was reported that
+ under Python 3, installation of distutils scripts could attempt to copy
+ the ``__pycache__`` directory as a file, causing an error, apparently only
+ under Windows. Easy_install now skips all directories when processing
+ metadata scripts.
+
------
0.6.35
------
diff --git a/vendor/distribute-0.6.35/CONTRIBUTORS.txt b/vendor/distribute-0.6.36/CONTRIBUTORS.txt
similarity index 100%
rename from vendor/distribute-0.6.35/CONTRIBUTORS.txt
rename to vendor/distribute-0.6.36/CONTRIBUTORS.txt
diff --git a/vendor/distribute-0.6.35/DEVGUIDE.txt b/vendor/distribute-0.6.36/DEVGUIDE.txt
similarity index 100%
rename from vendor/distribute-0.6.35/DEVGUIDE.txt
rename to vendor/distribute-0.6.36/DEVGUIDE.txt
diff --git a/vendor/distribute-0.6.35/MANIFEST.in b/vendor/distribute-0.6.36/MANIFEST.in
similarity index 100%
rename from vendor/distribute-0.6.35/MANIFEST.in
rename to vendor/distribute-0.6.36/MANIFEST.in
diff --git a/vendor/distribute-0.6.35/PKG-INFO b/vendor/distribute-0.6.36/PKG-INFO
similarity index 96%
rename from vendor/distribute-0.6.35/PKG-INFO
rename to vendor/distribute-0.6.36/PKG-INFO
index 4a0374a7ef84ab5d126d600820a7a1b2c1472ef5..f75ee6f05c608875df5f417528da17a476fb1d36 100644
--- a/vendor/distribute-0.6.35/PKG-INFO
+++ b/vendor/distribute-0.6.36/PKG-INFO
@@ -1,6 +1,6 @@
Metadata-Version: 1.1
Name: distribute
-Version: 0.6.35
+Version: 0.6.36
Summary: Easily download, build, install, upgrade, and uninstall Python packages
Home-page: http://packages.python.org/distribute
Author: The fellowship of the packaging
@@ -107,9 +107,9 @@ Description: ===============================
Download the source tarball, uncompress it, then run the install command::
- $ curl -O http://pypi.python.org/packages/source/d/distribute/distribute-0.6.35.tar.gz
- $ tar -xzvf distribute-0.6.35.tar.gz
- $ cd distribute-0.6.35
+ $ curl -O http://pypi.python.org/packages/source/d/distribute/distribute-0.6.36.tar.gz
+ $ tar -xzvf distribute-0.6.36.tar.gz
+ $ cd distribute-0.6.36
$ python setup.py install
---------------------------
@@ -238,6 +238,17 @@ Description: ===============================
CHANGES
=======
+ ------
+ 0.6.36
+ ------
+
+ * Pull Request #35: In `Buildout `issue 64`_
+ <https://github.com/buildout/buildout/issues/64>`_, it was reported that
+ under Python 3, installation of distutils scripts could attempt to copy
+ the ``__pycache__`` directory as a file, causing an error, apparently only
+ under Windows. Easy_install now skips all directories when processing
+ metadata scripts.
+
------
0.6.35
------
@@ -848,6 +859,7 @@ Description: ===============================
.. _`issue #7`: http://bitbucket.org/tarek/distribute/issue/7
.. _`issue #8`: http://bitbucket.org/tarek/distribute/issue/8
.. _`issue #9`: http://bitbucket.org/tarek/distribute/issue/9
+ .. _`issue 64`: http://bitbucket.org/tarek/distribute/issue/64
Keywords: CPAN PyPI distutils eggs package management
diff --git a/vendor/distribute-0.6.35/README.txt b/vendor/distribute-0.6.36/README.txt
similarity index 98%
rename from vendor/distribute-0.6.35/README.txt
rename to vendor/distribute-0.6.36/README.txt
index ea13a9bc4362099ac385be3af56f30980f1f58a7..a827f4a627b23e8951531792c17a58dde3b397ef 100644
--- a/vendor/distribute-0.6.35/README.txt
+++ b/vendor/distribute-0.6.36/README.txt
@@ -99,9 +99,9 @@ Source installation
Download the source tarball, uncompress it, then run the install command::
- $ curl -O http://pypi.python.org/packages/source/d/distribute/distribute-0.6.35.tar.gz
- $ tar -xzvf distribute-0.6.35.tar.gz
- $ cd distribute-0.6.35
+ $ curl -O http://pypi.python.org/packages/source/d/distribute/distribute-0.6.36.tar.gz
+ $ tar -xzvf distribute-0.6.36.tar.gz
+ $ cd distribute-0.6.36
$ python setup.py install
---------------------------
diff --git a/vendor/distribute-0.6.35/_markerlib/__init__.py b/vendor/distribute-0.6.36/_markerlib/__init__.py
similarity index 100%
rename from vendor/distribute-0.6.35/_markerlib/__init__.py
rename to vendor/distribute-0.6.36/_markerlib/__init__.py
diff --git a/vendor/distribute-0.6.35/_markerlib/markers.py b/vendor/distribute-0.6.36/_markerlib/markers.py
similarity index 100%
rename from vendor/distribute-0.6.35/_markerlib/markers.py
rename to vendor/distribute-0.6.36/_markerlib/markers.py
diff --git a/vendor/distribute-0.6.36/distribute.egg-info/PKG-INFO b/vendor/distribute-0.6.36/distribute.egg-info/PKG-INFO
new file mode 100644
index 0000000000000000000000000000000000000000..f75ee6f05c608875df5f417528da17a476fb1d36
--- /dev/null
+++ b/vendor/distribute-0.6.36/distribute.egg-info/PKG-INFO
@@ -0,0 +1,883 @@
+Metadata-Version: 1.1
+Name: distribute
+Version: 0.6.36
+Summary: Easily download, build, install, upgrade, and uninstall Python packages
+Home-page: http://packages.python.org/distribute
+Author: The fellowship of the packaging
+Author-email: distutils-sig@python.org
+License: PSF or ZPL
+Description: ===============================
+ Installing and Using Distribute
+ ===============================
+
+ .. contents:: **Table of Contents**
+
+ -----------
+ Disclaimers
+ -----------
+
+ About the fork
+ ==============
+
+ `Distribute` is a fork of the `Setuptools` project.
+
+ Distribute is intended to replace Setuptools as the standard method
+ for working with Python module distributions.
+
+ The fork has two goals:
+
+ - Providing a backward compatible version to replace Setuptools
+ and make all distributions that depend on Setuptools work as
+ before, but with less bugs and behaviorial issues.
+
+ This work is done in the 0.6.x series.
+
+ Starting with version 0.6.2, Distribute supports Python 3.
+ Installing and using distribute for Python 3 code works exactly
+ the same as for Python 2 code, but Distribute also helps you to support
+ Python 2 and Python 3 from the same source code by letting you run 2to3
+ on the code as a part of the build process, by setting the keyword parameter
+ ``use_2to3`` to True. See http://packages.python.org/distribute for more
+ information.
+
+ - Refactoring the code, and releasing it in several distributions.
+ This work is being done in the 0.7.x series but not yet released.
+
+ The roadmap is still evolving, and the page that is up-to-date is
+ located at : `http://packages.python.org/distribute/roadmap`.
+
+ If you install `Distribute` and want to switch back for any reason to
+ `Setuptools`, get to the `Uninstallation instructions`_ section.
+
+ More documentation
+ ==================
+
+ You can get more information in the Sphinx-based documentation, located
+ at http://packages.python.org/distribute. This documentation includes the old
+ Setuptools documentation that is slowly replaced, and brand new content.
+
+ About the installation process
+ ==============================
+
+ The `Distribute` installer modifies your installation by de-activating an
+ existing installation of `Setuptools` in a bootstrap process. This process
+ has been tested in various installation schemes and contexts but in case of a
+ bug during this process your Python installation might be left in a broken
+ state. Since all modified files and directories are copied before the
+ installation starts, you will be able to get back to a normal state by reading
+ the instructions in the `Uninstallation instructions`_ section.
+
+ In any case, it is recommended to save you `site-packages` directory before
+ you start the installation of `Distribute`.
+
+ -------------------------
+ Installation Instructions
+ -------------------------
+
+ Distribute is only released as a source distribution.
+
+ It can be installed using pip, and can be done so with the source tarball,
+ or by using the ``distribute_setup.py`` script provided online.
+
+ ``distribute_setup.py`` is the simplest and preferred way on all systems.
+
+ distribute_setup.py
+ ===================
+
+ Download
+ `distribute_setup.py <http://python-distribute.org/distribute_setup.py>`_
+ and execute it, using the Python interpreter of your choice.
+
+ If your shell has the ``curl`` program you can do::
+
+ $ curl -O http://python-distribute.org/distribute_setup.py
+ $ python distribute_setup.py
+
+ Notice this file is also provided in the source release.
+
+ pip
+ ===
+
+ Run easy_install or pip::
+
+ $ pip install distribute
+
+ Source installation
+ ===================
+
+ Download the source tarball, uncompress it, then run the install command::
+
+ $ curl -O http://pypi.python.org/packages/source/d/distribute/distribute-0.6.36.tar.gz
+ $ tar -xzvf distribute-0.6.36.tar.gz
+ $ cd distribute-0.6.36
+ $ python setup.py install
+
+ ---------------------------
+ Uninstallation Instructions
+ ---------------------------
+
+ Like other distutils-based distributions, Distribute doesn't provide an
+ uninstaller yet. It's all done manually! We are all waiting for PEP 376
+ support in Python.
+
+ Distribute is installed in three steps:
+
+ 1. it gets out of the way an existing installation of Setuptools
+ 2. it installs a `fake` setuptools installation
+ 3. it installs distribute
+
+ Distribute can be removed like this:
+
+ - remove the ``distribute*.egg`` file located in your site-packages directory
+ - remove the ``setuptools.pth`` file located in you site-packages directory
+ - remove the easy_install script located in you ``sys.prefix/bin`` directory
+ - remove the ``setuptools*.egg`` directory located in your site-packages directory,
+ if any.
+
+ If you want to get back to setuptools:
+
+ - reinstall setuptools using its instruction.
+
+ Lastly:
+
+ - remove the *.OLD.* directory located in your site-packages directory if any,
+ **once you have checked everything was working correctly again**.
+
+ -------------------------
+ Quick help for developers
+ -------------------------
+
+ To create an egg which is compatible with Distribute, use the same
+ practice as with Setuptools, e.g.::
+
+ from setuptools import setup
+
+ setup(...
+ )
+
+ To use `pkg_resources` to access data files in the egg, you should
+ require the Setuptools distribution explicitly::
+
+ from setuptools import setup
+
+ setup(...
+ install_requires=['setuptools']
+ )
+
+ Only if you need Distribute-specific functionality should you depend
+ on it explicitly. In this case, replace the Setuptools dependency::
+
+ from setuptools import setup
+
+ setup(...
+ install_requires=['distribute']
+ )
+
+ -----------
+ Install FAQ
+ -----------
+
+ - **Why is Distribute wrapping my Setuptools installation?**
+
+ Since Distribute is a fork, and since it provides the same package
+ and modules, it renames the existing Setuptools egg and inserts a
+ new one which merely wraps the Distribute code. This way, full
+ backwards compatibility is kept for packages which rely on the
+ Setuptools modules.
+
+ At the same time, packages can meet their dependency on Setuptools
+ without actually installing it (which would disable Distribute).
+
+ - **How does Distribute interact with virtualenv?**
+
+ Everytime you create a virtualenv it will install setuptools by default.
+ You either need to re-install Distribute in it right after or pass the
+ ``--distribute`` option when creating it.
+
+ Once installed, your virtualenv will use Distribute transparently.
+
+ Although, if you have Setuptools installed in your system-wide Python,
+ and if the virtualenv you are in was generated without the `--no-site-packages`
+ option, the Distribute installation will stop.
+
+ You need in this case to build a virtualenv with the `--no-site-packages`
+ option or to install `Distribute` globally.
+
+ - **How does Distribute interacts with zc.buildout?**
+
+ You can use Distribute in your zc.buildout, with the --distribute option,
+ starting at zc.buildout 1.4.2::
+
+ $ python bootstrap.py --distribute
+
+ For previous zc.buildout versions, *the only thing* you need to do
+ is use the bootstrap at `http://python-distribute.org/bootstrap.py`. Run
+ that bootstrap and ``bin/buildout`` (and all other buildout-generated
+ scripts) will transparently use distribute instead of setuptools. You do
+ not need a specific buildout release.
+
+ A shared eggs directory is no problem (since 0.6.6): the setuptools egg is
+ left in place unmodified. So other buildouts that do not yet use the new
+ bootstrap continue to work just fine. And there is no need to list
+ ``distribute`` somewhere in your eggs: using the bootstrap is enough.
+
+ The source code for the bootstrap script is located at
+ `http://bitbucket.org/tarek/buildout-distribute`.
+
+
+
+ -----------------------------
+ Feedback and getting involved
+ -----------------------------
+
+ - Mailing list: http://mail.python.org/mailman/listinfo/distutils-sig
+ - Issue tracker: http://bitbucket.org/tarek/distribute/issues/
+ - Code Repository: http://bitbucket.org/tarek/distribute
+
+ =======
+ CHANGES
+ =======
+
+ ------
+ 0.6.36
+ ------
+
+ * Pull Request #35: In `Buildout `issue 64`_
+ <https://github.com/buildout/buildout/issues/64>`_, it was reported that
+ under Python 3, installation of distutils scripts could attempt to copy
+ the ``__pycache__`` directory as a file, causing an error, apparently only
+ under Windows. Easy_install now skips all directories when processing
+ metadata scripts.
+
+ ------
+ 0.6.35
+ ------
+
+ Note this release is backward-incompatible with distribute 0.6.23-0.6.34 in
+ how it parses version numbers.
+
+ * `Issue #278`_: Restored compatibility with distribute 0.6.22 and setuptools
+ 0.6. Updated the documentation to match more closely with the version
+ parsing as intended in setuptools 0.6.
+
+ ------
+ 0.6.34
+ ------
+
+ * `Issue #341`_: 0.6.33 fails to build under Python 2.4.
+
+ ------
+ 0.6.33
+ ------
+
+ * Fix 2 errors with Jython 2.5.
+ * Fix 1 failure with Jython 2.5 and 2.7.
+ * Disable workaround for Jython scripts on Linux systems.
+ * `Issue #336`_: `setup.py` no longer masks failure exit code when tests fail.
+ * Fix issue in pkg_resources where try/except around a platform-dependent
+ import would trigger hook load failures on Mercurial. See pull request 32
+ for details.
+ * `Issue #341`_: Fix a ResourceWarning.
+
+ ------
+ 0.6.32
+ ------
+
+ * Fix test suite with Python 2.6.
+ * Fix some DeprecationWarnings and ResourceWarnings.
+ * `Issue #335`_: Backed out `setup_requires` superceding installed requirements
+ until regression can be addressed.
+
+ ------
+ 0.6.31
+ ------
+
+ * `Issue #303`_: Make sure the manifest only ever contains UTF-8 in Python 3.
+ * `Issue #329`_: Properly close files created by tests for compatibility with
+ Jython.
+ * Work around Jython bugs `#1980 <http://bugs.jython.org/issue1980>`_ and
+ `#1981 <http://bugs.jython.org/issue1981>`_.
+ * `Issue #334`_: Provide workaround for packages that reference `sys.__stdout__`
+ such as numpy does. This change should address
+ `virtualenv #359 <https://github.com/pypa/virtualenv/issues/359>`_ as long
+ as the system encoding is UTF-8 or the IO encoding is specified in the
+ environment, i.e.::
+
+ PYTHONIOENCODING=utf8 pip install numpy
+
+ * Fix for encoding issue when installing from Windows executable on Python 3.
+ * `Issue #323`_: Allow `setup_requires` requirements to supercede installed
+ requirements. Added some new keyword arguments to existing pkg_resources
+ methods. Also had to updated how __path__ is handled for namespace packages
+ to ensure that when a new egg distribution containing a namespace package is
+ placed on sys.path, the entries in __path__ are found in the same order they
+ would have been in had that egg been on the path when pkg_resources was
+ first imported.
+
+ ------
+ 0.6.30
+ ------
+
+ * `Issue #328`_: Clean up temporary directories in distribute_setup.py.
+ * Fix fatal bug in distribute_setup.py.
+
+ ------
+ 0.6.29
+ ------
+
+ * Pull Request #14: Honor file permissions in zip files.
+ * `Issue #327`_: Merged pull request #24 to fix a dependency problem with pip.
+ * Merged pull request #23 to fix https://github.com/pypa/virtualenv/issues/301.
+ * If Sphinx is installed, the `upload_docs` command now runs `build_sphinx`
+ to produce uploadable documentation.
+ * `Issue #326`_: `upload_docs` provided mangled auth credentials under Python 3.
+ * `Issue #320`_: Fix check for "createable" in distribute_setup.py.
+ * `Issue #305`_: Remove a warning that was triggered during normal operations.
+ * `Issue #311`_: Print metadata in UTF-8 independent of platform.
+ * `Issue #303`_: Read manifest file with UTF-8 encoding under Python 3.
+ * `Issue #301`_: Allow to run tests of namespace packages when using 2to3.
+ * `Issue #304`_: Prevent import loop in site.py under Python 3.3.
+ * `Issue #283`_: Reenable scanning of `*.pyc` / `*.pyo` files on Python 3.3.
+ * `Issue #299`_: The develop command didn't work on Python 3, when using 2to3,
+ as the egg link would go to the Python 2 source. Linking to the 2to3'd code
+ in build/lib makes it work, although you will have to rebuild the module
+ before testing it.
+ * `Issue #306`_: Even if 2to3 is used, we build in-place under Python 2.
+ * `Issue #307`_: Prints the full path when .svn/entries is broken.
+ * `Issue #313`_: Support for sdist subcommands (Python 2.7)
+ * `Issue #314`_: test_local_index() would fail an OS X.
+ * `Issue #310`_: Non-ascii characters in a namespace __init__.py causes errors.
+ * `Issue #218`_: Improved documentation on behavior of `package_data` and
+ `include_package_data`. Files indicated by `package_data` are now included
+ in the manifest.
+ * `distribute_setup.py` now allows a `--download-base` argument for retrieving
+ distribute from a specified location.
+
+ ------
+ 0.6.28
+ ------
+
+ * `Issue #294`_: setup.py can now be invoked from any directory.
+ * Scripts are now installed honoring the umask.
+ * Added support for .dist-info directories.
+ * `Issue #283`_: Fix and disable scanning of `*.pyc` / `*.pyo` files on
+ Python 3.3.
+
+ ------
+ 0.6.27
+ ------
+
+ * Support current snapshots of CPython 3.3.
+ * Distribute now recognizes README.rst as a standard, default readme file.
+ * Exclude 'encodings' modules when removing modules from sys.modules.
+ Workaround for #285.
+ * `Issue #231`_: Don't fiddle with system python when used with buildout
+ (bootstrap.py)
+
+ ------
+ 0.6.26
+ ------
+
+ * `Issue #183`_: Symlinked files are now extracted from source distributions.
+ * `Issue #227`_: Easy_install fetch parameters are now passed during the
+ installation of a source distribution; now fulfillment of setup_requires
+ dependencies will honor the parameters passed to easy_install.
+
+ ------
+ 0.6.25
+ ------
+
+ * `Issue #258`_: Workaround a cache issue
+ * `Issue #260`_: distribute_setup.py now accepts the --user parameter for
+ Python 2.6 and later.
+ * `Issue #262`_: package_index.open_with_auth no longer throws LookupError
+ on Python 3.
+ * `Issue #269`_: AttributeError when an exception occurs reading Manifest.in
+ on late releases of Python.
+ * `Issue #272`_: Prevent TypeError when namespace package names are unicode
+ and single-install-externally-managed is used. Also fixes PIP `issue
+ 449`_.
+ * `Issue #273`_: Legacy script launchers now install with Python2/3 support.
+
+ ------
+ 0.6.24
+ ------
+
+ * `Issue #249`_: Added options to exclude 2to3 fixers
+
+ ------
+ 0.6.23
+ ------
+
+ * `Issue #244`_: Fixed a test
+ * `Issue #243`_: Fixed a test
+ * `Issue #239`_: Fixed a test
+ * `Issue #240`_: Fixed a test
+ * `Issue #241`_: Fixed a test
+ * `Issue #237`_: Fixed a test
+ * `Issue #238`_: easy_install now uses 64bit executable wrappers on 64bit Python
+ * `Issue #208`_: Fixed parsed_versions, it now honors post-releases as noted in the documentation
+ * `Issue #207`_: Windows cli and gui wrappers pass CTRL-C to child python process
+ * `Issue #227`_: easy_install now passes its arguments to setup.py bdist_egg
+ * `Issue #225`_: Fixed a NameError on Python 2.5, 2.4
+
+ ------
+ 0.6.21
+ ------
+
+ * `Issue #225`_: FIxed a regression on py2.4
+
+ ------
+ 0.6.20
+ ------
+
+ * `Issue #135`_: Include url in warning when processing URLs in package_index.
+ * `Issue #212`_: Fix issue where easy_instal fails on Python 3 on windows installer.
+ * `Issue #213`_: Fix typo in documentation.
+
+ ------
+ 0.6.19
+ ------
+
+ * `Issue 206`_: AttributeError: 'HTTPMessage' object has no attribute 'getheaders'
+
+ ------
+ 0.6.18
+ ------
+
+ * `Issue 210`_: Fixed a regression introduced by `Issue 204`_ fix.
+
+ ------
+ 0.6.17
+ ------
+
+ * Support 'DISTRIBUTE_DISABLE_VERSIONED_EASY_INSTALL_SCRIPT' environment
+ variable to allow to disable installation of easy_install-${version} script.
+ * Support Python >=3.1.4 and >=3.2.1.
+ * `Issue 204`_: Don't try to import the parent of a namespace package in
+ declare_namespace
+ * `Issue 196`_: Tolerate responses with multiple Content-Length headers
+ * `Issue 205`_: Sandboxing doesn't preserve working_set. Leads to setup_requires
+ problems.
+
+ ------
+ 0.6.16
+ ------
+
+ * Builds sdist gztar even on Windows (avoiding `Issue 193`_).
+ * `Issue 192`_: Fixed metadata omitted on Windows when package_dir
+ specified with forward-slash.
+ * `Issue 195`_: Cython build support.
+ * `Issue 200`_: Issues with recognizing 64-bit packages on Windows.
+
+ ------
+ 0.6.15
+ ------
+
+ * Fixed typo in bdist_egg
+ * Several issues under Python 3 has been solved.
+ * `Issue 146`_: Fixed missing DLL files after easy_install of windows exe package.
+
+ ------
+ 0.6.14
+ ------
+
+ * `Issue 170`_: Fixed unittest failure. Thanks to Toshio.
+ * `Issue 171`_: Fixed race condition in unittests cause deadlocks in test suite.
+ * `Issue 143`_: Fixed a lookup issue with easy_install.
+ Thanks to David and Zooko.
+ * `Issue 174`_: Fixed the edit mode when its used with setuptools itself
+
+ ------
+ 0.6.13
+ ------
+
+ * `Issue 160`_: 2.7 gives ValueError("Invalid IPv6 URL")
+ * `Issue 150`_: Fixed using ~/.local even in a --no-site-packages virtualenv
+ * `Issue 163`_: scan index links before external links, and don't use the md5 when
+ comparing two distributions
+
+ ------
+ 0.6.12
+ ------
+
+ * `Issue 149`_: Fixed various failures on 2.3/2.4
+
+ ------
+ 0.6.11
+ ------
+
+ * Found another case of SandboxViolation - fixed
+ * `Issue 15`_ and 48: Introduced a socket timeout of 15 seconds on url openings
+ * Added indexsidebar.html into MANIFEST.in
+ * `Issue 108`_: Fixed TypeError with Python3.1
+ * `Issue 121`_: Fixed --help install command trying to actually install.
+ * `Issue 112`_: Added an os.makedirs so that Tarek's solution will work.
+ * `Issue 133`_: Added --no-find-links to easy_install
+ * Added easy_install --user
+ * `Issue 100`_: Fixed develop --user not taking '.' in PYTHONPATH into account
+ * `Issue 134`_: removed spurious UserWarnings. Patch by VanLindberg
+ * `Issue 138`_: cant_write_to_target error when setup_requires is used.
+ * `Issue 147`_: respect the sys.dont_write_bytecode flag
+
+ ------
+ 0.6.10
+ ------
+
+ * Reverted change made for the DistributionNotFound exception because
+ zc.buildout uses the exception message to get the name of the
+ distribution.
+
+ -----
+ 0.6.9
+ -----
+
+ * `Issue 90`_: unknown setuptools version can be added in the working set
+ * `Issue 87`_: setupt.py doesn't try to convert distribute_setup.py anymore
+ Initial Patch by arfrever.
+ * `Issue 89`_: added a side bar with a download link to the doc.
+ * `Issue 86`_: fixed missing sentence in pkg_resources doc.
+ * Added a nicer error message when a DistributionNotFound is raised.
+ * `Issue 80`_: test_develop now works with Python 3.1
+ * `Issue 93`_: upload_docs now works if there is an empty sub-directory.
+ * `Issue 70`_: exec bit on non-exec files
+ * `Issue 99`_: now the standalone easy_install command doesn't uses a
+ "setup.cfg" if any exists in the working directory. It will use it
+ only if triggered by ``install_requires`` from a setup.py call
+ (install, develop, etc).
+ * `Issue 101`_: Allowing ``os.devnull`` in Sandbox
+ * `Issue 92`_: Fixed the "no eggs" found error with MacPort
+ (platform.mac_ver() fails)
+ * `Issue 103`_: test_get_script_header_jython_workaround not run
+ anymore under py3 with C or POSIX local. Contributed by Arfrever.
+ * `Issue 104`_: remvoved the assertion when the installation fails,
+ with a nicer message for the end user.
+ * `Issue 100`_: making sure there's no SandboxViolation when
+ the setup script patches setuptools.
+
+ -----
+ 0.6.8
+ -----
+
+ * Added "check_packages" in dist. (added in Setuptools 0.6c11)
+ * Fixed the DONT_PATCH_SETUPTOOLS state.
+
+ -----
+ 0.6.7
+ -----
+
+ * `Issue 58`_: Added --user support to the develop command
+ * `Issue 11`_: Generated scripts now wrap their call to the script entry point
+ in the standard "if name == 'main'"
+ * Added the 'DONT_PATCH_SETUPTOOLS' environment variable, so virtualenv
+ can drive an installation that doesn't patch a global setuptools.
+ * Reviewed unladen-swallow specific change from
+ http://code.google.com/p/unladen-swallow/source/detail?spec=svn875&r=719
+ and determined that it no longer applies. Distribute should work fine with
+ Unladen Swallow 2009Q3.
+ * `Issue 21`_: Allow PackageIndex.open_url to gracefully handle all cases of a
+ httplib.HTTPException instead of just InvalidURL and BadStatusLine.
+ * Removed virtual-python.py from this distribution and updated documentation
+ to point to the actively maintained virtualenv instead.
+ * `Issue 64`_: use_setuptools no longer rebuilds the distribute egg every
+ time it is run
+ * use_setuptools now properly respects the requested version
+ * use_setuptools will no longer try to import a distribute egg for the
+ wrong Python version
+ * `Issue 74`_: no_fake should be True by default.
+ * `Issue 72`_: avoid a bootstrapping issue with easy_install -U
+
+ -----
+ 0.6.6
+ -----
+
+ * Unified the bootstrap file so it works on both py2.x and py3k without 2to3
+ (patch by Holger Krekel)
+
+ -----
+ 0.6.5
+ -----
+
+ * `Issue 65`_: cli.exe and gui.exe are now generated at build time,
+ depending on the platform in use.
+
+ * `Issue 67`_: Fixed doc typo (PEP 381/382)
+
+ * Distribute no longer shadows setuptools if we require a 0.7-series
+ setuptools. And an error is raised when installing a 0.7 setuptools with
+ distribute.
+
+ * When run from within buildout, no attempt is made to modify an existing
+ setuptools egg, whether in a shared egg directory or a system setuptools.
+
+ * Fixed a hole in sandboxing allowing builtin file to write outside of
+ the sandbox.
+
+ -----
+ 0.6.4
+ -----
+
+ * Added the generation of `distribute_setup_3k.py` during the release.
+ This closes `issue #52`_.
+
+ * Added an upload_docs command to easily upload project documentation to
+ PyPI's http://packages.python.org. This close `issue #56`_.
+
+ * Fixed a bootstrap bug on the use_setuptools() API.
+
+ -----
+ 0.6.3
+ -----
+
+ setuptools
+ ==========
+
+ * Fixed a bunch of calls to file() that caused crashes on Python 3.
+
+ bootstrapping
+ =============
+
+ * Fixed a bug in sorting that caused bootstrap to fail on Python 3.
+
+ -----
+ 0.6.2
+ -----
+
+ setuptools
+ ==========
+
+ * Added Python 3 support; see docs/python3.txt.
+ This closes http://bugs.python.org/setuptools/issue39.
+
+ * Added option to run 2to3 automatically when installing on Python 3.
+ This closes `issue #31`_.
+
+ * Fixed invalid usage of requirement.parse, that broke develop -d.
+ This closes http://bugs.python.org/setuptools/issue44.
+
+ * Fixed script launcher for 64-bit Windows.
+ This closes http://bugs.python.org/setuptools/issue2.
+
+ * KeyError when compiling extensions.
+ This closes http://bugs.python.org/setuptools/issue41.
+
+ bootstrapping
+ =============
+
+ * Fixed bootstrap not working on Windows. This closes `issue #49`_.
+
+ * Fixed 2.6 dependencies. This closes `issue #50`_.
+
+ * Make sure setuptools is patched when running through easy_install
+ This closes http://bugs.python.org/setuptools/issue40.
+
+ -----
+ 0.6.1
+ -----
+
+ setuptools
+ ==========
+
+ * package_index.urlopen now catches BadStatusLine and malformed url errors.
+ This closes `issue #16`_ and `issue #18`_.
+
+ * zip_ok is now False by default. This closes
+ http://bugs.python.org/setuptools/issue33.
+
+ * Fixed invalid URL error catching. http://bugs.python.org/setuptools/issue20.
+
+ * Fixed invalid bootstraping with easy_install installation (`issue #40`_).
+ Thanks to Florian Schulze for the help.
+
+ * Removed buildout/bootstrap.py. A new repository will create a specific
+ bootstrap.py script.
+
+
+ bootstrapping
+ =============
+
+ * The boostrap process leave setuptools alone if detected in the system
+ and --root or --prefix is provided, but is not in the same location.
+ This closes `issue #10`_.
+
+ ---
+ 0.6
+ ---
+
+ setuptools
+ ==========
+
+ * Packages required at build time where not fully present at install time.
+ This closes `issue #12`_.
+
+ * Protected against failures in tarfile extraction. This closes `issue #10`_.
+
+ * Made Jython api_tests.txt doctest compatible. This closes `issue #7`_.
+
+ * sandbox.py replaced builtin type file with builtin function open. This
+ closes `issue #6`_.
+
+ * Immediately close all file handles. This closes `issue #3`_.
+
+ * Added compatibility with Subversion 1.6. This references `issue #1`_.
+
+ pkg_resources
+ =============
+
+ * Avoid a call to /usr/bin/sw_vers on OSX and use the official platform API
+ instead. Based on a patch from ronaldoussoren. This closes `issue #5`_.
+
+ * Fixed a SandboxViolation for mkdir that could occur in certain cases.
+ This closes `issue #13`_.
+
+ * Allow to find_on_path on systems with tight permissions to fail gracefully.
+ This closes `issue #9`_.
+
+ * Corrected inconsistency between documentation and code of add_entry.
+ This closes `issue #8`_.
+
+ * Immediately close all file handles. This closes `issue #3`_.
+
+ easy_install
+ ============
+
+ * Immediately close all file handles. This closes `issue #3`_.
+
+
+ .. _`Issue #135`: http://bitbucket.org/tarek/distribute/issue/135
+ .. _`Issue #183`: http://bitbucket.org/tarek/distribute/issue/183
+ .. _`Issue #207`: http://bitbucket.org/tarek/distribute/issue/207
+ .. _`Issue #208`: http://bitbucket.org/tarek/distribute/issue/208
+ .. _`Issue #212`: http://bitbucket.org/tarek/distribute/issue/212
+ .. _`Issue #213`: http://bitbucket.org/tarek/distribute/issue/213
+ .. _`Issue #218`: http://bitbucket.org/tarek/distribute/issue/218
+ .. _`Issue #225`: http://bitbucket.org/tarek/distribute/issue/225
+ .. _`Issue #227`: http://bitbucket.org/tarek/distribute/issue/227
+ .. _`Issue #231`: http://bitbucket.org/tarek/distribute/issue/231
+ .. _`Issue #237`: http://bitbucket.org/tarek/distribute/issue/237
+ .. _`Issue #238`: http://bitbucket.org/tarek/distribute/issue/238
+ .. _`Issue #239`: http://bitbucket.org/tarek/distribute/issue/239
+ .. _`Issue #240`: http://bitbucket.org/tarek/distribute/issue/240
+ .. _`Issue #241`: http://bitbucket.org/tarek/distribute/issue/241
+ .. _`Issue #243`: http://bitbucket.org/tarek/distribute/issue/243
+ .. _`Issue #244`: http://bitbucket.org/tarek/distribute/issue/244
+ .. _`Issue #249`: http://bitbucket.org/tarek/distribute/issue/249
+ .. _`Issue #258`: http://bitbucket.org/tarek/distribute/issue/258
+ .. _`Issue #260`: http://bitbucket.org/tarek/distribute/issue/260
+ .. _`Issue #262`: http://bitbucket.org/tarek/distribute/issue/262
+ .. _`Issue #269`: http://bitbucket.org/tarek/distribute/issue/269
+ .. _`Issue #272`: http://bitbucket.org/tarek/distribute/issue/272
+ .. _`Issue #273`: http://bitbucket.org/tarek/distribute/issue/273
+ .. _`Issue #278`: http://bitbucket.org/tarek/distribute/issue/278
+ .. _`Issue #283`: http://bitbucket.org/tarek/distribute/issue/283
+ .. _`Issue #294`: http://bitbucket.org/tarek/distribute/issue/294
+ .. _`Issue #299`: http://bitbucket.org/tarek/distribute/issue/299
+ .. _`Issue #301`: http://bitbucket.org/tarek/distribute/issue/301
+ .. _`Issue #303`: http://bitbucket.org/tarek/distribute/issue/303
+ .. _`Issue #304`: http://bitbucket.org/tarek/distribute/issue/304
+ .. _`Issue #305`: http://bitbucket.org/tarek/distribute/issue/305
+ .. _`Issue #306`: http://bitbucket.org/tarek/distribute/issue/306
+ .. _`Issue #307`: http://bitbucket.org/tarek/distribute/issue/307
+ .. _`Issue #310`: http://bitbucket.org/tarek/distribute/issue/310
+ .. _`Issue #311`: http://bitbucket.org/tarek/distribute/issue/311
+ .. _`Issue #313`: http://bitbucket.org/tarek/distribute/issue/313
+ .. _`Issue #314`: http://bitbucket.org/tarek/distribute/issue/314
+ .. _`Issue #320`: http://bitbucket.org/tarek/distribute/issue/320
+ .. _`Issue #323`: http://bitbucket.org/tarek/distribute/issue/323
+ .. _`Issue #326`: http://bitbucket.org/tarek/distribute/issue/326
+ .. _`Issue #327`: http://bitbucket.org/tarek/distribute/issue/327
+ .. _`Issue #328`: http://bitbucket.org/tarek/distribute/issue/328
+ .. _`Issue #329`: http://bitbucket.org/tarek/distribute/issue/329
+ .. _`Issue #334`: http://bitbucket.org/tarek/distribute/issue/334
+ .. _`Issue #335`: http://bitbucket.org/tarek/distribute/issue/335
+ .. _`Issue #336`: http://bitbucket.org/tarek/distribute/issue/336
+ .. _`Issue #341`: http://bitbucket.org/tarek/distribute/issue/341
+ .. _`Issue 100`: http://bitbucket.org/tarek/distribute/issue/100
+ .. _`Issue 101`: http://bitbucket.org/tarek/distribute/issue/101
+ .. _`Issue 103`: http://bitbucket.org/tarek/distribute/issue/103
+ .. _`Issue 104`: http://bitbucket.org/tarek/distribute/issue/104
+ .. _`Issue 108`: http://bitbucket.org/tarek/distribute/issue/108
+ .. _`Issue 11`: http://bitbucket.org/tarek/distribute/issue/11
+ .. _`Issue 112`: http://bitbucket.org/tarek/distribute/issue/112
+ .. _`Issue 121`: http://bitbucket.org/tarek/distribute/issue/121
+ .. _`Issue 133`: http://bitbucket.org/tarek/distribute/issue/133
+ .. _`Issue 134`: http://bitbucket.org/tarek/distribute/issue/134
+ .. _`Issue 138`: http://bitbucket.org/tarek/distribute/issue/138
+ .. _`Issue 143`: http://bitbucket.org/tarek/distribute/issue/143
+ .. _`Issue 146`: http://bitbucket.org/tarek/distribute/issue/146
+ .. _`Issue 147`: http://bitbucket.org/tarek/distribute/issue/147
+ .. _`Issue 149`: http://bitbucket.org/tarek/distribute/issue/149
+ .. _`Issue 15`: http://bitbucket.org/tarek/distribute/issue/15
+ .. _`Issue 150`: http://bitbucket.org/tarek/distribute/issue/150
+ .. _`Issue 160`: http://bitbucket.org/tarek/distribute/issue/160
+ .. _`Issue 163`: http://bitbucket.org/tarek/distribute/issue/163
+ .. _`Issue 170`: http://bitbucket.org/tarek/distribute/issue/170
+ .. _`Issue 171`: http://bitbucket.org/tarek/distribute/issue/171
+ .. _`Issue 174`: http://bitbucket.org/tarek/distribute/issue/174
+ .. _`Issue 192`: http://bitbucket.org/tarek/distribute/issue/192
+ .. _`Issue 193`: http://bitbucket.org/tarek/distribute/issue/193
+ .. _`Issue 195`: http://bitbucket.org/tarek/distribute/issue/195
+ .. _`Issue 196`: http://bitbucket.org/tarek/distribute/issue/196
+ .. _`Issue 200`: http://bitbucket.org/tarek/distribute/issue/200
+ .. _`Issue 204`: http://bitbucket.org/tarek/distribute/issue/204
+ .. _`Issue 205`: http://bitbucket.org/tarek/distribute/issue/205
+ .. _`Issue 206`: http://bitbucket.org/tarek/distribute/issue/206
+ .. _`Issue 21`: http://bitbucket.org/tarek/distribute/issue/21
+ .. _`Issue 210`: http://bitbucket.org/tarek/distribute/issue/210
+ .. _`Issue 58`: http://bitbucket.org/tarek/distribute/issue/58
+ .. _`Issue 64`: http://bitbucket.org/tarek/distribute/issue/64
+ .. _`Issue 65`: http://bitbucket.org/tarek/distribute/issue/65
+ .. _`Issue 67`: http://bitbucket.org/tarek/distribute/issue/67
+ .. _`Issue 70`: http://bitbucket.org/tarek/distribute/issue/70
+ .. _`Issue 72`: http://bitbucket.org/tarek/distribute/issue/72
+ .. _`Issue 74`: http://bitbucket.org/tarek/distribute/issue/74
+ .. _`Issue 80`: http://bitbucket.org/tarek/distribute/issue/80
+ .. _`Issue 86`: http://bitbucket.org/tarek/distribute/issue/86
+ .. _`Issue 87`: http://bitbucket.org/tarek/distribute/issue/87
+ .. _`Issue 89`: http://bitbucket.org/tarek/distribute/issue/89
+ .. _`Issue 90`: http://bitbucket.org/tarek/distribute/issue/90
+ .. _`Issue 92`: http://bitbucket.org/tarek/distribute/issue/92
+ .. _`Issue 93`: http://bitbucket.org/tarek/distribute/issue/93
+ .. _`Issue 99`: http://bitbucket.org/tarek/distribute/issue/99
+ .. _`issue
+ 449`: http://bitbucket.org/tarek/distribute/issue/449
+ .. _`issue #1`: http://bitbucket.org/tarek/distribute/issue/1
+ .. _`issue #10`: http://bitbucket.org/tarek/distribute/issue/10
+ .. _`issue #12`: http://bitbucket.org/tarek/distribute/issue/12
+ .. _`issue #13`: http://bitbucket.org/tarek/distribute/issue/13
+ .. _`issue #16`: http://bitbucket.org/tarek/distribute/issue/16
+ .. _`issue #18`: http://bitbucket.org/tarek/distribute/issue/18
+ .. _`issue #3`: http://bitbucket.org/tarek/distribute/issue/3
+ .. _`issue #31`: http://bitbucket.org/tarek/distribute/issue/31
+ .. _`issue #40`: http://bitbucket.org/tarek/distribute/issue/40
+ .. _`issue #49`: http://bitbucket.org/tarek/distribute/issue/49
+ .. _`issue #5`: http://bitbucket.org/tarek/distribute/issue/5
+ .. _`issue #50`: http://bitbucket.org/tarek/distribute/issue/50
+ .. _`issue #52`: http://bitbucket.org/tarek/distribute/issue/52
+ .. _`issue #56`: http://bitbucket.org/tarek/distribute/issue/56
+ .. _`issue #6`: http://bitbucket.org/tarek/distribute/issue/6
+ .. _`issue #7`: http://bitbucket.org/tarek/distribute/issue/7
+ .. _`issue #8`: http://bitbucket.org/tarek/distribute/issue/8
+ .. _`issue #9`: http://bitbucket.org/tarek/distribute/issue/9
+ .. _`issue 64`: http://bitbucket.org/tarek/distribute/issue/64
+
+
+Keywords: CPAN PyPI distutils eggs package management
+Platform: UNKNOWN
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Python Software Foundation License
+Classifier: License :: OSI Approved :: Zope Public License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 2.4
+Classifier: Programming Language :: Python :: 2.5
+Classifier: Programming Language :: Python :: 2.6
+Classifier: Programming Language :: Python :: 2.7
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.1
+Classifier: Programming Language :: Python :: 3.2
+Classifier: Programming Language :: Python :: 3.3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Archiving :: Packaging
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
diff --git a/vendor/distribute-0.6.36/distribute.egg-info/SOURCES.txt b/vendor/distribute-0.6.36/distribute.egg-info/SOURCES.txt
new file mode 100644
index 0000000000000000000000000000000000000000..186220d23c35f627ed0da69b312d72c0080acc75
--- /dev/null
+++ b/vendor/distribute-0.6.36/distribute.egg-info/SOURCES.txt
@@ -0,0 +1,109 @@
+CHANGES.txt
+CONTRIBUTORS.txt
+DEVGUIDE.txt
+MANIFEST.in
+README.txt
+distribute_setup.py
+easy_install.py
+launcher.c
+pkg_resources.py
+release.py
+setup.cfg
+setup.py
+site.py
+_markerlib/__init__.py
+_markerlib/markers.py
+distribute.egg-info/PKG-INFO
+distribute.egg-info/SOURCES.txt
+distribute.egg-info/dependency_links.txt
+distribute.egg-info/entry_points.txt
+distribute.egg-info/top_level.txt
+distribute.egg-info/zip-safe
+docs/Makefile
+docs/conf.py
+docs/easy_install.txt
+docs/index.txt
+docs/pkg_resources.txt
+docs/python3.txt
+docs/roadmap.txt
+docs/setuptools.txt
+docs/using.txt
+docs/_templates/indexsidebar.html
+docs/_theme/nature/theme.conf
+docs/_theme/nature/static/nature.css_t
+docs/_theme/nature/static/pygments.css
+docs/build/html/_sources/easy_install.txt
+docs/build/html/_sources/index.txt
+docs/build/html/_sources/pkg_resources.txt
+docs/build/html/_sources/python3.txt
+docs/build/html/_sources/roadmap.txt
+docs/build/html/_sources/setuptools.txt
+docs/build/html/_sources/using.txt
+docs/build/html/_static/basic.css
+docs/build/html/_static/nature.css
+docs/build/html/_static/pygments.css
+setuptools/__init__.py
+setuptools/archive_util.py
+setuptools/cli-32.exe
+setuptools/cli-64.exe
+setuptools/cli.exe
+setuptools/depends.py
+setuptools/dist.py
+setuptools/extension.py
+setuptools/gui-32.exe
+setuptools/gui-64.exe
+setuptools/gui.exe
+setuptools/package_index.py
+setuptools/sandbox.py
+setuptools/script template (dev).py
+setuptools/script template.py
+setuptools/command/__init__.py
+setuptools/command/alias.py
+setuptools/command/bdist_egg.py
+setuptools/command/bdist_rpm.py
+setuptools/command/bdist_wininst.py
+setuptools/command/build_ext.py
+setuptools/command/build_py.py
+setuptools/command/develop.py
+setuptools/command/easy_install.py
+setuptools/command/egg_info.py
+setuptools/command/install.py
+setuptools/command/install_egg_info.py
+setuptools/command/install_lib.py
+setuptools/command/install_scripts.py
+setuptools/command/register.py
+setuptools/command/rotate.py
+setuptools/command/saveopts.py
+setuptools/command/sdist.py
+setuptools/command/setopt.py
+setuptools/command/test.py
+setuptools/command/upload.py
+setuptools/command/upload_docs.py
+setuptools/tests/__init__.py
+setuptools/tests/doctest.py
+setuptools/tests/py26compat.py
+setuptools/tests/server.py
+setuptools/tests/test_bdist_egg.py
+setuptools/tests/test_build_ext.py
+setuptools/tests/test_develop.py
+setuptools/tests/test_dist_info.py
+setuptools/tests/test_easy_install.py
+setuptools/tests/test_markerlib.py
+setuptools/tests/test_packageindex.py
+setuptools/tests/test_resources.py
+setuptools/tests/test_sandbox.py
+setuptools/tests/test_sdist.py
+setuptools/tests/test_test.py
+setuptools/tests/test_upload_docs.py
+setuptools/tests/win_script_wrapper.txt
+setuptools/tests/indexes/test_links_priority/external.html
+setuptools/tests/indexes/test_links_priority/simple/foobar/index.html
+tests/api_tests.txt
+tests/install_test.py
+tests/manual_test.py
+tests/test_distribute_setup.py
+tests/shlib_test/hello.c
+tests/shlib_test/hello.pyx
+tests/shlib_test/hellolib.c
+tests/shlib_test/setup.py
+tests/shlib_test/test_hello.py
\ No newline at end of file
diff --git a/vendor/distribute-0.6.36/distribute.egg-info/dependency_links.txt b/vendor/distribute-0.6.36/distribute.egg-info/dependency_links.txt
new file mode 100644
index 0000000000000000000000000000000000000000..8b137891791fe96927ad78e64b0aad7bded08bdc
--- /dev/null
+++ b/vendor/distribute-0.6.36/distribute.egg-info/dependency_links.txt
@@ -0,0 +1 @@
+
diff --git a/vendor/distribute-0.6.36/distribute.egg-info/entry_points.txt b/vendor/distribute-0.6.36/distribute.egg-info/entry_points.txt
new file mode 100644
index 0000000000000000000000000000000000000000..663882d630edfb4b4e59b2705c8345d70b75f8f3
--- /dev/null
+++ b/vendor/distribute-0.6.36/distribute.egg-info/entry_points.txt
@@ -0,0 +1,62 @@
+[distutils.commands]
+bdist_rpm = setuptools.command.bdist_rpm:bdist_rpm
+rotate = setuptools.command.rotate:rotate
+develop = setuptools.command.develop:develop
+setopt = setuptools.command.setopt:setopt
+build_py = setuptools.command.build_py:build_py
+saveopts = setuptools.command.saveopts:saveopts
+egg_info = setuptools.command.egg_info:egg_info
+register = setuptools.command.register:register
+upload_docs = setuptools.command.upload_docs:upload_docs
+install_egg_info = setuptools.command.install_egg_info:install_egg_info
+alias = setuptools.command.alias:alias
+easy_install = setuptools.command.easy_install:easy_install
+install_scripts = setuptools.command.install_scripts:install_scripts
+bdist_wininst = setuptools.command.bdist_wininst:bdist_wininst
+bdist_egg = setuptools.command.bdist_egg:bdist_egg
+install = setuptools.command.install:install
+test = setuptools.command.test:test
+install_lib = setuptools.command.install_lib:install_lib
+build_ext = setuptools.command.build_ext:build_ext
+sdist = setuptools.command.sdist:sdist
+
+[egg_info.writers]
+dependency_links.txt = setuptools.command.egg_info:overwrite_arg
+requires.txt = setuptools.command.egg_info:write_requirements
+PKG-INFO = setuptools.command.egg_info:write_pkg_info
+eager_resources.txt = setuptools.command.egg_info:overwrite_arg
+top_level.txt = setuptools.command.egg_info:write_toplevel_names
+namespace_packages.txt = setuptools.command.egg_info:overwrite_arg
+entry_points.txt = setuptools.command.egg_info:write_entries
+depends.txt = setuptools.command.egg_info:warn_depends_obsolete
+
+[console_scripts]
+easy_install = setuptools.command.easy_install:main
+easy_install-2.7 = setuptools.command.easy_install:main
+
+[setuptools.file_finders]
+svn_cvs = setuptools.command.sdist:_default_revctrl
+
+[distutils.setup_keywords]
+dependency_links = setuptools.dist:assert_string_list
+entry_points = setuptools.dist:check_entry_points
+extras_require = setuptools.dist:check_extras
+use_2to3_exclude_fixers = setuptools.dist:assert_string_list
+package_data = setuptools.dist:check_package_data
+install_requires = setuptools.dist:check_requirements
+use_2to3 = setuptools.dist:assert_bool
+use_2to3_fixers = setuptools.dist:assert_string_list
+include_package_data = setuptools.dist:assert_bool
+exclude_package_data = setuptools.dist:check_package_data
+namespace_packages = setuptools.dist:check_nsp
+test_suite = setuptools.dist:check_test_suite
+eager_resources = setuptools.dist:assert_string_list
+zip_safe = setuptools.dist:assert_bool
+test_loader = setuptools.dist:check_importable
+packages = setuptools.dist:check_packages
+convert_2to3_doctests = setuptools.dist:assert_string_list
+tests_require = setuptools.dist:check_requirements
+
+[setuptools.installation]
+eggsecutable = setuptools.command.easy_install:bootstrap
+
diff --git a/vendor/distribute-0.6.36/distribute.egg-info/top_level.txt b/vendor/distribute-0.6.36/distribute.egg-info/top_level.txt
new file mode 100644
index 0000000000000000000000000000000000000000..23374f9ccfaac50c7ffdbe61049c5b3d7db9085d
--- /dev/null
+++ b/vendor/distribute-0.6.36/distribute.egg-info/top_level.txt
@@ -0,0 +1,5 @@
+_markerlib
+easy_install
+pkg_resources
+setuptools
+site
diff --git a/vendor/distribute-0.6.36/distribute.egg-info/zip-safe b/vendor/distribute-0.6.36/distribute.egg-info/zip-safe
new file mode 100644
index 0000000000000000000000000000000000000000..d3f5a12faa99758192ecc4ed3fc22c9249232e86
--- /dev/null
+++ b/vendor/distribute-0.6.36/distribute.egg-info/zip-safe
@@ -0,0 +1 @@
+
diff --git a/vendor/distribute-0.6.35/distribute_setup.py b/vendor/distribute-0.6.36/distribute_setup.py
similarity index 99%
rename from vendor/distribute-0.6.35/distribute_setup.py
rename to vendor/distribute-0.6.36/distribute_setup.py
index a447f7ec8f568ee6b31a7a1c9136d74ca808d793..f630bca4f949698b34272c435b02839337c62571 100644
--- a/vendor/distribute-0.6.35/distribute_setup.py
+++ b/vendor/distribute-0.6.36/distribute_setup.py
@@ -49,7 +49,7 @@ except ImportError:
args = [quote(arg) for arg in args]
return os.spawnl(os.P_WAIT, sys.executable, *args) == 0
-DEFAULT_VERSION = "0.6.35"
+DEFAULT_VERSION = "0.6.36"
DEFAULT_URL = "http://pypi.python.org/packages/source/d/distribute/"
SETUPTOOLS_FAKED_VERSION = "0.6c11"
diff --git a/vendor/distribute-0.6.35/docs/Makefile b/vendor/distribute-0.6.36/docs/Makefile
similarity index 100%
rename from vendor/distribute-0.6.35/docs/Makefile
rename to vendor/distribute-0.6.36/docs/Makefile
diff --git a/vendor/distribute-0.6.35/docs/_templates/indexsidebar.html b/vendor/distribute-0.6.36/docs/_templates/indexsidebar.html
similarity index 100%
rename from vendor/distribute-0.6.35/docs/_templates/indexsidebar.html
rename to vendor/distribute-0.6.36/docs/_templates/indexsidebar.html
diff --git a/vendor/distribute-0.6.35/docs/_theme/nature/static/nature.css_t b/vendor/distribute-0.6.36/docs/_theme/nature/static/nature.css_t
similarity index 100%
rename from vendor/distribute-0.6.35/docs/_theme/nature/static/nature.css_t
rename to vendor/distribute-0.6.36/docs/_theme/nature/static/nature.css_t
diff --git a/vendor/distribute-0.6.35/docs/_theme/nature/static/pygments.css b/vendor/distribute-0.6.36/docs/_theme/nature/static/pygments.css
similarity index 100%
rename from vendor/distribute-0.6.35/docs/_theme/nature/static/pygments.css
rename to vendor/distribute-0.6.36/docs/_theme/nature/static/pygments.css
diff --git a/vendor/distribute-0.6.35/docs/_theme/nature/theme.conf b/vendor/distribute-0.6.36/docs/_theme/nature/theme.conf
similarity index 100%
rename from vendor/distribute-0.6.35/docs/_theme/nature/theme.conf
rename to vendor/distribute-0.6.36/docs/_theme/nature/theme.conf
diff --git a/vendor/distribute-0.6.35/docs/easy_install.txt b/vendor/distribute-0.6.36/docs/build/html/_sources/easy_install.txt
similarity index 100%
rename from vendor/distribute-0.6.35/docs/easy_install.txt
rename to vendor/distribute-0.6.36/docs/build/html/_sources/easy_install.txt
diff --git a/vendor/distribute-0.6.35/docs/index.txt b/vendor/distribute-0.6.36/docs/build/html/_sources/index.txt
similarity index 100%
rename from vendor/distribute-0.6.35/docs/index.txt
rename to vendor/distribute-0.6.36/docs/build/html/_sources/index.txt
diff --git a/vendor/distribute-0.6.35/docs/pkg_resources.txt b/vendor/distribute-0.6.36/docs/build/html/_sources/pkg_resources.txt
similarity index 100%
rename from vendor/distribute-0.6.35/docs/pkg_resources.txt
rename to vendor/distribute-0.6.36/docs/build/html/_sources/pkg_resources.txt
diff --git a/vendor/distribute-0.6.35/docs/python3.txt b/vendor/distribute-0.6.36/docs/build/html/_sources/python3.txt
similarity index 100%
rename from vendor/distribute-0.6.35/docs/python3.txt
rename to vendor/distribute-0.6.36/docs/build/html/_sources/python3.txt
diff --git a/vendor/distribute-0.6.35/docs/roadmap.txt b/vendor/distribute-0.6.36/docs/build/html/_sources/roadmap.txt
similarity index 100%
rename from vendor/distribute-0.6.35/docs/roadmap.txt
rename to vendor/distribute-0.6.36/docs/build/html/_sources/roadmap.txt
diff --git a/vendor/distribute-0.6.35/docs/setuptools.txt b/vendor/distribute-0.6.36/docs/build/html/_sources/setuptools.txt
similarity index 100%
rename from vendor/distribute-0.6.35/docs/setuptools.txt
rename to vendor/distribute-0.6.36/docs/build/html/_sources/setuptools.txt
diff --git a/vendor/distribute-0.6.35/docs/using.txt b/vendor/distribute-0.6.36/docs/build/html/_sources/using.txt
similarity index 100%
rename from vendor/distribute-0.6.35/docs/using.txt
rename to vendor/distribute-0.6.36/docs/build/html/_sources/using.txt
diff --git a/vendor/distribute-0.6.36/docs/build/html/_static/basic.css b/vendor/distribute-0.6.36/docs/build/html/_static/basic.css
new file mode 100644
index 0000000000000000000000000000000000000000..43e8bafaf35879a519818ef2157ad9687fb21413
--- /dev/null
+++ b/vendor/distribute-0.6.36/docs/build/html/_static/basic.css
@@ -0,0 +1,540 @@
+/*
+ * basic.css
+ * ~~~~~~~~~
+ *
+ * Sphinx stylesheet -- basic theme.
+ *
+ * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+/* -- main layout ----------------------------------------------------------- */
+
+div.clearer {
+ clear: both;
+}
+
+/* -- relbar ---------------------------------------------------------------- */
+
+div.related {
+ width: 100%;
+ font-size: 90%;
+}
+
+div.related h3 {
+ display: none;
+}
+
+div.related ul {
+ margin: 0;
+ padding: 0 0 0 10px;
+ list-style: none;
+}
+
+div.related li {
+ display: inline;
+}
+
+div.related li.right {
+ float: right;
+ margin-right: 5px;
+}
+
+/* -- sidebar --------------------------------------------------------------- */
+
+div.sphinxsidebarwrapper {
+ padding: 10px 5px 0 10px;
+}
+
+div.sphinxsidebar {
+ float: left;
+ width: 230px;
+ margin-left: -100%;
+ font-size: 90%;
+}
+
+div.sphinxsidebar ul {
+ list-style: none;
+}
+
+div.sphinxsidebar ul ul,
+div.sphinxsidebar ul.want-points {
+ margin-left: 20px;
+ list-style: square;
+}
+
+div.sphinxsidebar ul ul {
+ margin-top: 0;
+ margin-bottom: 0;
+}
+
+div.sphinxsidebar form {
+ margin-top: 10px;
+}
+
+div.sphinxsidebar input {
+ border: 1px solid #98dbcc;
+ font-family: sans-serif;
+ font-size: 1em;
+}
+
+div.sphinxsidebar #searchbox input[type="text"] {
+ width: 170px;
+}
+
+div.sphinxsidebar #searchbox input[type="submit"] {
+ width: 30px;
+}
+
+img {
+ border: 0;
+}
+
+/* -- search page ----------------------------------------------------------- */
+
+ul.search {
+ margin: 10px 0 0 20px;
+ padding: 0;
+}
+
+ul.search li {
+ padding: 5px 0 5px 20px;
+ background-image: url(file.png);
+ background-repeat: no-repeat;
+ background-position: 0 7px;
+}
+
+ul.search li a {
+ font-weight: bold;
+}
+
+ul.search li div.context {
+ color: #888;
+ margin: 2px 0 0 30px;
+ text-align: left;
+}
+
+ul.keywordmatches li.goodmatch a {
+ font-weight: bold;
+}
+
+/* -- index page ------------------------------------------------------------ */
+
+table.contentstable {
+ width: 90%;
+}
+
+table.contentstable p.biglink {
+ line-height: 150%;
+}
+
+a.biglink {
+ font-size: 1.3em;
+}
+
+span.linkdescr {
+ font-style: italic;
+ padding-top: 5px;
+ font-size: 90%;
+}
+
+/* -- general index --------------------------------------------------------- */
+
+table.indextable {
+ width: 100%;
+}
+
+table.indextable td {
+ text-align: left;
+ vertical-align: top;
+}
+
+table.indextable dl, table.indextable dd {
+ margin-top: 0;
+ margin-bottom: 0;
+}
+
+table.indextable tr.pcap {
+ height: 10px;
+}
+
+table.indextable tr.cap {
+ margin-top: 10px;
+ background-color: #f2f2f2;
+}
+
+img.toggler {
+ margin-right: 3px;
+ margin-top: 3px;
+ cursor: pointer;
+}
+
+div.modindex-jumpbox {
+ border-top: 1px solid #ddd;
+ border-bottom: 1px solid #ddd;
+ margin: 1em 0 1em 0;
+ padding: 0.4em;
+}
+
+div.genindex-jumpbox {
+ border-top: 1px solid #ddd;
+ border-bottom: 1px solid #ddd;
+ margin: 1em 0 1em 0;
+ padding: 0.4em;
+}
+
+/* -- general body styles --------------------------------------------------- */
+
+a.headerlink {
+ visibility: hidden;
+}
+
+h1:hover > a.headerlink,
+h2:hover > a.headerlink,
+h3:hover > a.headerlink,
+h4:hover > a.headerlink,
+h5:hover > a.headerlink,
+h6:hover > a.headerlink,
+dt:hover > a.headerlink {
+ visibility: visible;
+}
+
+div.body p.caption {
+ text-align: inherit;
+}
+
+div.body td {
+ text-align: left;
+}
+
+.field-list ul {
+ padding-left: 1em;
+}
+
+.first {
+ margin-top: 0 !important;
+}
+
+p.rubric {
+ margin-top: 30px;
+ font-weight: bold;
+}
+
+img.align-left, .figure.align-left, object.align-left {
+ clear: left;
+ float: left;
+ margin-right: 1em;
+}
+
+img.align-right, .figure.align-right, object.align-right {
+ clear: right;
+ float: right;
+ margin-left: 1em;
+}
+
+img.align-center, .figure.align-center, object.align-center {
+ display: block;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+.align-left {
+ text-align: left;
+}
+
+.align-center {
+ text-align: center;
+}
+
+.align-right {
+ text-align: right;
+}
+
+/* -- sidebars -------------------------------------------------------------- */
+
+div.sidebar {
+ margin: 0 0 0.5em 1em;
+ border: 1px solid #ddb;
+ padding: 7px 7px 0 7px;
+ background-color: #ffe;
+ width: 40%;
+ float: right;
+}
+
+p.sidebar-title {
+ font-weight: bold;
+}
+
+/* -- topics ---------------------------------------------------------------- */
+
+div.topic {
+ border: 1px solid #ccc;
+ padding: 7px 7px 0 7px;
+ margin: 10px 0 10px 0;
+}
+
+p.topic-title {
+ font-size: 1.1em;
+ font-weight: bold;
+ margin-top: 10px;
+}
+
+/* -- admonitions ----------------------------------------------------------- */
+
+div.admonition {
+ margin-top: 10px;
+ margin-bottom: 10px;
+ padding: 7px;
+}
+
+div.admonition dt {
+ font-weight: bold;
+}
+
+div.admonition dl {
+ margin-bottom: 0;
+}
+
+p.admonition-title {
+ margin: 0px 10px 5px 0px;
+ font-weight: bold;
+}
+
+div.body p.centered {
+ text-align: center;
+ margin-top: 25px;
+}
+
+/* -- tables ---------------------------------------------------------------- */
+
+table.docutils {
+ border: 0;
+ border-collapse: collapse;
+}
+
+table.docutils td, table.docutils th {
+ padding: 1px 8px 1px 5px;
+ border-top: 0;
+ border-left: 0;
+ border-right: 0;
+ border-bottom: 1px solid #aaa;
+}
+
+table.field-list td, table.field-list th {
+ border: 0 !important;
+}
+
+table.footnote td, table.footnote th {
+ border: 0 !important;
+}
+
+th {
+ text-align: left;
+ padding-right: 5px;
+}
+
+table.citation {
+ border-left: solid 1px gray;
+ margin-left: 1px;
+}
+
+table.citation td {
+ border-bottom: none;
+}
+
+/* -- other body styles ----------------------------------------------------- */
+
+ol.arabic {
+ list-style: decimal;
+}
+
+ol.loweralpha {
+ list-style: lower-alpha;
+}
+
+ol.upperalpha {
+ list-style: upper-alpha;
+}
+
+ol.lowerroman {
+ list-style: lower-roman;
+}
+
+ol.upperroman {
+ list-style: upper-roman;
+}
+
+dl {
+ margin-bottom: 15px;
+}
+
+dd p {
+ margin-top: 0px;
+}
+
+dd ul, dd table {
+ margin-bottom: 10px;
+}
+
+dd {
+ margin-top: 3px;
+ margin-bottom: 10px;
+ margin-left: 30px;
+}
+
+dt:target, .highlighted {
+ background-color: #fbe54e;
+}
+
+dl.glossary dt {
+ font-weight: bold;
+ font-size: 1.1em;
+}
+
+.field-list ul {
+ margin: 0;
+ padding-left: 1em;
+}
+
+.field-list p {
+ margin: 0;
+}
+
+.refcount {
+ color: #060;
+}
+
+.optional {
+ font-size: 1.3em;
+}
+
+.versionmodified {
+ font-style: italic;
+}
+
+.system-message {
+ background-color: #fda;
+ padding: 5px;
+ border: 3px solid red;
+}
+
+.footnote:target {
+ background-color: #ffa;
+}
+
+.line-block {
+ display: block;
+ margin-top: 1em;
+ margin-bottom: 1em;
+}
+
+.line-block .line-block {
+ margin-top: 0;
+ margin-bottom: 0;
+ margin-left: 1.5em;
+}
+
+.guilabel, .menuselection {
+ font-family: sans-serif;
+}
+
+.accelerator {
+ text-decoration: underline;
+}
+
+.classifier {
+ font-style: oblique;
+}
+
+abbr, acronym {
+ border-bottom: dotted 1px;
+ cursor: help;
+}
+
+/* -- code displays --------------------------------------------------------- */
+
+pre {
+ overflow: auto;
+ overflow-y: hidden; /* fixes display issues on Chrome browsers */
+}
+
+td.linenos pre {
+ padding: 5px 0px;
+ border: 0;
+ background-color: transparent;
+ color: #aaa;
+}
+
+table.highlighttable {
+ margin-left: 0.5em;
+}
+
+table.highlighttable td {
+ padding: 0 0.5em 0 0.5em;
+}
+
+tt.descname {
+ background-color: transparent;
+ font-weight: bold;
+ font-size: 1.2em;
+}
+
+tt.descclassname {
+ background-color: transparent;
+}
+
+tt.xref, a tt {
+ background-color: transparent;
+ font-weight: bold;
+}
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+ background-color: transparent;
+}
+
+.viewcode-link {
+ float: right;
+}
+
+.viewcode-back {
+ float: right;
+ font-family: sans-serif;
+}
+
+div.viewcode-block:target {
+ margin: -1px -10px;
+ padding: 0 10px;
+}
+
+/* -- math display ---------------------------------------------------------- */
+
+img.math {
+ vertical-align: middle;
+}
+
+div.body div.math p {
+ text-align: center;
+}
+
+span.eqno {
+ float: right;
+}
+
+/* -- printout stylesheet --------------------------------------------------- */
+
+@media print {
+ div.document,
+ div.documentwrapper,
+ div.bodywrapper {
+ margin: 0 !important;
+ width: 100%;
+ }
+
+ div.sphinxsidebar,
+ div.related,
+ div.footer,
+ #top-link {
+ display: none;
+ }
+}
\ No newline at end of file
diff --git a/vendor/distribute-0.6.36/docs/build/html/_static/nature.css b/vendor/distribute-0.6.36/docs/build/html/_static/nature.css
new file mode 100644
index 0000000000000000000000000000000000000000..891c59ebfbf19346da36612253af351c90b83e3e
--- /dev/null
+++ b/vendor/distribute-0.6.36/docs/build/html/_static/nature.css
@@ -0,0 +1,236 @@
+/**
+ * Sphinx stylesheet -- default theme
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ */
+
+@import url("basic.css");
+
+/* -- page layout ----------------------------------------------------------- */
+
+body {
+ font-family: Arial, sans-serif;
+ font-size: 100%;
+ background-color: #111111;
+ color: #555555;
+ margin: 0;
+ padding: 0;
+}
+
+div.documentwrapper {
+ float: left;
+ width: 100%;
+}
+
+div.bodywrapper {
+ margin: 0 0 0 300px;
+}
+
+hr{
+ border: 1px solid #B1B4B6;
+}
+
+div.document {
+ background-color: #fafafa;
+}
+
+div.body {
+ background-color: #ffffff;
+ color: #3E4349;
+ padding: 1em 30px 30px 30px;
+ font-size: 0.9em;
+}
+
+div.footer {
+ color: #555;
+ width: 100%;
+ padding: 13px 0;
+ text-align: center;
+ font-size: 75%;
+}
+
+div.footer a {
+ color: #444444;
+}
+
+div.related {
+ background-color: #6BA81E;
+ line-height: 36px;
+ color: #ffffff;
+ text-shadow: 0px 1px 0 #444444;
+ font-size: 1.1em;
+}
+
+div.related a {
+ color: #E2F3CC;
+}
+
+div.related .right {
+ font-size: 0.9em;
+}
+
+div.sphinxsidebar {
+ font-size: 0.9em;
+ line-height: 1.5em;
+ width: 300px;
+}
+
+div.sphinxsidebarwrapper{
+ padding: 20px 0;
+}
+
+div.sphinxsidebar h3,
+div.sphinxsidebar h4 {
+ font-family: Arial, sans-serif;
+ color: #222222;
+ font-size: 1.2em;
+ font-weight: bold;
+ margin: 0;
+ padding: 5px 10px;
+ text-shadow: 1px 1px 0 white
+}
+
+div.sphinxsidebar h3 a {
+ color: #444444;
+}
+
+div.sphinxsidebar p {
+ color: #888888;
+ padding: 5px 20px;
+ margin: 0.5em 0px;
+}
+
+div.sphinxsidebar p.topless {
+}
+
+div.sphinxsidebar ul {
+ margin: 10px 10px 10px 20px;
+ padding: 0;
+ color: #000000;
+}
+
+div.sphinxsidebar a {
+ color: #444444;
+}
+
+div.sphinxsidebar a:hover {
+ color: #E32E00;
+}
+
+div.sphinxsidebar input {
+ border: 1px solid #cccccc;
+ font-family: sans-serif;
+ font-size: 1.1em;
+ padding: 0.15em 0.3em;
+}
+
+div.sphinxsidebar input[type=text]{
+ margin-left: 20px;
+}
+
+/* -- body styles ----------------------------------------------------------- */
+
+a {
+ color: #005B81;
+ text-decoration: none;
+}
+
+a:hover {
+ color: #E32E00;
+}
+
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+ font-family: Arial, sans-serif;
+ font-weight: normal;
+ color: #212224;
+ margin: 30px 0px 10px 0px;
+ padding: 5px 0 5px 0px;
+ text-shadow: 0px 1px 0 white;
+ border-bottom: 1px solid #C8D5E3;
+}
+
+div.body h1 { margin-top: 0; font-size: 200%; }
+div.body h2 { font-size: 150%; }
+div.body h3 { font-size: 120%; }
+div.body h4 { font-size: 110%; }
+div.body h5 { font-size: 100%; }
+div.body h6 { font-size: 100%; }
+
+a.headerlink {
+ color: #c60f0f;
+ font-size: 0.8em;
+ padding: 0 4px 0 4px;
+ text-decoration: none;
+}
+
+a.headerlink:hover {
+ background-color: #c60f0f;
+ color: white;
+}
+
+div.body p, div.body dd, div.body li {
+ line-height: 1.8em;
+}
+
+div.admonition p.admonition-title + p {
+ display: inline;
+}
+
+div.highlight{
+ background-color: white;
+}
+
+div.note {
+ background-color: #eeeeee;
+ border: 1px solid #cccccc;
+}
+
+div.seealso {
+ background-color: #ffffcc;
+ border: 1px solid #ffff66;
+}
+
+div.topic {
+ background-color: #fafafa;
+ border-width: 0;
+}
+
+div.warning {
+ background-color: #ffe4e4;
+ border: 1px solid #ff6666;
+}
+
+p.admonition-title {
+ display: inline;
+}
+
+p.admonition-title:after {
+ content: ":";
+}
+
+pre {
+ padding: 10px;
+ background-color: #fafafa;
+ color: #222222;
+ line-height: 1.5em;
+ font-size: 1.1em;
+ margin: 1.5em 0 1.5em 0;
+ -webkit-box-shadow: 0px 0px 4px #d8d8d8;
+ -moz-box-shadow: 0px 0px 4px #d8d8d8;
+ box-shadow: 0px 0px 4px #d8d8d8;
+}
+
+tt {
+ color: #222222;
+ padding: 1px 2px;
+ font-size: 1.2em;
+ font-family: monospace;
+}
+
+#table-of-contents ul {
+ padding-left: 2em;
+}
diff --git a/vendor/distribute-0.6.36/docs/build/html/_static/pygments.css b/vendor/distribute-0.6.36/docs/build/html/_static/pygments.css
new file mode 100644
index 0000000000000000000000000000000000000000..652b76128b6a174f3407a50fff8735896f47d863
--- /dev/null
+++ b/vendor/distribute-0.6.36/docs/build/html/_static/pygments.css
@@ -0,0 +1,54 @@
+.c { color: #999988; font-style: italic } /* Comment */
+.k { font-weight: bold } /* Keyword */
+.o { font-weight: bold } /* Operator */
+.cm { color: #999988; font-style: italic } /* Comment.Multiline */
+.cp { color: #999999; font-weight: bold } /* Comment.preproc */
+.c1 { color: #999988; font-style: italic } /* Comment.Single */
+.gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
+.ge { font-style: italic } /* Generic.Emph */
+.gr { color: #aa0000 } /* Generic.Error */
+.gh { color: #999999 } /* Generic.Heading */
+.gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
+.go { color: #111 } /* Generic.Output */
+.gp { color: #555555 } /* Generic.Prompt */
+.gs { font-weight: bold } /* Generic.Strong */
+.gu { color: #aaaaaa } /* Generic.Subheading */
+.gt { color: #aa0000 } /* Generic.Traceback */
+.kc { font-weight: bold } /* Keyword.Constant */
+.kd { font-weight: bold } /* Keyword.Declaration */
+.kp { font-weight: bold } /* Keyword.Pseudo */
+.kr { font-weight: bold } /* Keyword.Reserved */
+.kt { color: #445588; font-weight: bold } /* Keyword.Type */
+.m { color: #009999 } /* Literal.Number */
+.s { color: #bb8844 } /* Literal.String */
+.na { color: #008080 } /* Name.Attribute */
+.nb { color: #999999 } /* Name.Builtin */
+.nc { color: #445588; font-weight: bold } /* Name.Class */
+.no { color: #ff99ff } /* Name.Constant */
+.ni { color: #800080 } /* Name.Entity */
+.ne { color: #990000; font-weight: bold } /* Name.Exception */
+.nf { color: #990000; font-weight: bold } /* Name.Function */
+.nn { color: #555555 } /* Name.Namespace */
+.nt { color: #000080 } /* Name.Tag */
+.nv { color: purple } /* Name.Variable */
+.ow { font-weight: bold } /* Operator.Word */
+.mf { color: #009999 } /* Literal.Number.Float */
+.mh { color: #009999 } /* Literal.Number.Hex */
+.mi { color: #009999 } /* Literal.Number.Integer */
+.mo { color: #009999 } /* Literal.Number.Oct */
+.sb { color: #bb8844 } /* Literal.String.Backtick */
+.sc { color: #bb8844 } /* Literal.String.Char */
+.sd { color: #bb8844 } /* Literal.String.Doc */
+.s2 { color: #bb8844 } /* Literal.String.Double */
+.se { color: #bb8844 } /* Literal.String.Escape */
+.sh { color: #bb8844 } /* Literal.String.Heredoc */
+.si { color: #bb8844 } /* Literal.String.Interpol */
+.sx { color: #bb8844 } /* Literal.String.Other */
+.sr { color: #808000 } /* Literal.String.Regex */
+.s1 { color: #bb8844 } /* Literal.String.Single */
+.ss { color: #bb8844 } /* Literal.String.Symbol */
+.bp { color: #999999 } /* Name.Builtin.Pseudo */
+.vc { color: #ff99ff } /* Name.Variable.Class */
+.vg { color: #ff99ff } /* Name.Variable.Global */
+.vi { color: #ff99ff } /* Name.Variable.Instance */
+.il { color: #009999 } /* Literal.Number.Integer.Long */
\ No newline at end of file
diff --git a/vendor/distribute-0.6.35/docs/conf.py b/vendor/distribute-0.6.36/docs/conf.py
similarity index 99%
rename from vendor/distribute-0.6.35/docs/conf.py
rename to vendor/distribute-0.6.36/docs/conf.py
index 98380ba9d61a26d83c922c65e1f93abcccbd3cd4..586e3fe6adf5f7f6e3e0014fe5964187ef904b9c 100644
--- a/vendor/distribute-0.6.35/docs/conf.py
+++ b/vendor/distribute-0.6.36/docs/conf.py
@@ -48,9 +48,9 @@ copyright = u'2009-2011, The fellowship of the packaging'
# built documents.
#
# The short X.Y version.
-version = '0.6.35'
+version = '0.6.36'
# The full version, including alpha/beta/rc tags.
-release = '0.6.35'
+release = '0.6.36'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/vendor/distribute-0.6.36/docs/easy_install.txt b/vendor/distribute-0.6.36/docs/easy_install.txt
new file mode 100644
index 0000000000000000000000000000000000000000..9b4fcfbb6e673e9c97de8503d0deeab602f1594c
--- /dev/null
+++ b/vendor/distribute-0.6.36/docs/easy_install.txt
@@ -0,0 +1,1597 @@
+============
+Easy Install
+============
+
+Easy Install is a python module (``easy_install``) bundled with ``setuptools``
+that lets you automatically download, build, install, and manage Python
+packages.
+
+Please share your experiences with us! If you encounter difficulty installing
+a package, please contact us via the `distutils mailing list
+<http://mail.python.org/pipermail/distutils-sig/>`_. (Note: please DO NOT send
+private email directly to the author of setuptools; it will be discarded. The
+mailing list is a searchable archive of previously-asked and answered
+questions; you should begin your research there before reporting something as a
+bug -- and then do so via list discussion first.)
+
+(Also, if you'd like to learn about how you can use ``setuptools`` to make your
+own packages work better with EasyInstall, or provide EasyInstall-like features
+without requiring your users to use EasyInstall directly, you'll probably want
+to check out the full `setuptools`_ documentation as well.)
+
+.. contents:: **Table of Contents**
+
+
+Using "Easy Install"
+====================
+
+
+.. _installation instructions:
+
+Installing "Easy Install"
+-------------------------
+
+Please see the `setuptools PyPI page <http://pypi.python.org/pypi/setuptools>`_
+for download links and basic installation instructions for each of the
+supported platforms.
+
+You will need at least Python 2.3.5, or if you are on a 64-bit platform, Python
+2.4. An ``easy_install`` script will be installed in the normal location for
+Python scripts on your platform.
+
+Note that the instructions on the setuptools PyPI page assume that you are
+are installling to Python's primary ``site-packages`` directory. If this is
+not the case, you should consult the section below on `Custom Installation
+Locations`_ before installing. (And, on Windows, you should not use the
+``.exe`` installer when installing to an alternate location.)
+
+Note that ``easy_install`` normally works by downloading files from the
+internet. 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.
+
+(Alternately, if you do not wish easy_install to actually download anything, you
+can restrict it from doing so with the ``--allow-hosts`` option; see the
+sections on `restricting downloads with --allow-hosts`_ and `command-line
+options`_ for more details.)
+
+
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+If EasyInstall/setuptools appears to install correctly, and you can run the
+``easy_install`` command but it fails with an ``ImportError``, the most likely
+cause is that you installed to a location other than ``site-packages``,
+without taking any of the steps described in the `Custom Installation
+Locations`_ section below. Please see that section and follow the steps to
+make sure that your custom location will work correctly. Then re-install.
+
+Similarly, if you can run ``easy_install``, and it appears to be installing
+packages, but then you can't import them, the most likely issue is that you
+installed EasyInstall correctly but are using it to install packages to a
+non-standard location that hasn't been properly prepared. Again, see the
+section on `Custom Installation Locations`_ for more details.
+
+
+Windows Notes
+~~~~~~~~~~~~~
+
+On Windows, an ``easy_install.exe`` launcher will also be installed, so that
+you can just type ``easy_install`` as long as it's on your ``PATH``. If typing
+``easy_install`` at the command prompt doesn't work, check to make sure your
+``PATH`` includes the appropriate ``C:\\Python2X\\Scripts`` directory. On
+most current versions of Windows, you can change the ``PATH`` by right-clicking
+"My Computer", choosing "Properties" and selecting the "Advanced" tab, then
+clicking the "Environment Variables" button. ``PATH`` will be in the "System
+Variables" section, and you will need to exit and restart your command shell
+(command.com, cmd.exe, bash, or other) for the change to take effect. Be sure
+to add a ``;`` after the last item on ``PATH`` before adding the scripts
+directory to it.
+
+Note that instead of changing your ``PATH`` to include the Python scripts
+directory, you can also retarget the installation location for scripts so they
+go on a directory that's already on the ``PATH``. For more information see the
+sections below on `Command-Line Options`_ and `Configuration Files`_. You
+can pass command line options (such as ``--script-dir``) to
+``distribute_setup.py`` to control where ``easy_install.exe`` will be installed.
+
+
+
+Downloading and Installing a Package
+------------------------------------
+
+For basic use of ``easy_install``, you need only supply the filename or URL of
+a source distribution or .egg file (`Python Egg`__).
+
+__ http://peak.telecommunity.com/DevCenter/PythonEggs
+
+**Example 1**. Install a package by name, searching PyPI for the latest
+version, and automatically downloading, building, and installing it::
+
+ easy_install SQLObject
+
+**Example 2**. Install or upgrade a package by name and version by finding
+links on a given "download page"::
+
+ easy_install -f http://pythonpaste.org/package_index.html SQLObject
+
+**Example 3**. Download a source distribution from a specified URL,
+automatically building and installing it::
+
+ easy_install http://example.com/path/to/MyPackage-1.2.3.tgz
+
+**Example 4**. Install an already-downloaded .egg file::
+
+ easy_install /my_downloads/OtherPackage-3.2.1-py2.3.egg
+
+**Example 5**. Upgrade an already-installed package to the latest version
+listed on PyPI::
+
+ easy_install --upgrade PyProtocols
+
+**Example 6**. Install a source distribution that's already downloaded and
+extracted in the current directory (New in 0.5a9)::
+
+ easy_install .
+
+**Example 7**. (New in 0.6a1) Find a source distribution or Subversion
+checkout URL for a package, and extract it or check it out to
+``~/projects/sqlobject`` (the name will always be in all-lowercase), where it
+can be examined or edited. (The package will not be installed, but it can
+easily be installed with ``easy_install ~/projects/sqlobject``. See `Editing
+and Viewing Source Packages`_ below for more info.)::
+
+ easy_install --editable --build-directory ~/projects SQLObject
+
+**Example 7**. (New in 0.6.11) Install a distribution within your home dir::
+
+ easy_install --user SQLAlchemy
+
+Easy Install accepts URLs, filenames, PyPI package names (i.e., ``distutils``
+"distribution" names), and package+version specifiers. In each case, it will
+attempt to locate the latest available version that meets your criteria.
+
+When downloading or processing downloaded files, Easy Install recognizes
+distutils source distribution files with extensions of .tgz, .tar, .tar.gz,
+.tar.bz2, or .zip. And of course it handles already-built .egg
+distributions as well as ``.win32.exe`` installers built using distutils.
+
+By default, packages are installed to the running Python installation's
+``site-packages`` directory, unless you provide the ``-d`` or ``--install-dir``
+option to specify an alternative directory, or specify an alternate location
+using distutils configuration files. (See `Configuration Files`_, below.)
+
+By default, any scripts included with the package are installed to the running
+Python installation's standard script installation location. However, if you
+specify an installation directory via the command line or a config file, then
+the default directory for installing scripts will be the same as the package
+installation directory, to ensure that the script will have access to the
+installed package. You can override this using the ``-s`` or ``--script-dir``
+option.
+
+Installed packages are added to an ``easy-install.pth`` file in the install
+directory, so that Python will always use the most-recently-installed version
+of the package. If you would like to be able to select which version to use at
+runtime, you should use the ``-m`` or ``--multi-version`` option.
+
+
+Upgrading a Package
+-------------------
+
+You don't need to do anything special to upgrade a package: just install the
+new version, either by requesting a specific version, e.g.::
+
+ easy_install "SomePackage==2.0"
+
+a version greater than the one you have now::
+
+ easy_install "SomePackage>2.0"
+
+using the upgrade flag, to find the latest available version on PyPI::
+
+ easy_install --upgrade SomePackage
+
+or by using a download page, direct download URL, or package filename::
+
+ easy_install -f http://example.com/downloads ExamplePackage
+
+ easy_install http://example.com/downloads/ExamplePackage-2.0-py2.4.egg
+
+ easy_install my_downloads/ExamplePackage-2.0.tgz
+
+If you're using ``-m`` or ``--multi-version`` , using the ``require()``
+function at runtime automatically selects the newest installed version of a
+package that meets your version criteria. So, installing a newer version is
+the only step needed to upgrade such packages.
+
+If you're installing to a directory on PYTHONPATH, or a configured "site"
+directory (and not using ``-m``), installing a package automatically replaces
+any previous version in the ``easy-install.pth`` file, so that Python will
+import the most-recently installed version by default. So, again, installing
+the newer version is the only upgrade step needed.
+
+If you haven't suppressed script installation (using ``--exclude-scripts`` or
+``-x``), then the upgraded version's scripts will be installed, and they will
+be automatically patched to ``require()`` the corresponding version of the
+package, so that you can use them even if they are installed in multi-version
+mode.
+
+``easy_install`` never actually deletes packages (unless you're installing a
+package with the same name and version number as an existing package), so if
+you want to get rid of older versions of a package, please see `Uninstalling
+Packages`_, below.
+
+
+Changing the Active Version
+---------------------------
+
+If you've upgraded a package, but need to revert to a previously-installed
+version, you can do so like this::
+
+ easy_install PackageName==1.2.3
+
+Where ``1.2.3`` is replaced by the exact version number you wish to switch to.
+If a package matching the requested name and version is not already installed
+in a directory on ``sys.path``, it will be located via PyPI and installed.
+
+If you'd like to switch to the latest installed version of ``PackageName``, you
+can do so like this::
+
+ easy_install PackageName
+
+This will activate the latest installed version. (Note: if you have set any
+``find_links`` via distutils configuration files, those download pages will be
+checked for the latest available version of the package, and it will be
+downloaded and installed if it is newer than your current version.)
+
+Note that changing the active version of a package will install the newly
+active version's scripts, unless the ``--exclude-scripts`` or ``-x`` option is
+specified.
+
+
+Uninstalling Packages
+---------------------
+
+If you have replaced a package with another version, then you can just delete
+the package(s) you don't need by deleting the PackageName-versioninfo.egg file
+or directory (found in the installation directory).
+
+If you want to delete the currently installed version of a package (or all
+versions of a package), you should first run::
+
+ easy_install -m PackageName
+
+This will ensure that Python doesn't continue to search for a package you're
+planning to remove. After you've done this, you can safely delete the .egg
+files or directories, along with any scripts you wish to remove.
+
+
+Managing Scripts
+----------------
+
+Whenever you install, upgrade, or change versions of a package, EasyInstall
+automatically installs the scripts for the selected package version, unless
+you tell it not to with ``-x`` or ``--exclude-scripts``. If any scripts in
+the script directory have the same name, they are overwritten.
+
+Thus, you do not normally need to manually delete scripts for older versions of
+a package, unless the newer version of the package does not include a script
+of the same name. However, if you are completely uninstalling a package, you
+may wish to manually delete its scripts.
+
+EasyInstall's default behavior means that you can normally only run scripts
+from one version of a package at a time. If you want to keep multiple versions
+of a script available, however, you can simply use the ``--multi-version`` or
+``-m`` option, and rename the scripts that EasyInstall creates. This works
+because EasyInstall installs scripts as short code stubs that ``require()`` the
+matching version of the package the script came from, so renaming the script
+has no effect on what it executes.
+
+For example, suppose you want to use two versions of the ``rst2html`` tool
+provided by the `docutils <http://docutils.sf.net/>`_ package. You might
+first install one version::
+
+ easy_install -m docutils==0.3.9
+
+then rename the ``rst2html.py`` to ``r2h_039``, and install another version::
+
+ easy_install -m docutils==0.3.10
+
+This will create another ``rst2html.py`` script, this one using docutils
+version 0.3.10 instead of 0.3.9. You now have two scripts, each using a
+different version of the package. (Notice that we used ``-m`` for both
+installations, so that Python won't lock us out of using anything but the most
+recently-installed version of the package.)
+
+
+
+Tips & Techniques
+-----------------
+
+
+Multiple Python Versions
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+As of version 0.6a11, EasyInstall installs itself under two names:
+``easy_install`` and ``easy_install-N.N``, where ``N.N`` is the Python version
+used to install it. Thus, if you install EasyInstall for both Python 2.3 and
+2.4, you can use the ``easy_install-2.3`` or ``easy_install-2.4`` scripts to
+install packages for Python 2.3 or 2.4, respectively.
+
+Also, if you're working with Python version 2.4 or higher, you can run Python
+with ``-m easy_install`` to run that particular Python version's
+``easy_install`` command.
+
+
+Restricting Downloads with ``--allow-hosts``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use the ``--allow-hosts`` (``-H``) option to restrict what domains
+EasyInstall will look for links and downloads on. ``--allow-hosts=None``
+prevents downloading altogether. You can also use wildcards, for example
+to restrict downloading to hosts in your own intranet. See the section below
+on `Command-Line Options`_ for more details on the ``--allow-hosts`` option.
+
+By default, there are no host restrictions in effect, but you can change this
+default by editing the appropriate `configuration files`_ and adding:
+
+.. code-block:: ini
+
+ [easy_install]
+ allow_hosts = *.myintranet.example.com,*.python.org
+
+The above example would then allow downloads only from hosts in the
+``python.org`` and ``myintranet.example.com`` domains, unless overridden on the
+command line.
+
+
+Installing on Un-networked Machines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Just copy the eggs or source packages you need to a directory on the target
+machine, then use the ``-f`` or ``--find-links`` option to specify that
+directory's location. For example::
+
+ easy_install -H None -f somedir SomePackage
+
+will attempt to install SomePackage using only eggs and source packages found
+in ``somedir`` and disallowing all remote access. You should of course make
+sure you have all of SomePackage's dependencies available in somedir.
+
+If you have another machine of the same operating system and library versions
+(or if the packages aren't platform-specific), you can create the directory of
+eggs using a command like this::
+
+ easy_install -zmaxd somedir SomePackage
+
+This will tell EasyInstall to put zipped eggs or source packages for
+SomePackage and all its dependencies into ``somedir``, without creating any
+scripts or .pth files. You can then copy the contents of ``somedir`` to the
+target machine. (``-z`` means zipped eggs, ``-m`` means multi-version, which
+prevents .pth files from being used, ``-a`` means to copy all the eggs needed,
+even if they're installed elsewhere on the machine, and ``-d`` indicates the
+directory to place the eggs in.)
+
+You can also build the eggs from local development packages that were installed
+with the ``setup.py develop`` command, by including the ``-l`` option, e.g.::
+
+ easy_install -zmaxld somedir SomePackage
+
+This will use locally-available source distributions to build the eggs.
+
+
+Packaging Others' Projects As Eggs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Need to distribute a package that isn't published in egg form? You can use
+EasyInstall to build eggs for a project. You'll want to use the ``--zip-ok``,
+``--exclude-scripts``, and possibly ``--no-deps`` options (``-z``, ``-x`` and
+``-N``, respectively). Use ``-d`` or ``--install-dir`` to specify the location
+where you'd like the eggs placed. By placing them in a directory that is
+published to the web, you can then make the eggs available for download, either
+in an intranet or to the internet at large.
+
+If someone distributes a package in the form of a single ``.py`` file, you can
+wrap it in an egg by tacking an ``#egg=name-version`` suffix on the file's URL.
+So, something like this::
+
+ easy_install -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo
+
+will install the package as an egg, and this::
+
+ easy_install -zmaxd. \
+ -f "http://some.example.com/downloads/foo.py#egg=foo-1.0" foo
+
+will create a ``.egg`` file in the current directory.
+
+
+Creating your own Package Index
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to local directories and the Python Package Index, EasyInstall can
+find download links on most any web page whose URL is given to the ``-f``
+(``--find-links``) option. In the simplest case, you can simply have a web
+page with links to eggs or Python source packages, even an automatically
+generated directory listing (such as the Apache web server provides).
+
+If you are setting up an intranet site for package downloads, you may want to
+configure the target machines to use your download site by default, adding
+something like this to their `configuration files`_:
+
+.. code-block:: ini
+
+ [easy_install]
+ find_links = http://mypackages.example.com/somedir/
+ http://turbogears.org/download/
+ http://peak.telecommunity.com/dist/
+
+As you can see, you can list multiple URLs separated by whitespace, continuing
+on multiple lines if necessary (as long as the subsequent lines are indented.
+
+If you are more ambitious, you can also create an entirely custom package index
+or PyPI mirror. See the ``--index-url`` option under `Command-Line Options`_,
+below, and also the section on `Package Index "API"`_.
+
+
+Password-Protected Sites
+------------------------
+
+If a site you want to download from is password-protected using HTTP "Basic"
+authentication, you can specify your credentials in the URL, like so::
+
+ http://some_userid:some_password@some.example.com/some_path/
+
+You can do this with both index page URLs and direct download URLs. As long
+as any HTML pages read by easy_install use *relative* links to point to the
+downloads, the same user ID and password will be used to do the downloading.
+
+
+Controlling Build Options
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+EasyInstall respects standard distutils `Configuration Files`_, so you can use
+them to configure build options for packages that it installs from source. For
+example, if you are on Windows using the MinGW compiler, you can configure the
+default compiler by putting something like this:
+
+.. code-block:: ini
+
+ [build]
+ compiler = mingw32
+
+into the appropriate distutils configuration file. In fact, since this is just
+normal distutils configuration, it will affect any builds using that config
+file, not just ones done by EasyInstall. For example, if you add those lines
+to ``distutils.cfg`` in the ``distutils`` package directory, it will be the
+default compiler for *all* packages you build. See `Configuration Files`_
+below for a list of the standard configuration file locations, and links to
+more documentation on using distutils configuration files.
+
+
+Editing and Viewing Source Packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes a package's source distribution contains additional documentation,
+examples, configuration files, etc., that are not part of its actual code. If
+you want to be able to examine these files, you can use the ``--editable``
+option to EasyInstall, and EasyInstall will look for a source distribution
+or Subversion URL for the package, then download and extract it or check it out
+as a subdirectory of the ``--build-directory`` you specify. If you then wish
+to install the package after editing or configuring it, you can do so by
+rerunning EasyInstall with that directory as the target.
+
+Note that using ``--editable`` stops EasyInstall from actually building or
+installing the package; it just finds, obtains, and possibly unpacks it for
+you. This allows you to make changes to the package if necessary, and to
+either install it in development mode using ``setup.py develop`` (if the
+package uses setuptools, that is), or by running ``easy_install projectdir``
+(where ``projectdir`` is the subdirectory EasyInstall created for the
+downloaded package.
+
+In order to use ``--editable`` (``-e`` for short), you *must* also supply a
+``--build-directory`` (``-b`` for short). The project will be placed in a
+subdirectory of the build directory. The subdirectory will have the same
+name as the project itself, but in all-lowercase. If a file or directory of
+that name already exists, EasyInstall will print an error message and exit.
+
+Also, when using ``--editable``, you cannot use URLs or filenames as arguments.
+You *must* specify project names (and optional version requirements) so that
+EasyInstall knows what directory name(s) to create. If you need to force
+EasyInstall to use a particular URL or filename, you should specify it as a
+``--find-links`` item (``-f`` for short), and then also specify
+the project name, e.g.::
+
+ easy_install -eb ~/projects \
+ -fhttp://prdownloads.sourceforge.net/ctypes/ctypes-0.9.6.tar.gz?download \
+ ctypes==0.9.6
+
+
+Dealing with Installation Conflicts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+(NOTE: As of 0.6a11, this section is obsolete; it is retained here only so that
+people using older versions of EasyInstall can consult it. As of version
+0.6a11, installation conflicts are handled automatically without deleting the
+old or system-installed packages, and without ignoring the issue. Instead,
+eggs are automatically shifted to the front of ``sys.path`` using special
+code added to the ``easy-install.pth`` file. So, if you are using version
+0.6a11 or better of setuptools, you do not need to worry about conflicts,
+and the following issues do not apply to you.)
+
+EasyInstall installs distributions in a "managed" way, such that each
+distribution can be independently activated or deactivated on ``sys.path``.
+However, packages that were not installed by EasyInstall are "unmanaged",
+in that they usually live all in one directory and cannot be independently
+activated or deactivated.
+
+As a result, if you are using EasyInstall to upgrade an existing package, or
+to install a package with the same name as an existing package, EasyInstall
+will warn you of the conflict. (This is an improvement over ``setup.py
+install``, becuase the ``distutils`` just install new packages on top of old
+ones, possibly combining two unrelated packages or leaving behind modules that
+have been deleted in the newer version of the package.)
+
+By default, EasyInstall will stop the installation if it detects a conflict
+between an existing, "unmanaged" package, and a module or package in any of
+the distributions you're installing. It will display a list of all of the
+existing files and directories that would need to be deleted for the new
+package to be able to function correctly. You can then either delete these
+conflicting files and directories yourself and re-run EasyInstall, or you can
+just use the ``--delete-conflicting`` or ``--ignore-conflicts-at-my-risk``
+options, as described under `Command-Line Options`_, below.
+
+Of course, once you've replaced all of your existing "unmanaged" packages with
+versions managed by EasyInstall, you won't have any more conflicts to worry
+about!
+
+
+Compressed Installation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+EasyInstall tries to install packages in zipped form, if it can. Zipping
+packages can improve Python's overall import performance if you're not using
+the ``--multi-version`` option, because Python processes zipfile entries on
+``sys.path`` much faster than it does directories.
+
+As of version 0.5a9, EasyInstall analyzes packages to determine whether they
+can be safely installed as a zipfile, and then acts on its analysis. (Previous
+versions would not install a package as a zipfile unless you used the
+``--zip-ok`` option.)
+
+The current analysis approach is fairly conservative; it currenly looks for:
+
+ * Any use of the ``__file__`` or ``__path__`` variables (which should be
+ replaced with ``pkg_resources`` API calls)
+
+ * Possible use of ``inspect`` functions that expect to manipulate source files
+ (e.g. ``inspect.getsource()``)
+
+ * Top-level modules that might be scripts used with ``python -m`` (Python 2.4)
+
+If any of the above are found in the package being installed, EasyInstall will
+assume that the package cannot be safely run from a zipfile, and unzip it to
+a directory instead. You can override this analysis with the ``-zip-ok`` flag,
+which will tell EasyInstall to install the package as a zipfile anyway. Or,
+you can use the ``--always-unzip`` flag, in which case EasyInstall will always
+unzip, even if its analysis says the package is safe to run as a zipfile.
+
+Normally, however, it is simplest to let EasyInstall handle the determination
+of whether to zip or unzip, and only specify overrides when needed to work
+around a problem. If you find you need to override EasyInstall's guesses, you
+may want to contact the package author and the EasyInstall maintainers, so that
+they can make appropriate changes in future versions.
+
+(Note: If a package uses ``setuptools`` in its setup script, the package author
+has the option to declare the package safe or unsafe for zipped usage via the
+``zip_safe`` argument to ``setup()``. If the package author makes such a
+declaration, EasyInstall believes the package's author and does not perform its
+own analysis. However, your command-line option, if any, will still override
+the package author's choice.)
+
+
+Reference Manual
+================
+
+Configuration Files
+-------------------
+
+(New in 0.4a2)
+
+You may specify default options for EasyInstall using the standard
+distutils configuration files, under the command heading ``easy_install``.
+EasyInstall will look first for a ``setup.cfg`` file in the current directory,
+then a ``~/.pydistutils.cfg`` or ``$HOME\\pydistutils.cfg`` (on Unix-like OSes
+and Windows, respectively), and finally a ``distutils.cfg`` file in the
+``distutils`` package directory. Here's a simple example:
+
+.. code-block:: ini
+
+ [easy_install]
+
+ # set the default location to install packages
+ install_dir = /home/me/lib/python
+
+ # Notice that indentation can be used to continue an option
+ # value; this is especially useful for the "--find-links"
+ # option, which tells easy_install to use download links on
+ # these pages before consulting PyPI:
+ #
+ find_links = http://sqlobject.org/
+ http://peak.telecommunity.com/dist/
+
+In addition to accepting configuration for its own options under
+``[easy_install]``, EasyInstall also respects defaults specified for other
+distutils commands. For example, if you don't set an ``install_dir`` for
+``[easy_install]``, but *have* set an ``install_lib`` for the ``[install]``
+command, this will become EasyInstall's default installation directory. Thus,
+if you are already using distutils configuration files to set default install
+locations, build options, etc., EasyInstall will respect your existing settings
+until and unless you override them explicitly in an ``[easy_install]`` section.
+
+For more information, see also the current Python documentation on the `use and
+location of distutils configuration files <http://docs.python.org/inst/config-syntax.html>`_.
+
+Notice that ``easy_install`` will use the ``setup.cfg`` from the current
+working directory only if it was triggered from ``setup.py`` through the
+``install_requires`` option. The standalone command will not use that file.
+
+Command-Line Options
+--------------------
+
+``--zip-ok, -z``
+ Install all packages as zip files, even if they are marked as unsafe for
+ running as a zipfile. This can be useful when EasyInstall's analysis
+ of a non-setuptools package is too conservative, but keep in mind that
+ the package may not work correctly. (Changed in 0.5a9; previously this
+ option was required in order for zipped installation to happen at all.)
+
+``--always-unzip, -Z``
+ Don't install any packages as zip files, even if the packages are marked
+ as safe for running as a zipfile. This can be useful if a package does
+ something unsafe, but not in a way that EasyInstall can easily detect.
+ EasyInstall's default analysis is currently very conservative, however, so
+ you should only use this option if you've had problems with a particular
+ package, and *after* reporting the problem to the package's maintainer and
+ to the EasyInstall maintainers.
+
+ (Note: the ``-z/-Z`` options only affect the installation of newly-built
+ or downloaded packages that are not already installed in the target
+ directory; if you want to convert an existing installed version from
+ zipped to unzipped or vice versa, you'll need to delete the existing
+ version first, and re-run EasyInstall.)
+
+``--multi-version, -m``
+ "Multi-version" mode. Specifying this option prevents ``easy_install`` from
+ adding an ``easy-install.pth`` entry for the package being installed, and
+ if an entry for any version the package already exists, it will be removed
+ upon successful installation. In multi-version mode, no specific version of
+ the package is available for importing, unless you use
+ ``pkg_resources.require()`` to put it on ``sys.path``. This can be as
+ simple as::
+
+ from pkg_resources import require
+ require("SomePackage", "OtherPackage", "MyPackage")
+
+ which will put the latest installed version of the specified packages on
+ ``sys.path`` for you. (For more advanced uses, like selecting specific
+ versions and enabling optional dependencies, see the ``pkg_resources`` API
+ doc.)
+
+ Changed in 0.6a10: this option is no longer silently enabled when
+ installing to a non-PYTHONPATH, non-"site" directory. You must always
+ explicitly use this option if you want it to be active.
+
+``--upgrade, -U`` (New in 0.5a4)
+ By default, EasyInstall only searches online if a project/version
+ requirement can't be met by distributions already installed
+ on sys.path or the installation directory. However, if you supply the
+ ``--upgrade`` or ``-U`` flag, EasyInstall will always check the package
+ index and ``--find-links`` URLs before selecting a version to install. In
+ this way, you can force EasyInstall to use the latest available version of
+ any package it installs (subject to any version requirements that might
+ exclude such later versions).
+
+``--install-dir=DIR, -d DIR``
+ Set the installation directory. It is up to you to ensure that this
+ directory is on ``sys.path`` at runtime, and to use
+ ``pkg_resources.require()`` to enable the installed package(s) that you
+ need.
+
+ (New in 0.4a2) If this option is not directly specified on the command line
+ or in a distutils configuration file, the distutils default installation
+ location is used. Normally, this would be the ``site-packages`` directory,
+ but if you are using distutils configuration files, setting things like
+ ``prefix`` or ``install_lib``, then those settings are taken into
+ account when computing the default installation directory, as is the
+ ``--prefix`` option.
+
+``--script-dir=DIR, -s DIR``
+ Set the script installation directory. If you don't supply this option
+ (via the command line or a configuration file), but you *have* supplied
+ an ``--install-dir`` (via command line or config file), then this option
+ defaults to the same directory, so that the scripts will be able to find
+ their associated package installation. Otherwise, this setting defaults
+ to the location where the distutils would normally install scripts, taking
+ any distutils configuration file settings into account.
+
+``--exclude-scripts, -x``
+ Don't install scripts. This is useful if you need to install multiple
+ versions of a package, but do not want to reset the version that will be
+ run by scripts that are already installed.
+
+``--user`` (New in 0.6.11)
+ Use the the user-site-packages as specified in :pep:`370`
+ instead of the global site-packages.
+
+``--always-copy, -a`` (New in 0.5a4)
+ Copy all needed distributions to the installation directory, even if they
+ are already present in a directory on sys.path. In older versions of
+ EasyInstall, this was the default behavior, but now you must explicitly
+ request it. By default, EasyInstall will no longer copy such distributions
+ from other sys.path directories to the installation directory, unless you
+ explicitly gave the distribution's filename on the command line.
+
+ Note that as of 0.6a10, using this option excludes "system" and
+ "development" eggs from consideration because they can't be reliably
+ copied. This may cause EasyInstall to choose an older version of a package
+ than what you expected, or it may cause downloading and installation of a
+ fresh copy of something that's already installed. You will see warning
+ messages for any eggs that EasyInstall skips, before it falls back to an
+ older version or attempts to download a fresh copy.
+
+``--find-links=URLS_OR_FILENAMES, -f URLS_OR_FILENAMES``
+ Scan the specified "download pages" or directories for direct links to eggs
+ or other distributions. Any existing file or directory names or direct
+ download URLs are immediately added to EasyInstall's search cache, and any
+ indirect URLs (ones that don't point to eggs or other recognized archive
+ formats) are added to a list of additional places to search for download
+ links. As soon as EasyInstall has to go online to find a package (either
+ because it doesn't exist locally, or because ``--upgrade`` or ``-U`` was
+ used), the specified URLs will be downloaded and scanned for additional
+ direct links.
+
+ Eggs and archives found by way of ``--find-links`` are only downloaded if
+ they are needed to meet a requirement specified on the command line; links
+ to unneeded packages are ignored.
+
+ If all requested packages can be found using links on the specified
+ download pages, the Python Package Index will not be consulted unless you
+ also specified the ``--upgrade`` or ``-U`` option.
+
+ (Note: if you want to refer to a local HTML file containing links, you must
+ use a ``file:`` URL, as filenames that do not refer to a directory, egg, or
+ archive are ignored.)
+
+ You may specify multiple URLs or file/directory names with this option,
+ separated by whitespace. Note that on the command line, you will probably
+ have to surround the URL list with quotes, so that it is recognized as a
+ single option value. You can also specify URLs in a configuration file;
+ see `Configuration Files`_, above.
+
+ Changed in 0.6a10: previously all URLs and directories passed to this
+ option were scanned as early as possible, but from 0.6a10 on, only
+ directories and direct archive links are scanned immediately; URLs are not
+ retrieved unless a package search was already going to go online due to a
+ package not being available locally, or due to the use of the ``--update``
+ or ``-U`` option.
+
+``--no-find-links`` Blocks the addition of any link. (New in Distribute 0.6.11)
+ This is useful if you want to avoid adding links defined in a project
+ easy_install is installing (wether it's a requested project or a
+ dependency.). When used, ``--find-links`` is ignored.
+
+``--delete-conflicting, -D`` (Removed in 0.6a11)
+ (As of 0.6a11, this option is no longer necessary; please do not use it!)
+
+ If you are replacing a package that was previously installed *without*
+ using EasyInstall, the old version may end up on ``sys.path`` before the
+ version being installed with EasyInstall. EasyInstall will normally abort
+ the installation of a package if it detects such a conflict, and ask you to
+ manually remove the conflicting files or directories. If you specify this
+ option, however, EasyInstall will attempt to delete the files or
+ directories itself, and then proceed with the installation.
+
+``--ignore-conflicts-at-my-risk`` (Removed in 0.6a11)
+ (As of 0.6a11, this option is no longer necessary; please do not use it!)
+
+ Ignore conflicting packages and proceed with installation anyway, even
+ though it means the package probably won't work properly. If the
+ conflicting package is in a directory you can't write to, this may be your
+ only option, but you will need to take more invasive measures to get the
+ installed package to work, like manually adding it to ``PYTHONPATH`` or to
+ ``sys.path`` at runtime.
+
+``--index-url=URL, -i URL`` (New in 0.4a1; default changed in 0.6c7)
+ Specifies the base URL of the Python Package Index. The default is
+ http://pypi.python.org/simple if not specified. When a package is requested
+ that is not locally available or linked from a ``--find-links`` download
+ page, the package index will be searched for download pages for the needed
+ package, and those download pages will be searched for links to download
+ an egg or source distribution.
+
+``--editable, -e`` (New in 0.6a1)
+ Only find and download source distributions for the specified projects,
+ unpacking them to subdirectories of the specified ``--build-directory``.
+ EasyInstall will not actually build or install the requested projects or
+ their dependencies; it will just find and extract them for you. See
+ `Editing and Viewing Source Packages`_ above for more details.
+
+``--build-directory=DIR, -b DIR`` (UPDATED in 0.6a1)
+ Set the directory used to build source packages. If a package is built
+ from a source distribution or checkout, it will be extracted to a
+ subdirectory of the specified directory. The subdirectory will have the
+ same name as the extracted distribution's project, but in all-lowercase.
+ If a file or directory of that name already exists in the given directory,
+ a warning will be printed to the console, and the build will take place in
+ a temporary directory instead.
+
+ This option is most useful in combination with the ``--editable`` option,
+ which forces EasyInstall to *only* find and extract (but not build and
+ install) source distributions. See `Editing and Viewing Source Packages`_,
+ above, for more information.
+
+``--verbose, -v, --quiet, -q`` (New in 0.4a4)
+ Control the level of detail of EasyInstall's progress messages. The
+ default detail level is "info", which prints information only about
+ relatively time-consuming operations like running a setup script, unpacking
+ an archive, or retrieving a URL. Using ``-q`` or ``--quiet`` drops the
+ detail level to "warn", which will only display installation reports,
+ warnings, and errors. Using ``-v`` or ``--verbose`` increases the detail
+ level to include individual file-level operations, link analysis messages,
+ and distutils messages from any setup scripts that get run. If you include
+ the ``-v`` option more than once, the second and subsequent uses are passed
+ down to any setup scripts, increasing the verbosity of their reporting as
+ well.
+
+``--dry-run, -n`` (New in 0.4a4)
+ Don't actually install the package or scripts. This option is passed down
+ to any setup scripts run, so packages should not actually build either.
+ This does *not* skip downloading, nor does it skip extracting source
+ distributions to a temporary/build directory.
+
+``--optimize=LEVEL``, ``-O LEVEL`` (New in 0.4a4)
+ If you are installing from a source distribution, and are *not* using the
+ ``--zip-ok`` option, this option controls the optimization level for
+ compiling installed ``.py`` files to ``.pyo`` files. It does not affect
+ the compilation of modules contained in ``.egg`` files, only those in
+ ``.egg`` directories. The optimization level can be set to 0, 1, or 2;
+ the default is 0 (unless it's set under ``install`` or ``install_lib`` in
+ one of your distutils configuration files).
+
+``--record=FILENAME`` (New in 0.5a4)
+ Write a record of all installed files to FILENAME. This is basically the
+ same as the same option for the standard distutils "install" command, and
+ is included for compatibility with tools that expect to pass this option
+ to "setup.py install".
+
+``--site-dirs=DIRLIST, -S DIRLIST`` (New in 0.6a1)
+ Specify one or more custom "site" directories (separated by commas).
+ "Site" directories are directories where ``.pth`` files are processed, such
+ as the main Python ``site-packages`` directory. As of 0.6a10, EasyInstall
+ automatically detects whether a given directory processes ``.pth`` files
+ (or can be made to do so), so you should not normally need to use this
+ option. It is is now only necessary if you want to override EasyInstall's
+ judgment and force an installation directory to be treated as if it
+ supported ``.pth`` files.
+
+``--no-deps, -N`` (New in 0.6a6)
+ Don't install any dependencies. This is intended as a convenience for
+ tools that wrap eggs in a platform-specific packaging system. (We don't
+ recommend that you use it for anything else.)
+
+``--allow-hosts=PATTERNS, -H PATTERNS`` (New in 0.6a6)
+ Restrict downloading and spidering to hosts matching the specified glob
+ patterns. E.g. ``-H *.python.org`` restricts web access so that only
+ packages listed and downloadable from machines in the ``python.org``
+ domain. The glob patterns must match the *entire* user/host/port section of
+ the target URL(s). For example, ``*.python.org`` will NOT accept a URL
+ like ``http://python.org/foo`` or ``http://www.python.org:8080/``.
+ Multiple patterns can be specified by separting them with commas. The
+ default pattern is ``*``, which matches anything.
+
+ In general, this option is mainly useful for blocking EasyInstall's web
+ access altogether (e.g. ``-Hlocalhost``), or to restrict it to an intranet
+ or other trusted site. EasyInstall will do the best it can to satisfy
+ dependencies given your host restrictions, but of course can fail if it
+ can't find suitable packages. EasyInstall displays all blocked URLs, so
+ that you can adjust your ``--allow-hosts`` setting if it is more strict
+ than you intended. Some sites may wish to define a restrictive default
+ setting for this option in their `configuration files`_, and then manually
+ override the setting on the command line as needed.
+
+``--prefix=DIR`` (New in 0.6a10)
+ Use the specified directory as a base for computing the default
+ installation and script directories. On Windows, the resulting default
+ directories will be ``prefix\\Lib\\site-packages`` and ``prefix\\Scripts``,
+ while on other platforms the defaults will be
+ ``prefix/lib/python2.X/site-packages`` (with the appropriate version
+ substituted) for libraries and ``prefix/bin`` for scripts.
+
+ Note that the ``--prefix`` option only sets the *default* installation and
+ script directories, and does not override the ones set on the command line
+ or in a configuration file.
+
+``--local-snapshots-ok, -l`` (New in 0.6c6)
+ Normally, EasyInstall prefers to only install *released* versions of
+ projects, not in-development ones, because such projects may not
+ have a currently-valid version number. So, it usually only installs them
+ when their ``setup.py`` directory is explicitly passed on the command line.
+
+ However, if this option is used, then any in-development projects that were
+ installed using the ``setup.py develop`` command, will be used to build
+ eggs, effectively upgrading the "in-development" project to a snapshot
+ release. Normally, this option is used only in conjunction with the
+ ``--always-copy`` option to create a distributable snapshot of every egg
+ needed to run an application.
+
+ Note that if you use this option, you must make sure that there is a valid
+ version number (such as an SVN revision number tag) for any in-development
+ projects that may be used, as otherwise EasyInstall may not be able to tell
+ what version of the project is "newer" when future installations or
+ upgrades are attempted.
+
+
+.. _non-root installation:
+
+Custom Installation Locations
+-----------------------------
+
+By default, EasyInstall installs python packages into Python's main ``site-packages`` directory,
+and manages them using a custom ``.pth`` file in that same directory.
+
+Very often though, a user or developer wants ``easy_install`` to install and manage python packages
+in an alternative location, usually for one of 3 reasons:
+
+1. They don't have access to write to the main Python site-packages directory.
+
+2. They want a user-specific stash of packages, that is not visible to other users.
+
+3. They want to isolate a set of packages to a specific python application, usually to minimize
+ the possibility of version conflicts.
+
+Historically, there have been many approaches to achieve custom installation.
+The following section lists only the easiest and most relevant approaches [1]_.
+
+`Use the "--user" option`_
+
+`Use the "--user" option and customize "PYTHONUSERBASE"`_
+
+`Use "virtualenv"`_
+
+.. [1] There are older ways to achieve custom installation using various ``easy_install`` and ``setup.py install`` options, combined with ``PYTHONPATH`` and/or ``PYTHONUSERBASE`` alterations, but all of these are effectively deprecated by the User scheme brought in by `PEP-370`_ in Python 2.6.
+
+.. _PEP-370: http://www.python.org/dev/peps/pep-0370/
+
+
+Use the "--user" option
+~~~~~~~~~~~~~~~~~~~~~~~
+With Python 2.6 came the User scheme for installation, which means that all
+python distributions support an alternative install location that is specific to a user [2]_ [3]_.
+The Default location for each OS is explained in the python documentation
+for the ``site.USER_BASE`` variable. This mode of installation can be turned on by
+specifying the ``--user`` option to ``setup.py install`` or ``easy_install``.
+This approach serves the need to have a user-specific stash of packages.
+
+.. [2] Prior to Python2.6, Mac OS X offered a form of the User scheme. That is now subsumed into the User scheme introduced in Python 2.6.
+.. [3] Prior to the User scheme, there was the Home scheme, which is still available, but requires more effort than the User scheme to get packages recognized.
+
+Use the "--user" option and customize "PYTHONUSERBASE"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The User scheme install location can be customized by setting the ``PYTHONUSERBASE`` environment
+variable, which updates the value of ``site.USER_BASE``. To isolate packages to a specific
+application, simply set the OS environment of that application to a specific value of
+``PYTHONUSERBASE``, that contains just those packages.
+
+Use "virtualenv"
+~~~~~~~~~~~~~~~~
+"virtualenv" is a 3rd-party python package that effectively "clones" a python installation, thereby
+creating an isolated location to intall packages. The evolution of "virtualenv" started before the existence
+of the User installation scheme. "virtualenv" provides a version of ``easy_install`` that is
+scoped to the cloned python install and is used in the normal way. "virtualenv" does offer various features
+that the User installation scheme alone does not provide, e.g. the ability to hide the main python site-packages.
+
+Please refer to the `virtualenv`_ documentation for more details.
+
+.. _virtualenv: http://pypi.python.org/pypi/virtualenv
+
+
+
+Package Index "API"
+-------------------
+
+Custom package indexes (and PyPI) must follow the following rules for
+EasyInstall to be able to look up and download packages:
+
+1. Except where stated otherwise, "pages" are HTML or XHTML, and "links"
+ refer to ``href`` attributes.
+
+2. Individual project version pages' URLs must be of the form
+ ``base/projectname/version``, where ``base`` is the package index's base URL.
+
+3. Omitting the ``/version`` part of a project page's URL (but keeping the
+ trailing ``/``) should result in a page that is either:
+
+ a) The single active version of that project, as though the version had been
+ explicitly included, OR
+
+ b) A page with links to all of the active version pages for that project.
+
+4. Individual project version pages should contain direct links to downloadable
+ distributions where possible. It is explicitly permitted for a project's
+ "long_description" to include URLs, and these should be formatted as HTML
+ links by the package index, as EasyInstall does no special processing to
+ identify what parts of a page are index-specific and which are part of the
+ project's supplied description.
+
+5. Where available, MD5 information should be added to download URLs by
+ appending a fragment identifier of the form ``#md5=...``, where ``...`` is
+ the 32-character hex MD5 digest. EasyInstall will verify that the
+ downloaded file's MD5 digest matches the given value.
+
+6. Individual project version pages should identify any "homepage" or
+ "download" URLs using ``rel="homepage"`` and ``rel="download"`` attributes
+ on the HTML elements linking to those URLs. Use of these attributes will
+ cause EasyInstall to always follow the provided links, unless it can be
+ determined by inspection that they are downloadable distributions. If the
+ links are not to downloadable distributions, they are retrieved, and if they
+ are HTML, they are scanned for download links. They are *not* scanned for
+ additional "homepage" or "download" links, as these are only processed for
+ pages that are part of a package index site.
+
+7. The root URL of the index, if retrieved with a trailing ``/``, must result
+ in a page containing links to *all* projects' active version pages.
+
+ (Note: This requirement is a workaround for the absence of case-insensitive
+ ``safe_name()`` matching of project names in URL paths. If project names are
+ matched in this fashion (e.g. via the PyPI server, mod_rewrite, or a similar
+ mechanism), then it is not necessary to include this all-packages listing
+ page.)
+
+8. If a package index is accessed via a ``file://`` URL, then EasyInstall will
+ automatically use ``index.html`` files, if present, when trying to read a
+ directory with a trailing ``/`` on the URL.
+
+
+Backward Compatibility
+~~~~~~~~~~~~~~~~~~~~~~
+
+Package indexes that wish to support setuptools versions prior to 0.6b4 should
+also follow these rules:
+
+* Homepage and download links must be preceded with ``"<th>Home Page"`` or
+ ``"<th>Download URL"``, in addition to (or instead of) the ``rel=""``
+ attributes on the actual links. These marker strings do not need to be
+ visible, or uncommented, however! For example, the following is a valid
+ homepage link that will work with any version of setuptools::
+
+ <li>
+ <strong>Home Page:</strong>
+ <!-- <th>Home Page -->
+ <a rel="homepage" href="http://sqlobject.org">http://sqlobject.org</a>
+ </li>
+
+ Even though the marker string is in an HTML comment, older versions of
+ EasyInstall will still "see" it and know that the link that follows is the
+ project's home page URL.
+
+* The pages described by paragraph 3(b) of the preceding section *must*
+ contain the string ``"Index of Packages</title>"`` somewhere in their text.
+ This can be inside of an HTML comment, if desired, and it can be anywhere
+ in the page. (Note: this string MUST NOT appear on normal project pages, as
+ described in paragraphs 2 and 3(a)!)
+
+In addition, for compatibility with PyPI versions that do not use ``#md5=``
+fragment IDs, EasyInstall uses the following regular expression to match PyPI's
+displayed MD5 info (broken onto two lines for readability)::
+
+ <a href="([^"#]+)">([^<]+)</a>\n\s+\(<a href="[^?]+\?:action=show_md5
+ &digest=([0-9a-f]{32})">md5</a>\)
+
+History
+=======
+
+0.6c9
+ * Fixed ``win32.exe`` support for .pth files, so unnecessary directory nesting
+ is flattened out in the resulting egg. (There was a case-sensitivity
+ problem that affected some distributions, notably ``pywin32``.)
+
+ * Prevent ``--help-commands`` and other junk from showing under Python 2.5
+ when running ``easy_install --help``.
+
+ * Fixed GUI scripts sometimes not executing on Windows
+
+ * Fixed not picking up dependency links from recursive dependencies.
+
+ * Only make ``.py``, ``.dll`` and ``.so`` files executable when unpacking eggs
+
+ * Changes for Jython compatibility
+
+ * Improved error message when a requirement is also a directory name, but the
+ specified directory is not a source package.
+
+ * Fixed ``--allow-hosts`` option blocking ``file:`` URLs
+
+ * Fixed HTTP SVN detection failing when the page title included a project
+ name (e.g. on SourceForge-hosted SVN)
+
+ * Fix Jython script installation to handle ``#!`` lines better when
+ ``sys.executable`` is a script.
+
+ * Removed use of deprecated ``md5`` module if ``hashlib`` is available
+
+ * Keep site directories (e.g. ``site-packages``) from being included in
+ ``.pth`` files.
+
+0.6c7
+ * ``ftp:`` download URLs now work correctly.
+
+ * The default ``--index-url`` is now ``http://pypi.python.org/simple``, to use
+ the Python Package Index's new simpler (and faster!) REST API.
+
+0.6c6
+ * EasyInstall no longer aborts the installation process if a URL it wants to
+ retrieve can't be downloaded, unless the URL is an actual package download.
+ Instead, it issues a warning and tries to keep going.
+
+ * Fixed distutils-style scripts originally built on Windows having their line
+ endings doubled when installed on any platform.
+
+ * Added ``--local-snapshots-ok`` flag, to allow building eggs from projects
+ installed using ``setup.py develop``.
+
+ * Fixed not HTML-decoding URLs scraped from web pages
+
+0.6c5
+ * Fixed ``.dll`` files on Cygwin not having executable permisions when an egg
+ is installed unzipped.
+
+0.6c4
+ * Added support for HTTP "Basic" authentication using ``http://user:pass@host``
+ URLs. If a password-protected page contains links to the same host (and
+ protocol), those links will inherit the credentials used to access the
+ original page.
+
+ * Removed all special support for Sourceforge mirrors, as Sourceforge's
+ mirror system now works well for non-browser downloads.
+
+ * Fixed not recognizing ``win32.exe`` installers that included a custom
+ bitmap.
+
+ * Fixed not allowing ``os.open()`` of paths outside the sandbox, even if they
+ are opened read-only (e.g. reading ``/dev/urandom`` for random numbers, as
+ is done by ``os.urandom()`` on some platforms).
+
+ * Fixed a problem with ``.pth`` testing on Windows when ``sys.executable``
+ has a space in it (e.g., the user installed Python to a ``Program Files``
+ directory).
+
+0.6c3
+ * You can once again use "python -m easy_install" with Python 2.4 and above.
+
+ * Python 2.5 compatibility fixes added.
+
+0.6c2
+ * Windows script wrappers now support quoted arguments and arguments
+ containing spaces. (Patch contributed by Jim Fulton.)
+
+ * The ``ez_setup.py`` script now actually works when you put a setuptools
+ ``.egg`` alongside it for bootstrapping an offline machine.
+
+ * A writable installation directory on ``sys.path`` is no longer required to
+ download and extract a source distribution using ``--editable``.
+
+ * Generated scripts now use ``-x`` on the ``#!`` line when ``sys.executable``
+ contains non-ASCII characters, to prevent deprecation warnings about an
+ unspecified encoding when the script is run.
+
+0.6c1
+ * EasyInstall now includes setuptools version information in the
+ ``User-Agent`` string sent to websites it visits.
+
+0.6b4
+ * Fix creating Python wrappers for non-Python scripts
+
+ * Fix ``ftp://`` directory listing URLs from causing a crash when used in the
+ "Home page" or "Download URL" slots on PyPI.
+
+ * Fix ``sys.path_importer_cache`` not being updated when an existing zipfile
+ or directory is deleted/overwritten.
+
+ * Fix not recognizing HTML 404 pages from package indexes.
+
+ * Allow ``file://`` URLs to be used as a package index. URLs that refer to
+ directories will use an internally-generated directory listing if there is
+ no ``index.html`` file in the directory.
+
+ * Allow external links in a package index to be specified using
+ ``rel="homepage"`` or ``rel="download"``, without needing the old
+ PyPI-specific visible markup.
+
+ * Suppressed warning message about possibly-misspelled project name, if an egg
+ or link for that project name has already been seen.
+
+0.6b3
+ * Fix local ``--find-links`` eggs not being copied except with
+ ``--always-copy``.
+
+ * Fix sometimes not detecting local packages installed outside of "site"
+ directories.
+
+ * Fix mysterious errors during initial ``setuptools`` install, caused by
+ ``ez_setup`` trying to run ``easy_install`` twice, due to a code fallthru
+ after deleting the egg from which it's running.
+
+0.6b2
+ * Don't install or update a ``site.py`` patch when installing to a
+ ``PYTHONPATH`` directory with ``--multi-version``, unless an
+ ``easy-install.pth`` file is already in use there.
+
+ * Construct ``.pth`` file paths in such a way that installing an egg whose
+ name begins with ``import`` doesn't cause a syntax error.
+
+ * Fixed a bogus warning message that wasn't updated since the 0.5 versions.
+
+0.6b1
+ * Better ambiguity management: accept ``#egg`` name/version even if processing
+ what appears to be a correctly-named distutils file, and ignore ``.egg``
+ files with no ``-``, since valid Python ``.egg`` files always have a version
+ number (but Scheme eggs often don't).
+
+ * Support ``file://`` links to directories in ``--find-links``, so that
+ easy_install can build packages from local source checkouts.
+
+ * Added automatic retry for Sourceforge mirrors. The new download process is
+ to first just try dl.sourceforge.net, then randomly select mirror IPs and
+ remove ones that fail, until something works. The removed IPs stay removed
+ for the remainder of the run.
+
+ * Ignore bdist_dumb distributions when looking at download URLs.
+
+0.6a11
+ * Process ``dependency_links.txt`` if found in a distribution, by adding the
+ URLs to the list for scanning.
+
+ * Use relative paths in ``.pth`` files when eggs are being installed to the
+ same directory as the ``.pth`` file. This maximizes portability of the
+ target directory when building applications that contain eggs.
+
+ * Added ``easy_install-N.N`` script(s) for convenience when using multiple
+ Python versions.
+
+ * Added automatic handling of installation conflicts. Eggs are now shifted to
+ the front of sys.path, in an order consistent with where they came from,
+ making EasyInstall seamlessly co-operate with system package managers.
+
+ The ``--delete-conflicting`` and ``--ignore-conflicts-at-my-risk`` options
+ are now no longer necessary, and will generate warnings at the end of a
+ run if you use them.
+
+ * Don't recursively traverse subdirectories given to ``--find-links``.
+
+0.6a10
+ * Added exhaustive testing of the install directory, including a spawn test
+ for ``.pth`` file support, and directory writability/existence checks. This
+ should virtually eliminate the need to set or configure ``--site-dirs``.
+
+ * Added ``--prefix`` option for more do-what-I-mean-ishness in the absence of
+ RTFM-ing. :)
+
+ * Enhanced ``PYTHONPATH`` support so that you don't have to put any eggs on it
+ manually to make it work. ``--multi-version`` is no longer a silent
+ default; you must explicitly use it if installing to a non-PYTHONPATH,
+ non-"site" directory.
+
+ * Expand ``$variables`` used in the ``--site-dirs``, ``--build-directory``,
+ ``--install-dir``, and ``--script-dir`` options, whether on the command line
+ or in configuration files.
+
+ * Improved SourceForge mirror processing to work faster and be less affected
+ by transient HTML changes made by SourceForge.
+
+ * PyPI searches now use the exact spelling of requirements specified on the
+ command line or in a project's ``install_requires``. Previously, a
+ normalized form of the name was used, which could lead to unnecessary
+ full-index searches when a project's name had an underscore (``_``) in it.
+
+ * EasyInstall can now download bare ``.py`` files and wrap them in an egg,
+ as long as you include an ``#egg=name-version`` suffix on the URL, or if
+ the ``.py`` file is listed as the "Download URL" on the project's PyPI page.
+ This allows third parties to "package" trivial Python modules just by
+ linking to them (e.g. from within their own PyPI page or download links
+ page).
+
+ * The ``--always-copy`` option now skips "system" and "development" eggs since
+ they can't be reliably copied. Note that this may cause EasyInstall to
+ choose an older version of a package than what you expected, or it may cause
+ downloading and installation of a fresh version of what's already installed.
+
+ * The ``--find-links`` option previously scanned all supplied URLs and
+ directories as early as possible, but now only directories and direct
+ archive links are scanned immediately. URLs are not retrieved unless a
+ package search was already going to go online due to a package not being
+ available locally, or due to the use of the ``--update`` or ``-U`` option.
+
+ * Fixed the annoying ``--help-commands`` wart.
+
+0.6a9
+ * Fixed ``.pth`` file processing picking up nested eggs (i.e. ones inside
+ "baskets") when they weren't explicitly listed in the ``.pth`` file.
+
+ * If more than one URL appears to describe the exact same distribution, prefer
+ the shortest one. This helps to avoid "table of contents" CGI URLs like the
+ ones on effbot.org.
+
+ * Quote arguments to python.exe (including python's path) to avoid problems
+ when Python (or a script) is installed in a directory whose name contains
+ spaces on Windows.
+
+ * 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
+ * Update for changed SourceForge mirror format
+
+ * Fixed not installing dependencies for some packages fetched via Subversion
+
+ * Fixed dependency installation with ``--always-copy`` not using the same
+ dependency resolution procedure as other operations.
+
+ * Fixed not fully removing temporary directories on Windows, if a Subversion
+ checkout left read-only files behind
+
+ * Fixed some problems building extensions when Pyrex was installed, especially
+ with Python 2.4 and/or packages using SWIG.
+
+0.6a7
+ * Fixed not being able to install Windows script wrappers using Python 2.3
+
+0.6a6
+ * Added support for "traditional" PYTHONPATH-based non-root installation, and
+ also the convenient ``virtual-python.py`` script, based on a contribution
+ by Ian Bicking. The setuptools egg now contains a hacked ``site`` module
+ that makes the PYTHONPATH-based approach work with .pth files, so that you
+ can get the full EasyInstall feature set on such installations.
+
+ * Added ``--no-deps`` and ``--allow-hosts`` options.
+
+ * Improved Windows ``.exe`` script wrappers so that the script can have the
+ same name as a module without confusing Python.
+
+ * Changed dependency processing so that it's breadth-first, allowing a
+ depender's preferences to override those of a dependee, to prevent conflicts
+ when a lower version is acceptable to the dependee, but not the depender.
+ Also, ensure that currently installed/selected packages aren't given
+ precedence over ones desired by a package being installed, which could
+ cause conflict errors.
+
+0.6a3
+ * Improved error message when trying to use old ways of running
+ ``easy_install``. Removed the ability to run via ``python -m`` or by
+ running ``easy_install.py``; ``easy_install`` is the command to run on all
+ supported platforms.
+
+ * Improved wrapper script generation and runtime initialization so that a
+ VersionConflict doesn't occur if you later install a competing version of a
+ needed package as the default version of that package.
+
+ * Fixed a problem parsing version numbers in ``#egg=`` links.
+
+0.6a2
+ * EasyInstall can now install "console_scripts" defined by packages that use
+ ``setuptools`` and define appropriate entry points. On Windows, console
+ scripts get an ``.exe`` wrapper so you can just type their name. On other
+ platforms, the scripts are installed without a file extension.
+
+ * Using ``python -m easy_install`` or running ``easy_install.py`` is now
+ DEPRECATED, since an ``easy_install`` wrapper is now available on all
+ platforms.
+
+0.6a1
+ * EasyInstall now does MD5 validation of downloads from PyPI, or from any link
+ that has an "#md5=..." trailer with a 32-digit lowercase hex md5 digest.
+
+ * EasyInstall now handles symlinks in target directories by removing the link,
+ rather than attempting to overwrite the link's destination. This makes it
+ easier to set up an alternate Python "home" directory (as described above in
+ the `Non-Root Installation`_ section).
+
+ * Added support for handling MacOS platform information in ``.egg`` filenames,
+ based on a contribution by Kevin Dangoor. You may wish to delete and
+ reinstall any eggs whose filename includes "darwin" and "Power_Macintosh",
+ because the format for this platform information has changed so that minor
+ OS X upgrades (such as 10.4.1 to 10.4.2) do not cause eggs built with a
+ previous OS version to become obsolete.
+
+ * easy_install's dependency processing algorithms have changed. When using
+ ``--always-copy``, it now ensures that dependencies are copied too. When
+ not using ``--always-copy``, it tries to use a single resolution loop,
+ rather than recursing.
+
+ * Fixed installing extra ``.pyc`` or ``.pyo`` files for scripts with ``.py``
+ extensions.
+
+ * Added ``--site-dirs`` option to allow adding custom "site" directories.
+ Made ``easy-install.pth`` work in platform-specific alternate site
+ directories (e.g. ``~/Library/Python/2.x/site-packages`` on Mac OS X).
+
+ * If you manually delete the current version of a package, the next run of
+ EasyInstall against the target directory will now remove the stray entry
+ from the ``easy-install.pth`` file.
+
+ * EasyInstall now recognizes URLs with a ``#egg=project_name`` fragment ID
+ as pointing to the named project's source checkout. Such URLs have a lower
+ match precedence than any other kind of distribution, so they'll only be
+ used if they have a higher version number than any other available
+ distribution, or if you use the ``--editable`` option. The ``#egg``
+ fragment can contain a version if it's formatted as ``#egg=proj-ver``,
+ where ``proj`` is the project name, and ``ver`` is the version number. You
+ *must* use the format for these values that the ``bdist_egg`` command uses;
+ i.e., all non-alphanumeric runs must be condensed to single underscore
+ characters.
+
+ * Added the ``--editable`` option; see `Editing and Viewing Source Packages`_
+ above for more info. Also, slightly changed the behavior of the
+ ``--build-directory`` option.
+
+ * Fixed the setup script sandbox facility not recognizing certain paths as
+ valid on case-insensitive platforms.
+
+0.5a12
+ * Fix ``python -m easy_install`` not working due to setuptools being installed
+ as a zipfile. Update safety scanner to check for modules that might be used
+ as ``python -m`` scripts.
+
+ * Misc. fixes for win32.exe support, including changes to support Python 2.4's
+ changed ``bdist_wininst`` format.
+
+0.5a10
+ * Put the ``easy_install`` module back in as a module, as it's needed for
+ ``python -m`` to run it!
+
+ * Allow ``--find-links/-f`` to accept local directories or filenames as well
+ as URLs.
+
+0.5a9
+ * EasyInstall now automatically detects when an "unmanaged" package or
+ module is going to be on ``sys.path`` ahead of a package you're installing,
+ thereby preventing the newer version from being imported. By default, it
+ will abort installation to alert you of the problem, but there are also
+ new options (``--delete-conflicting`` and ``--ignore-conflicts-at-my-risk``)
+ available to change the default behavior. (Note: this new feature doesn't
+ take effect for egg files that were built with older ``setuptools``
+ versions, because they lack the new metadata file required to implement it.)
+
+ * The ``easy_install`` distutils command now uses ``DistutilsError`` as its
+ base error type for errors that should just issue a message to stderr and
+ exit the program without a traceback.
+
+ * EasyInstall can now be given a path to a directory containing a setup
+ script, and it will attempt to build and install the package there.
+
+ * EasyInstall now performs a safety analysis on module contents to determine
+ whether a package is likely to run in zipped form, and displays
+ information about what modules may be doing introspection that would break
+ when running as a zipfile.
+
+ * Added the ``--always-unzip/-Z`` option, to force unzipping of packages that
+ would ordinarily be considered safe to unzip, and changed the meaning of
+ ``--zip-ok/-z`` to "always leave everything zipped".
+
+0.5a8
+ * There is now a separate documentation page for `setuptools`_; revision
+ history that's not specific to EasyInstall has been moved to that page.
+
+ .. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
+
+0.5a5
+ * Made ``easy_install`` a standard ``setuptools`` command, moving it from
+ the ``easy_install`` module to ``setuptools.command.easy_install``. Note
+ that if you were importing or extending it, you must now change your imports
+ accordingly. ``easy_install.py`` is still installed as a script, but not as
+ a module.
+
+0.5a4
+ * Added ``--always-copy/-a`` option to always copy needed packages to the
+ installation directory, even if they're already present elsewhere on
+ sys.path. (In previous versions, this was the default behavior, but now
+ you must request it.)
+
+ * Added ``--upgrade/-U`` option to force checking PyPI for latest available
+ version(s) of all packages requested by name and version, even if a matching
+ version is available locally.
+
+ * Added automatic installation of dependencies declared by a distribution
+ being installed. These dependencies must be listed in the distribution's
+ ``EGG-INFO`` directory, so the distribution has to have declared its
+ dependencies by using setuptools. If a package has requirements it didn't
+ declare, you'll still have to deal with them yourself. (E.g., by asking
+ EasyInstall to find and install them.)
+
+ * Added the ``--record`` option to ``easy_install`` for the benefit of tools
+ that run ``setup.py install --record=filename`` on behalf of another
+ packaging system.)
+
+0.5a3
+ * Fixed not setting script permissions to allow execution.
+
+ * Improved sandboxing so that setup scripts that want a temporary directory
+ (e.g. pychecker) can still run in the sandbox.
+
+0.5a2
+ * Fix stupid stupid refactoring-at-the-last-minute typos. :(
+
+0.5a1
+ * Added support for converting ``.win32.exe`` installers to eggs on the fly.
+ EasyInstall will now recognize such files by name and install them.
+
+ * Fixed a problem with picking the "best" version to install (versions were
+ being sorted as strings, rather than as parsed values)
+
+0.4a4
+ * Added support for the distutils "verbose/quiet" and "dry-run" options, as
+ well as the "optimize" flag.
+
+ * Support downloading packages that were uploaded to PyPI (by scanning all
+ links on package pages, not just the homepage/download links).
+
+0.4a3
+ * Add progress messages to the search/download process so that you can tell
+ what URLs it's reading to find download links. (Hopefully, this will help
+ people report out-of-date and broken links to package authors, and to tell
+ when they've asked for a package that doesn't exist.)
+
+0.4a2
+ * Added support for installing scripts
+
+ * Added support for setting options via distutils configuration files, and
+ using distutils' default options as a basis for EasyInstall's defaults.
+
+ * Renamed ``--scan-url/-s`` to ``--find-links/-f`` to free up ``-s`` for the
+ script installation directory option.
+
+ * Use ``urllib2`` instead of ``urllib``, to allow use of ``https:`` URLs if
+ Python includes SSL support.
+
+0.4a1
+ * Added ``--scan-url`` and ``--index-url`` options, to scan download pages
+ and search PyPI for needed packages.
+
+0.3a4
+ * Restrict ``--build-directory=DIR/-b DIR`` option to only be used with single
+ URL installs, to avoid running the wrong setup.py.
+
+0.3a3
+ * Added ``--build-directory=DIR/-b DIR`` option.
+
+ * Added "installation report" that explains how to use 'require()' when doing
+ a multiversion install or alternate installation directory.
+
+ * Added SourceForge mirror auto-select (Contributed by Ian Bicking)
+
+ * Added "sandboxing" that stops a setup script from running if it attempts to
+ write to the filesystem outside of the build area
+
+ * Added more workarounds for packages with quirky ``install_data`` hacks
+
+0.3a2
+ * Added subversion download support for ``svn:`` and ``svn+`` URLs, as well as
+ automatic recognition of HTTP subversion URLs (Contributed by Ian Bicking)
+
+ * Misc. bug fixes
+
+0.3a1
+ * Initial release.
+
+
+Future Plans
+============
+
+* Additional utilities to list/remove/verify packages
+* Signature checking? SSL? Ability to suppress PyPI search?
+* Display byte progress meter when downloading distributions and long pages?
+* Redirect stdout/stderr to log during run_setup?
+
diff --git a/vendor/distribute-0.6.36/docs/index.txt b/vendor/distribute-0.6.36/docs/index.txt
new file mode 100644
index 0000000000000000000000000000000000000000..5f3b945b200a8a0504d65a1aaf28892d0243a037
--- /dev/null
+++ b/vendor/distribute-0.6.36/docs/index.txt
@@ -0,0 +1,36 @@
+Welcome to Distribute's documentation!
+======================================
+
+`Distribute` is a fork of the `Setuptools` project.
+
+Distribute is intended to replace Setuptools as the standard method for
+working with Python module distributions.
+
+For those who may wonder why they should switch to Distribute over Setuptools, it’s quite simple:
+
+- Distribute is a drop-in replacement for Setuptools
+- The code is actively maintained, and has over 10 commiters
+- Distribute offers Python 3 support !
+
+Documentation content:
+
+.. toctree::
+ :maxdepth: 2
+
+ roadmap
+ python3
+ using
+ setuptools
+ easy_install
+ pkg_resources
+
+
+.. image:: http://python-distribute.org/pip_distribute.png
+
+Design done by Idan Gazit (http://pixane.com) - License: cc-by-3.0
+
+Copy & paste::
+
+ curl -O http://python-distribute.org/distribute_setup.py
+ python distribute_setup.py
+ easy_install pip
\ No newline at end of file
diff --git a/vendor/distribute-0.6.36/docs/pkg_resources.txt b/vendor/distribute-0.6.36/docs/pkg_resources.txt
new file mode 100644
index 0000000000000000000000000000000000000000..480f9547ceb1fdf60c55e2e12a393a49ca84207f
--- /dev/null
+++ b/vendor/distribute-0.6.36/docs/pkg_resources.txt
@@ -0,0 +1,1955 @@
+=============================================================
+Package Discovery and Resource Access using ``pkg_resources``
+=============================================================
+
+The ``pkg_resources`` module distributed with ``setuptools`` provides an API
+for Python libraries to access their resource files, and for extensible
+applications and frameworks to automatically discover plugins. It also
+provides runtime support for using C extensions that are inside zipfile-format
+eggs, support for merging packages that have separately-distributed modules or
+subpackages, and APIs for managing Python's current "working set" of active
+packages.
+
+
+.. contents:: **Table of Contents**
+
+
+--------
+Overview
+--------
+
+Eggs are a distribution format for Python modules, similar in concept to Java's
+"jars" or Ruby's "gems". They differ from previous Python distribution formats
+in that they are importable (i.e. they can be added to ``sys.path``), and they
+are *discoverable*, meaning that they carry metadata that unambiguously
+identifies their contents and dependencies, and thus can be *automatically*
+found and added to ``sys.path`` in response to simple requests of the form,
+"get me everything I need to use docutils' PDF support".
+
+The ``pkg_resources`` module provides runtime facilities for finding,
+introspecting, activating and using eggs and other "pluggable" distribution
+formats. Because these are new concepts in Python (and not that well-
+established in other languages either), it helps to have a few special terms
+for talking about eggs and how they can be used:
+
+project
+ A library, framework, script, plugin, application, or collection of data
+ or other resources, or some combination thereof. Projects are assumed to
+ have "relatively unique" names, e.g. names registered with PyPI.
+
+release
+ A snapshot of a project at a particular point in time, denoted by a version
+ identifier.
+
+distribution
+ A file or files that represent a particular release.
+
+importable distribution
+ A file or directory that, if placed on ``sys.path``, allows Python to
+ import any modules contained within it.
+
+pluggable distribution
+ An importable distribution whose filename unambiguously identifies its
+ release (i.e. project and version), and whose contents unamabiguously
+ specify what releases of other projects will satisfy its runtime
+ requirements.
+
+extra
+ An "extra" is an optional feature of a release, that may impose additional
+ runtime requirements. For example, if docutils PDF support required a
+ PDF support library to be present, docutils could define its PDF support as
+ an "extra", and list what other project releases need to be available in
+ order to provide it.
+
+environment
+ A collection of distributions potentially available for importing, but not
+ necessarily active. More than one distribution (i.e. release version) for
+ a given project may be present in an environment.
+
+working set
+ A collection of distributions actually available for importing, as on
+ ``sys.path``. At most one distribution (release version) of a given
+ project may be present in a working set, as otherwise there would be
+ ambiguity as to what to import.
+
+eggs
+ Eggs are pluggable distributions in one of the three formats currently
+ supported by ``pkg_resources``. There are built eggs, development eggs,
+ and egg links. Built eggs are directories or zipfiles whose name ends
+ with ``.egg`` and follows the egg naming conventions, and contain an
+ ``EGG-INFO`` subdirectory (zipped or otherwise). Development eggs are
+ normal directories of Python code with one or more ``ProjectName.egg-info``
+ subdirectories. And egg links are ``*.egg-link`` files that contain the
+ name of a built or development egg, to support symbolic linking on
+ platforms that do not have native symbolic links.
+
+(For more information about these terms and concepts, see also this
+`architectural overview`_ of ``pkg_resources`` and Python Eggs in general.)
+
+.. _architectural overview: http://mail.python.org/pipermail/distutils-sig/2005-June/004652.html
+
+
+.. -----------------
+.. Developer's Guide
+.. -----------------
+
+.. This section isn't written yet. Currently planned topics include
+ Accessing Resources
+ Finding and Activating Package Distributions
+ get_provider()
+ require()
+ WorkingSet
+ iter_distributions
+ Running Scripts
+ Configuration
+ Namespace Packages
+ Extensible Applications and Frameworks
+ Locating entry points
+ Activation listeners
+ Metadata access
+ Extended Discovery and Installation
+ Supporting Custom PEP 302 Implementations
+.. For now, please check out the extensive `API Reference`_ below.
+
+
+-------------
+API Reference
+-------------
+
+Namespace Package Support
+=========================
+
+A namespace package is a package that only contains other packages and modules,
+with no direct contents of its own. Such packages can be split across
+multiple, separately-packaged distributions. Normally, you do not need to use
+the namespace package APIs directly; instead you should supply the
+``namespace_packages`` argument to ``setup()`` in your project's ``setup.py``.
+See the `setuptools documentation on namespace packages`_ for more information.
+
+However, if for some reason you need to manipulate namespace packages or
+directly alter ``sys.path`` at runtime, you may find these APIs useful:
+
+``declare_namespace(name)``
+ Declare that the dotted package name `name` is a "namespace package" whose
+ contained packages and modules may be spread across multiple distributions.
+ The named package's ``__path__`` will be extended to include the
+ corresponding package in all distributions on ``sys.path`` that contain a
+ package of that name. (More precisely, if an importer's
+ ``find_module(name)`` returns a loader, then it will also be searched for
+ the package's contents.) Whenever a Distribution's ``activate()`` method
+ is invoked, it checks for the presence of namespace packages and updates
+ their ``__path__`` contents accordingly.
+
+Applications that manipulate namespace packages or directly alter ``sys.path``
+at runtime may also need to use this API function:
+
+``fixup_namespace_packages(path_item)``
+ Declare that `path_item` is a newly added item on ``sys.path`` that may
+ need to be used to update existing namespace packages. Ordinarily, this is
+ called for you when an egg is automatically added to ``sys.path``, but if
+ your application modifies ``sys.path`` to include locations that may
+ contain portions of a namespace package, you will need to call this
+ function to ensure they are added to the existing namespace packages.
+
+Although by default ``pkg_resources`` only supports namespace packages for
+filesystem and zip importers, you can extend its support to other "importers"
+compatible with PEP 302 using the ``register_namespace_handler()`` function.
+See the section below on `Supporting Custom Importers`_ for details.
+
+.. _setuptools documentation on namespace packages: http://peak.telecommunity.com/DevCenter/setuptools#namespace-packages
+
+
+``WorkingSet`` Objects
+======================
+
+The ``WorkingSet`` class provides access to a collection of "active"
+distributions. In general, there is only one meaningful ``WorkingSet``
+instance: the one that represents the distributions that are currently active
+on ``sys.path``. This global instance is available under the name
+``working_set`` in the ``pkg_resources`` module. However, specialized
+tools may wish to manipulate working sets that don't correspond to
+``sys.path``, and therefore may wish to create other ``WorkingSet`` instances.
+
+It's important to note that the global ``working_set`` object is initialized
+from ``sys.path`` when ``pkg_resources`` is first imported, but is only updated
+if you do all future ``sys.path`` manipulation via ``pkg_resources`` APIs. If
+you manually modify ``sys.path``, you must invoke the appropriate methods on
+the ``working_set`` instance to keep it in sync. Unfortunately, Python does
+not provide any way to detect arbitrary changes to a list object like
+``sys.path``, so ``pkg_resources`` cannot automatically update the
+``working_set`` based on changes to ``sys.path``.
+
+``WorkingSet(entries=None)``
+ Create a ``WorkingSet`` from an iterable of path entries. If `entries`
+ is not supplied, it defaults to the value of ``sys.path`` at the time
+ the constructor is called.
+
+ Note that you will not normally construct ``WorkingSet`` instances
+ yourself, but instead you will implicitly or explicitly use the global
+ ``working_set`` instance. For the most part, the ``pkg_resources`` API
+ is designed so that the ``working_set`` is used by default, such that you
+ don't have to explicitly refer to it most of the time.
+
+
+Basic ``WorkingSet`` Methods
+----------------------------
+
+The following methods of ``WorkingSet`` objects are also available as module-
+level functions in ``pkg_resources`` that apply to the default ``working_set``
+instance. Thus, you can use e.g. ``pkg_resources.require()`` as an
+abbreviation for ``pkg_resources.working_set.require()``:
+
+
+``require(*requirements)``
+ Ensure that distributions matching `requirements` are activated
+
+ `requirements` must be a string or a (possibly-nested) sequence
+ thereof, specifying the distributions and versions required. The
+ return value is a sequence of the distributions that needed to be
+ activated to fulfill the requirements; all relevant distributions are
+ included, even if they were already activated in this working set.
+
+ For the syntax of requirement specifiers, see the section below on
+ `Requirements Parsing`_.
+
+ In general, it should not be necessary for you to call this method
+ directly. It's intended more for use in quick-and-dirty scripting and
+ interactive interpreter hacking than for production use. If you're creating
+ an actual library or application, it's strongly recommended that you create
+ a "setup.py" script using ``setuptools``, and declare all your requirements
+ there. That way, tools like EasyInstall can automatically detect what
+ requirements your package has, and deal with them accordingly.
+
+ Note that calling ``require('SomePackage')`` will not install
+ ``SomePackage`` if it isn't already present. If you need to do this, you
+ should use the ``resolve()`` method instead, which allows you to pass an
+ ``installer`` callback that will be invoked when a needed distribution
+ can't be found on the local machine. You can then have this callback
+ display a dialog, automatically download the needed distribution, or
+ whatever else is appropriate for your application. See the documentation
+ below on the ``resolve()`` method for more information, and also on the
+ ``obtain()`` method of ``Environment`` objects.
+
+``run_script(requires, script_name)``
+ Locate distribution specified by `requires` and run its `script_name`
+ script. `requires` must be a string containing a requirement specifier.
+ (See `Requirements Parsing`_ below for the syntax.)
+
+ The script, if found, will be executed in *the caller's globals*. That's
+ because this method is intended to be called from wrapper scripts that
+ act as a proxy for the "real" scripts in a distribution. A wrapper script
+ usually doesn't need to do anything but invoke this function with the
+ correct arguments.
+
+ If you need more control over the script execution environment, you
+ probably want to use the ``run_script()`` method of a ``Distribution``
+ object's `Metadata API`_ instead.
+
+``iter_entry_points(group, name=None)``
+ Yield entry point objects from `group` matching `name`
+
+ If `name` is None, yields all entry points in `group` from all
+ distributions in the working set, otherwise only ones matching both
+ `group` and `name` are yielded. Entry points are yielded from the active
+ distributions in the order that the distributions appear in the working
+ set. (For the global ``working_set``, this should be the same as the order
+ that they are listed in ``sys.path``.) Note that within the entry points
+ advertised by an individual distribution, there is no particular ordering.
+
+ Please see the section below on `Entry Points`_ for more information.
+
+
+``WorkingSet`` Methods and Attributes
+-------------------------------------
+
+These methods are used to query or manipulate the contents of a specific
+working set, so they must be explicitly invoked on a particular ``WorkingSet``
+instance:
+
+``add_entry(entry)``
+ Add a path item to the ``entries``, finding any distributions on it. You
+ should use this when you add additional items to ``sys.path`` and you want
+ the global ``working_set`` to reflect the change. This method is also
+ called by the ``WorkingSet()`` constructor during initialization.
+
+ This method uses ``find_distributions(entry,True)`` to find distributions
+ corresponding to the path entry, and then ``add()`` them. `entry` is
+ always appended to the ``entries`` attribute, even if it is already
+ present, however. (This is because ``sys.path`` can contain the same value
+ more than once, and the ``entries`` attribute should be able to reflect
+ this.)
+
+``__contains__(dist)``
+ True if `dist` is active in this ``WorkingSet``. Note that only one
+ distribution for a given project can be active in a given ``WorkingSet``.
+
+``__iter__()``
+ Yield distributions for non-duplicate projects in the working set.
+ The yield order is the order in which the items' path entries were
+ added to the working set.
+
+``find(req)``
+ Find a distribution matching `req` (a ``Requirement`` instance).
+ If there is an active distribution for the requested project, this
+ returns it, as long as it meets the version requirement specified by
+ `req`. But, if there is an active distribution for the project and it
+ does *not* meet the `req` requirement, ``VersionConflict`` is raised.
+ If there is no active distribution for the requested project, ``None``
+ is returned.
+
+``resolve(requirements, env=None, installer=None)``
+ List all distributions needed to (recursively) meet `requirements`
+
+ `requirements` must be a sequence of ``Requirement`` objects. `env`,
+ if supplied, should be an ``Environment`` instance. If
+ not supplied, an ``Environment`` is created from the working set's
+ ``entries``. `installer`, if supplied, will be invoked with each
+ requirement that cannot be met by an already-installed distribution; it
+ should return a ``Distribution`` or ``None``. (See the ``obtain()`` method
+ of `Environment Objects`_, below, for more information on the `installer`
+ argument.)
+
+``add(dist, entry=None)``
+ Add `dist` to working set, associated with `entry`
+
+ If `entry` is unspecified, it defaults to ``dist.location``. On exit from
+ this routine, `entry` is added to the end of the working set's ``.entries``
+ (if it wasn't already present).
+
+ `dist` is only added to the working set if it's for a project that
+ doesn't already have a distribution active in the set. If it's
+ successfully added, any callbacks registered with the ``subscribe()``
+ method will be called. (See `Receiving Change Notifications`_, below.)
+
+ Note: ``add()`` is automatically called for you by the ``require()``
+ method, so you don't normally need to use this method directly.
+
+``entries``
+ This attribute represents a "shadow" ``sys.path``, primarily useful for
+ debugging. If you are experiencing import problems, you should check
+ the global ``working_set`` object's ``entries`` against ``sys.path``, to
+ ensure that they match. If they do not, then some part of your program
+ is manipulating ``sys.path`` without updating the ``working_set``
+ accordingly. IMPORTANT NOTE: do not directly manipulate this attribute!
+ Setting it equal to ``sys.path`` will not fix your problem, any more than
+ putting black tape over an "engine warning" light will fix your car! If
+ this attribute is out of sync with ``sys.path``, it's merely an *indicator*
+ of the problem, not the cause of it.
+
+
+Receiving Change Notifications
+------------------------------
+
+Extensible applications and frameworks may need to receive notification when
+a new distribution (such as a plug-in component) has been added to a working
+set. This is what the ``subscribe()`` method and ``add_activation_listener()``
+function are for.
+
+``subscribe(callback)``
+ Invoke ``callback(distribution)`` once for each active distribution that is
+ in the set now, or gets added later. Because the callback is invoked for
+ already-active distributions, you do not need to loop over the working set
+ yourself to deal with the existing items; just register the callback and
+ be prepared for the fact that it will be called immediately by this method.
+
+ Note that callbacks *must not* allow exceptions to propagate, or they will
+ interfere with the operation of other callbacks and possibly result in an
+ inconsistent working set state. Callbacks should use a try/except block
+ to ignore, log, or otherwise process any errors, especially since the code
+ that caused the callback to be invoked is unlikely to be able to handle
+ the errors any better than the callback itself.
+
+``pkg_resources.add_activation_listener()`` is an alternate spelling of
+``pkg_resources.working_set.subscribe()``.
+
+
+Locating Plugins
+----------------
+
+Extensible applications will sometimes have a "plugin directory" or a set of
+plugin directories, from which they want to load entry points or other
+metadata. The ``find_plugins()`` method allows you to do this, by scanning an
+environment for the newest version of each project that can be safely loaded
+without conflicts or missing requirements.
+
+``find_plugins(plugin_env, full_env=None, fallback=True)``
+ Scan `plugin_env` and identify which distributions could be added to this
+ working set without version conflicts or missing requirements.
+
+ Example usage::
+
+ distributions, errors = working_set.find_plugins(
+ Environment(plugin_dirlist)
+ )
+ map(working_set.add, distributions) # add plugins+libs to sys.path
+ print "Couldn't load", errors # display errors
+
+ The `plugin_env` should be an ``Environment`` instance that contains only
+ distributions that are in the project's "plugin directory" or directories.
+ The `full_env`, if supplied, should be an ``Environment`` instance that
+ contains all currently-available distributions.
+
+ If `full_env` is not supplied, one is created automatically from the
+ ``WorkingSet`` this method is called on, which will typically mean that
+ every directory on ``sys.path`` will be scanned for distributions.
+
+ This method returns a 2-tuple: (`distributions`, `error_info`), where
+ `distributions` is a list of the distributions found in `plugin_env` that
+ were loadable, along with any other distributions that are needed to resolve
+ their dependencies. `error_info` is a dictionary mapping unloadable plugin
+ distributions to an exception instance describing the error that occurred.
+ Usually this will be a ``DistributionNotFound`` or ``VersionConflict``
+ instance.
+
+ Most applications will use this method mainly on the master ``working_set``
+ instance in ``pkg_resources``, and then immediately add the returned
+ distributions to the working set so that they are available on sys.path.
+ This will make it possible to find any entry points, and allow any other
+ metadata tracking and hooks to be activated.
+
+ The resolution algorithm used by ``find_plugins()`` is as follows. First,
+ the project names of the distributions present in `plugin_env` are sorted.
+ Then, each project's eggs are tried in descending version order (i.e.,
+ newest version first).
+
+ An attempt is made to resolve each egg's dependencies. If the attempt is
+ successful, the egg and its dependencies are added to the output list and to
+ a temporary copy of the working set. The resolution process continues with
+ the next project name, and no older eggs for that project are tried.
+
+ If the resolution attempt fails, however, the error is added to the error
+ dictionary. If the `fallback` flag is true, the next older version of the
+ plugin is tried, until a working version is found. If false, the resolution
+ process continues with the next plugin project name.
+
+ Some applications may have stricter fallback requirements than others. For
+ example, an application that has a database schema or persistent objects
+ may not be able to safely downgrade a version of a package. Others may want
+ to ensure that a new plugin configuration is either 100% good or else
+ revert to a known-good configuration. (That is, they may wish to revert to
+ a known configuration if the `error_info` return value is non-empty.)
+
+ Note that this algorithm gives precedence to satisfying the dependencies of
+ alphabetically prior project names in case of version conflicts. If two
+ projects named "AaronsPlugin" and "ZekesPlugin" both need different versions
+ of "TomsLibrary", then "AaronsPlugin" will win and "ZekesPlugin" will be
+ disabled due to version conflict.
+
+
+``Environment`` Objects
+=======================
+
+An "environment" is a collection of ``Distribution`` objects, usually ones
+that are present and potentially importable on the current platform.
+``Environment`` objects are used by ``pkg_resources`` to index available
+distributions during dependency resolution.
+
+``Environment(search_path=None, platform=get_supported_platform(), python=PY_MAJOR)``
+ Create an environment snapshot by scanning `search_path` for distributions
+ compatible with `platform` and `python`. `search_path` should be a
+ sequence of strings such as might be used on ``sys.path``. If a
+ `search_path` isn't supplied, ``sys.path`` is used.
+
+ `platform` is an optional string specifying the name of the platform
+ that platform-specific distributions must be compatible with. If
+ unspecified, it defaults to the current platform. `python` is an
+ optional string naming the desired version of Python (e.g. ``'2.4'``);
+ it defaults to the currently-running version.
+
+ You may explicitly set `platform` (and/or `python`) to ``None`` if you
+ wish to include *all* distributions, not just those compatible with the
+ running platform or Python version.
+
+ Note that `search_path` is scanned immediately for distributions, and the
+ resulting ``Environment`` is a snapshot of the found distributions. It
+ is not automatically updated if the system's state changes due to e.g.
+ installation or removal of distributions.
+
+``__getitem__(project_name)``
+ Returns a list of distributions for the given project name, ordered
+ from newest to oldest version. (And highest to lowest format precedence
+ for distributions that contain the same version of the project.) If there
+ are no distributions for the project, returns an empty list.
+
+``__iter__()``
+ Yield the unique project names of the distributions in this environment.
+ The yielded names are always in lower case.
+
+``add(dist)``
+ Add `dist` to the environment if it matches the platform and python version
+ specified at creation time, and only if the distribution hasn't already
+ been added. (i.e., adding the same distribution more than once is a no-op.)
+
+``remove(dist)``
+ Remove `dist` from the environment.
+
+``can_add(dist)``
+ Is distribution `dist` acceptable for this environment? If it's not
+ compatible with the ``platform`` and ``python`` version values specified
+ when the environment was created, a false value is returned.
+
+``__add__(dist_or_env)`` (``+`` operator)
+ Add a distribution or environment to an ``Environment`` instance, returning
+ a *new* environment object that contains all the distributions previously
+ contained by both. The new environment will have a ``platform`` and
+ ``python`` of ``None``, meaning that it will not reject any distributions
+ from being added to it; it will simply accept whatever is added. If you
+ want the added items to be filtered for platform and Python version, or
+ you want to add them to the *same* environment instance, you should use
+ in-place addition (``+=``) instead.
+
+``__iadd__(dist_or_env)`` (``+=`` operator)
+ Add a distribution or environment to an ``Environment`` instance
+ *in-place*, updating the existing instance and returning it. The
+ ``platform`` and ``python`` filter attributes take effect, so distributions
+ in the source that do not have a suitable platform string or Python version
+ are silently ignored.
+
+``best_match(req, working_set, installer=None)``
+ Find distribution best matching `req` and usable on `working_set`
+
+ This calls the ``find(req)`` method of the `working_set` to see if a
+ suitable distribution is already active. (This may raise
+ ``VersionConflict`` if an unsuitable version of the project is already
+ active in the specified `working_set`.) If a suitable distribution isn't
+ active, this method returns the newest distribution in the environment
+ that meets the ``Requirement`` in `req`. If no suitable distribution is
+ found, and `installer` is supplied, then the result of calling
+ the environment's ``obtain(req, installer)`` method will be returned.
+
+``obtain(requirement, installer=None)``
+ Obtain a distro that matches requirement (e.g. via download). In the
+ base ``Environment`` class, this routine just returns
+ ``installer(requirement)``, unless `installer` is None, in which case
+ None is returned instead. This method is a hook that allows subclasses
+ to attempt other ways of obtaining a distribution before falling back
+ to the `installer` argument.
+
+``scan(search_path=None)``
+ Scan `search_path` for distributions usable on `platform`
+
+ Any distributions found are added to the environment. `search_path` should
+ be a sequence of strings such as might be used on ``sys.path``. If not
+ supplied, ``sys.path`` is used. Only distributions conforming to
+ the platform/python version defined at initialization are added. This
+ method is a shortcut for using the ``find_distributions()`` function to
+ find the distributions from each item in `search_path`, and then calling
+ ``add()`` to add each one to the environment.
+
+
+``Requirement`` Objects
+=======================
+
+``Requirement`` objects express what versions of a project are suitable for
+some purpose. These objects (or their string form) are used by various
+``pkg_resources`` APIs in order to find distributions that a script or
+distribution needs.
+
+
+Requirements Parsing
+--------------------
+
+``parse_requirements(s)``
+ Yield ``Requirement`` objects for a string or iterable of lines. Each
+ requirement must start on a new line. See below for syntax.
+
+``Requirement.parse(s)``
+ Create a ``Requirement`` object from a string or iterable of lines. A
+ ``ValueError`` is raised if the string or lines do not contain a valid
+ requirement specifier, or if they contain more than one specifier. (To
+ parse multiple specifiers from a string or iterable of strings, use
+ ``parse_requirements()`` instead.)
+
+ The syntax of a requirement specifier can be defined in EBNF as follows::
+
+ requirement ::= project_name versionspec? extras?
+ versionspec ::= comparison version (',' comparison version)*
+ comparison ::= '<' | '<=' | '!=' | '==' | '>=' | '>'
+ extras ::= '[' extralist? ']'
+ extralist ::= identifier (',' identifier)*
+ project_name ::= identifier
+ identifier ::= [-A-Za-z0-9_]+
+ version ::= [-A-Za-z0-9_.]+
+
+ Tokens can be separated by whitespace, and a requirement can be continued
+ over multiple lines using a backslash (``\\``). Line-end comments (using
+ ``#``) are also allowed.
+
+ Some examples of valid requirement specifiers::
+
+ FooProject >= 1.2
+ Fizzy [foo, bar]
+ PickyThing<1.6,>1.9,!=1.9.6,<2.0a0,==2.4c1
+ SomethingWhoseVersionIDontCareAbout
+
+ The project name is the only required portion of a requirement string, and
+ if it's the only thing supplied, the requirement will accept any version
+ of that project.
+
+ The "extras" in a requirement are used to request optional features of a
+ project, that may require additional project distributions in order to
+ function. For example, if the hypothetical "Report-O-Rama" project offered
+ optional PDF support, it might require an additional library in order to
+ provide that support. Thus, a project needing Report-O-Rama's PDF features
+ could use a requirement of ``Report-O-Rama[PDF]`` to request installation
+ or activation of both Report-O-Rama and any libraries it needs in order to
+ provide PDF support. For example, you could use::
+
+ easy_install.py Report-O-Rama[PDF]
+
+ To install the necessary packages using the EasyInstall program, or call
+ ``pkg_resources.require('Report-O-Rama[PDF]')`` to add the necessary
+ distributions to sys.path at runtime.
+
+
+``Requirement`` Methods and Attributes
+--------------------------------------
+
+``__contains__(dist_or_version)``
+ Return true if `dist_or_version` fits the criteria for this requirement.
+ If `dist_or_version` is a ``Distribution`` object, its project name must
+ match the requirement's project name, and its version must meet the
+ requirement's version criteria. If `dist_or_version` is a string, it is
+ parsed using the ``parse_version()`` utility function. Otherwise, it is
+ assumed to be an already-parsed version.
+
+ The ``Requirement`` object's version specifiers (``.specs``) are internally
+ sorted into ascending version order, and used to establish what ranges of
+ versions are acceptable. Adjacent redundant conditions are effectively
+ consolidated (e.g. ``">1, >2"`` produces the same results as ``">1"``, and
+ ``"<2,<3"`` produces the same results as``"<3"``). ``"!="`` versions are
+ excised from the ranges they fall within. The version being tested for
+ acceptability 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 when compared with actual version number(s).)
+
+``__eq__(other_requirement)``
+ A requirement compares equal to another requirement if they have
+ case-insensitively equal project names, version specifiers, and "extras".
+ (The order that extras and version specifiers are in is also ignored.)
+ Equal requirements also have equal hashes, so that requirements can be
+ used in sets or as dictionary keys.
+
+``__str__()``
+ The string form of a ``Requirement`` is a string that, if passed to
+ ``Requirement.parse()``, would return an equal ``Requirement`` object.
+
+``project_name``
+ The name of the required project
+
+``key``
+ An all-lowercase version of the ``project_name``, useful for comparison
+ or indexing.
+
+``extras``
+ A tuple of names of "extras" that this requirement calls for. (These will
+ be all-lowercase and normalized using the ``safe_extra()`` parsing utility
+ function, so they may not exactly equal the extras the requirement was
+ created with.)
+
+``specs``
+ A list of ``(op,version)`` tuples, sorted in ascending parsed-version
+ order. The `op` in each tuple is a comparison operator, represented as
+ a string. The `version` is the (unparsed) version number. The relative
+ order of tuples containing the same version numbers is undefined, since
+ having more than one operator for a given version is either redundant or
+ self-contradictory.
+
+
+Entry Points
+============
+
+Entry points are a simple way for distributions to "advertise" Python objects
+(such as functions or classes) for use by other distributions. Extensible
+applications and frameworks can search for entry points with a particular name
+or group, either from a specific distribution or from all active distributions
+on sys.path, and then inspect or load the advertised objects at will.
+
+Entry points belong to "groups" which are named with a dotted name similar to
+a Python package or module name. For example, the ``setuptools`` package uses
+an entry point named ``distutils.commands`` in order to find commands defined
+by distutils extensions. ``setuptools`` treats the names of entry points
+defined in that group as the acceptable commands for a setup script.
+
+In a similar way, other packages can define their own entry point groups,
+either using dynamic names within the group (like ``distutils.commands``), or
+possibly using predefined names within the group. For example, a blogging
+framework that offers various pre- or post-publishing hooks might define an
+entry point group and look for entry points named "pre_process" and
+"post_process" within that group.
+
+To advertise an entry point, a project needs to use ``setuptools`` and provide
+an ``entry_points`` argument to ``setup()`` in its setup script, so that the
+entry points will be included in the distribution's metadata. For more
+details, see the ``setuptools`` documentation. (XXX link here to setuptools)
+
+Each project distribution can advertise at most one entry point of a given
+name within the same entry point group. For example, a distutils extension
+could advertise two different ``distutils.commands`` entry points, as long as
+they had different names. However, there is nothing that prevents *different*
+projects from advertising entry points of the same name in the same group. In
+some cases, this is a desirable thing, since the application or framework that
+uses the entry points may be calling them as hooks, or in some other way
+combining them. It is up to the application or framework to decide what to do
+if multiple distributions advertise an entry point; some possibilities include
+using both entry points, displaying an error message, using the first one found
+in sys.path order, etc.
+
+
+Convenience API
+---------------
+
+In the following functions, the `dist` argument can be a ``Distribution``
+instance, a ``Requirement`` instance, or a string specifying a requirement
+(i.e. project name, version, etc.). If the argument is a string or
+``Requirement``, the specified distribution is located (and added to sys.path
+if not already present). An error will be raised if a matching distribution is
+not available.
+
+The `group` argument should be a string containing a dotted identifier,
+identifying an entry point group. If you are defining an entry point group,
+you should include some portion of your package's name in the group name so as
+to avoid collision with other packages' entry point groups.
+
+``load_entry_point(dist, group, name)``
+ Load the named entry point from the specified distribution, or raise
+ ``ImportError``.
+
+``get_entry_info(dist, group, name)``
+ Return an ``EntryPoint`` object for the given `group` and `name` from
+ the specified distribution. Returns ``None`` if the distribution has not
+ advertised a matching entry point.
+
+``get_entry_map(dist, group=None)``
+ Return the distribution's entry point map for `group`, or the full entry
+ map for the distribution. This function always returns a dictionary,
+ even if the distribution advertises no entry points. If `group` is given,
+ the dictionary maps entry point names to the corresponding ``EntryPoint``
+ object. If `group` is None, the dictionary maps group names to
+ dictionaries that then map entry point names to the corresponding
+ ``EntryPoint`` instance in that group.
+
+``iter_entry_points(group, name=None)``
+ Yield entry point objects from `group` matching `name`.
+
+ If `name` is None, yields all entry points in `group` from all
+ distributions in the working set on sys.path, otherwise only ones matching
+ both `group` and `name` are yielded. Entry points are yielded from
+ the active distributions in the order that the distributions appear on
+ sys.path. (Within entry points for a particular distribution, however,
+ there is no particular ordering.)
+
+ (This API is actually a method of the global ``working_set`` object; see
+ the section above on `Basic WorkingSet Methods`_ for more information.)
+
+
+Creating and Parsing
+--------------------
+
+``EntryPoint(name, module_name, attrs=(), extras=(), dist=None)``
+ Create an ``EntryPoint`` instance. `name` is the entry point name. The
+ `module_name` is the (dotted) name of the module containing the advertised
+ object. `attrs` is an optional tuple of names to look up from the
+ module to obtain the advertised object. For example, an `attrs` of
+ ``("foo","bar")`` and a `module_name` of ``"baz"`` would mean that the
+ advertised object could be obtained by the following code::
+
+ import baz
+ advertised_object = baz.foo.bar
+
+ The `extras` are an optional tuple of "extra feature" names that the
+ distribution needs in order to provide this entry point. When the
+ entry point is loaded, these extra features are looked up in the `dist`
+ argument to find out what other distributions may need to be activated
+ on sys.path; see the ``load()`` method for more details. The `extras`
+ argument is only meaningful if `dist` is specified. `dist` must be
+ a ``Distribution`` instance.
+
+``EntryPoint.parse(src, dist=None)`` (classmethod)
+ Parse a single entry point from string `src`
+
+ Entry point syntax follows the form::
+
+ name = some.module:some.attr [extra1,extra2]
+
+ The entry name and module name are required, but the ``:attrs`` and
+ ``[extras]`` parts are optional, as is the whitespace shown between
+ some of the items. The `dist` argument is passed through to the
+ ``EntryPoint()`` constructor, along with the other values parsed from
+ `src`.
+
+``EntryPoint.parse_group(group, lines, dist=None)`` (classmethod)
+ Parse `lines` (a string or sequence of lines) to create a dictionary
+ mapping entry point names to ``EntryPoint`` objects. ``ValueError`` is
+ raised if entry point names are duplicated, if `group` is not a valid
+ entry point group name, or if there are any syntax errors. (Note: the
+ `group` parameter is used only for validation and to create more
+ informative error messages.) If `dist` is provided, it will be used to
+ set the ``dist`` attribute of the created ``EntryPoint`` objects.
+
+``EntryPoint.parse_map(data, dist=None)`` (classmethod)
+ Parse `data` into a dictionary mapping group names to dictionaries mapping
+ entry point names to ``EntryPoint`` objects. If `data` is a dictionary,
+ then the keys are used as group names and the values are passed to
+ ``parse_group()`` as the `lines` argument. If `data` is a string or
+ sequence of lines, it is first split into .ini-style sections (using
+ the ``split_sections()`` utility function) and the section names are used
+ as group names. In either case, the `dist` argument is passed through to
+ ``parse_group()`` so that the entry points will be linked to the specified
+ distribution.
+
+
+``EntryPoint`` Objects
+----------------------
+
+For simple introspection, ``EntryPoint`` objects have attributes that
+correspond exactly to the constructor argument names: ``name``,
+``module_name``, ``attrs``, ``extras``, and ``dist`` are all available. In
+addition, the following methods are provided:
+
+``load(require=True, env=None, installer=None)``
+ Load the entry point, returning the advertised Python object, or raise
+ ``ImportError`` if it cannot be obtained. If `require` is a true value,
+ then ``require(env, installer)`` is called before attempting the import.
+
+``require(env=None, installer=None)``
+ Ensure that any "extras" needed by the entry point are available on
+ sys.path. ``UnknownExtra`` is raised if the ``EntryPoint`` has ``extras``,
+ but no ``dist``, or if the named extras are not defined by the
+ distribution. If `env` is supplied, it must be an ``Environment``, and it
+ will be used to search for needed distributions if they are not already
+ present on sys.path. If `installer` is supplied, it must be a callable
+ taking a ``Requirement`` instance and returning a matching importable
+ ``Distribution`` instance or None.
+
+``__str__()``
+ The string form of an ``EntryPoint`` is a string that could be passed to
+ ``EntryPoint.parse()`` to produce an equivalent ``EntryPoint``.
+
+
+``Distribution`` Objects
+========================
+
+``Distribution`` objects represent collections of Python code that may or may
+not be importable, and may or may not have metadata and resources associated
+with them. Their metadata may include information such as what other projects
+the distribution depends on, what entry points the distribution advertises, and
+so on.
+
+
+Getting or Creating Distributions
+---------------------------------
+
+Most commonly, you'll obtain ``Distribution`` objects from a ``WorkingSet`` or
+an ``Environment``. (See the sections above on `WorkingSet Objects`_ and
+`Environment Objects`_, which are containers for active distributions and
+available distributions, respectively.) You can also obtain ``Distribution``
+objects from one of these high-level APIs:
+
+``find_distributions(path_item, only=False)``
+ Yield distributions accessible via `path_item`. If `only` is true, yield
+ only distributions whose ``location`` is equal to `path_item`. In other
+ words, if `only` is true, this yields any distributions that would be
+ importable if `path_item` were on ``sys.path``. If `only` is false, this
+ also yields distributions that are "in" or "under" `path_item`, but would
+ not be importable unless their locations were also added to ``sys.path``.
+
+``get_distribution(dist_spec)``
+ Return a ``Distribution`` object for a given ``Requirement`` or string.
+ If `dist_spec` is already a ``Distribution`` instance, it is returned.
+ If it is a ``Requirement`` object or a string that can be parsed into one,
+ it is used to locate and activate a matching distribution, which is then
+ returned.
+
+However, if you're creating specialized tools for working with distributions,
+or creating a new distribution format, you may also need to create
+``Distribution`` objects directly, using one of the three constructors below.
+
+These constructors all take an optional `metadata` argument, which is used to
+access any resources or metadata associated with the distribution. `metadata`
+must be an object that implements the ``IResourceProvider`` interface, or None.
+If it is None, an ``EmptyProvider`` is used instead. ``Distribution`` objects
+implement both the `IResourceProvider`_ and `IMetadataProvider Methods`_ by
+delegating them to the `metadata` object.
+
+``Distribution.from_location(location, basename, metadata=None, **kw)`` (classmethod)
+ Create a distribution for `location`, which must be a string such as a
+ URL, filename, or other string that might be used on ``sys.path``.
+ `basename` is a string naming the distribution, like ``Foo-1.2-py2.4.egg``.
+ If `basename` ends with ``.egg``, then the project's name, version, python
+ version and platform are extracted from the filename and used to set those
+ properties of the created distribution. Any additional keyword arguments
+ are forwarded to the ``Distribution()`` constructor.
+
+``Distribution.from_filename(filename, metadata=None**kw)`` (classmethod)
+ Create a distribution by parsing a local filename. This is a shorter way
+ of saying ``Distribution.from_location(normalize_path(filename),
+ os.path.basename(filename), metadata)``. In other words, it creates a
+ distribution whose location is the normalize form of the filename, parsing
+ name and version information from the base portion of the filename. Any
+ additional keyword arguments are forwarded to the ``Distribution()``
+ constructor.
+
+``Distribution(location,metadata,project_name,version,py_version,platform,precedence)``
+ Create a distribution by setting its properties. All arguments are
+ optional and default to None, except for `py_version` (which defaults to
+ the current Python version) and `precedence` (which defaults to
+ ``EGG_DIST``; for more details see ``precedence`` under `Distribution
+ Attributes`_ below). Note that it's usually easier to use the
+ ``from_filename()`` or ``from_location()`` constructors than to specify
+ all these arguments individually.
+
+
+``Distribution`` Attributes
+---------------------------
+
+location
+ A string indicating the distribution's location. For an importable
+ distribution, this is the string that would be added to ``sys.path`` to
+ make it actively importable. For non-importable distributions, this is
+ simply a filename, URL, or other way of locating the distribution.
+
+project_name
+ A string, naming the project that this distribution is for. Project names
+ are defined by a project's setup script, and they are used to identify
+ projects on PyPI. When a ``Distribution`` is constructed, the
+ `project_name` argument is passed through the ``safe_name()`` utility
+ function to filter out any unacceptable characters.
+
+key
+ ``dist.key`` is short for ``dist.project_name.lower()``. It's used for
+ case-insensitive comparison and indexing of distributions by project name.
+
+extras
+ A list of strings, giving the names of extra features defined by the
+ project's dependency list (the ``extras_require`` argument specified in
+ the project's setup script).
+
+version
+ A string denoting what release of the project this distribution contains.
+ When a ``Distribution`` is constructed, the `version` argument is passed
+ through the ``safe_version()`` utility function to filter out any
+ unacceptable characters. If no `version` is specified at construction
+ time, then attempting to access this attribute later will cause the
+ ``Distribution`` to try to discover its version by reading its ``PKG-INFO``
+ metadata file. If ``PKG-INFO`` is unavailable or can't be parsed,
+ ``ValueError`` is raised.
+
+parsed_version
+ The ``parsed_version`` is a tuple representing a "parsed" form of the
+ distribution's ``version``. ``dist.parsed_version`` is a shortcut for
+ calling ``parse_version(dist.version)``. It is used to compare or sort
+ distributions by version. (See the `Parsing Utilities`_ section below for
+ more information on the ``parse_version()`` function.) Note that accessing
+ ``parsed_version`` may result in a ``ValueError`` if the ``Distribution``
+ was constructed without a `version` and without `metadata` capable of
+ supplying the missing version info.
+
+py_version
+ The major/minor Python version the distribution supports, as a string.
+ For example, "2.3" or "2.4". The default is the current version of Python.
+
+platform
+ A string representing the platform the distribution is intended for, or
+ ``None`` if the distribution is "pure Python" and therefore cross-platform.
+ See `Platform Utilities`_ below for more information on platform strings.
+
+precedence
+ A distribution's ``precedence`` is used to determine the relative order of
+ two distributions that have the same ``project_name`` and
+ ``parsed_version``. The default precedence is ``pkg_resources.EGG_DIST``,
+ which is the highest (i.e. most preferred) precedence. The full list
+ of predefined precedences, from most preferred to least preferred, is:
+ ``EGG_DIST``, ``BINARY_DIST``, ``SOURCE_DIST``, ``CHECKOUT_DIST``, and
+ ``DEVELOP_DIST``. Normally, precedences other than ``EGG_DIST`` are used
+ only by the ``setuptools.package_index`` module, when sorting distributions
+ found in a package index to determine their suitability for installation.
+ "System" and "Development" eggs (i.e., ones that use the ``.egg-info``
+ format), however, are automatically given a precedence of ``DEVELOP_DIST``.
+
+
+
+``Distribution`` Methods
+------------------------
+
+``activate(path=None)``
+ Ensure distribution is importable on `path`. If `path` is None,
+ ``sys.path`` is used instead. This ensures that the distribution's
+ ``location`` is in the `path` list, and it also performs any necessary
+ namespace package fixups or declarations. (That is, if the distribution
+ contains namespace packages, this method ensures that they are declared,
+ and that the distribution's contents for those namespace packages are
+ merged with the contents provided by any other active distributions. See
+ the section above on `Namespace Package Support`_ for more information.)
+
+ ``pkg_resources`` adds a notification callback to the global ``working_set``
+ that ensures this method is called whenever a distribution is added to it.
+ Therefore, you should not normally need to explicitly call this method.
+ (Note that this means that namespace packages on ``sys.path`` are always
+ imported as soon as ``pkg_resources`` is, which is another reason why
+ namespace packages should not contain any code or import statements.)
+
+``as_requirement()``
+ Return a ``Requirement`` instance that matches this distribution's project
+ name and version.
+
+``requires(extras=())``
+ List the ``Requirement`` objects that specify this distribution's
+ dependencies. If `extras` is specified, it should be a sequence of names
+ of "extras" defined by the distribution, and the list returned will then
+ include any dependencies needed to support the named "extras".
+
+``clone(**kw)``
+ Create a copy of the distribution. Any supplied keyword arguments override
+ the corresponding argument to the ``Distribution()`` constructor, allowing
+ you to change some of the copied distribution's attributes.
+
+``egg_name()``
+ Return what this distribution's standard filename should be, not including
+ the ".egg" extension. For example, a distribution for project "Foo"
+ version 1.2 that runs on Python 2.3 for Windows would have an ``egg_name()``
+ of ``Foo-1.2-py2.3-win32``. Any dashes in the name or version are
+ converted to underscores. (``Distribution.from_location()`` will convert
+ them back when parsing a ".egg" file name.)
+
+``__cmp__(other)``, ``__hash__()``
+ Distribution objects are hashed and compared on the basis of their parsed
+ version and precedence, followed by their key (lowercase project name),
+ location, Python version, and platform.
+
+The following methods are used to access ``EntryPoint`` objects advertised
+by the distribution. See the section above on `Entry Points`_ for more
+detailed information about these operations:
+
+``get_entry_info(group, name)``
+ Return the ``EntryPoint`` object for `group` and `name`, or None if no
+ such point is advertised by this distribution.
+
+``get_entry_map(group=None)``
+ Return the entry point map for `group`. If `group` is None, return
+ a dictionary mapping group names to entry point maps for all groups.
+ (An entry point map is a dictionary of entry point names to ``EntryPoint``
+ objects.)
+
+``load_entry_point(group, name)``
+ Short for ``get_entry_info(group, name).load()``. Returns the object
+ advertised by the named entry point, or raises ``ImportError`` if
+ the entry point isn't advertised by this distribution, or there is some
+ other import problem.
+
+In addition to the above methods, ``Distribution`` objects also implement all
+of the `IResourceProvider`_ and `IMetadataProvider Methods`_ (which are
+documented in later sections):
+
+* ``has_metadata(name)``
+* ``metadata_isdir(name)``
+* ``metadata_listdir(name)``
+* ``get_metadata(name)``
+* ``get_metadata_lines(name)``
+* ``run_script(script_name, namespace)``
+* ``get_resource_filename(manager, resource_name)``
+* ``get_resource_stream(manager, resource_name)``
+* ``get_resource_string(manager, resource_name)``
+* ``has_resource(resource_name)``
+* ``resource_isdir(resource_name)``
+* ``resource_listdir(resource_name)``
+
+If the distribution was created with a `metadata` argument, these resource and
+metadata access methods are all delegated to that `metadata` provider.
+Otherwise, they are delegated to an ``EmptyProvider``, so that the distribution
+will appear to have no resources or metadata. This delegation approach is used
+so that supporting custom importers or new distribution formats can be done
+simply by creating an appropriate `IResourceProvider`_ implementation; see the
+section below on `Supporting Custom Importers`_ for more details.
+
+
+``ResourceManager`` API
+=======================
+
+The ``ResourceManager`` class provides uniform access to package resources,
+whether those resources exist as files and directories or are compressed in
+an archive of some kind.
+
+Normally, you do not need to create or explicitly manage ``ResourceManager``
+instances, as the ``pkg_resources`` module creates a global instance for you,
+and makes most of its methods available as top-level names in the
+``pkg_resources`` module namespace. So, for example, this code actually
+calls the ``resource_string()`` method of the global ``ResourceManager``::
+
+ import pkg_resources
+ my_data = pkg_resources.resource_string(__name__, "foo.dat")
+
+Thus, you can use the APIs below without needing an explicit
+``ResourceManager`` instance; just import and use them as needed.
+
+
+Basic Resource Access
+---------------------
+
+In the following methods, the `package_or_requirement` argument may be either
+a Python package/module name (e.g. ``foo.bar``) or a ``Requirement`` instance.
+If it is a package or module name, the named module or package must be
+importable (i.e., be in a distribution or directory on ``sys.path``), and the
+`resource_name` argument is interpreted relative to the named package. (Note
+that if a module name is used, then the resource name is relative to the
+package immediately containing the named module. Also, you should not use use
+a namespace package name, because a namespace package can be spread across
+multiple distributions, and is therefore ambiguous as to which distribution
+should be searched for the resource.)
+
+If it is a ``Requirement``, then the requirement is automatically resolved
+(searching the current ``Environment`` if necessary) and a matching
+distribution is added to the ``WorkingSet`` and ``sys.path`` if one was not
+already present. (Unless the ``Requirement`` can't be satisfied, in which
+case an exception is raised.) The `resource_name` argument is then interpreted
+relative to the root of the identified distribution; i.e. its first path
+segment will be treated as a peer of the top-level modules or packages in the
+distribution.
+
+Note that resource names must be ``/``-separated paths and cannot be absolute
+(i.e. no leading ``/``) or contain relative names like ``".."``. Do *not* use
+``os.path`` routines to manipulate resource paths, as they are *not* filesystem
+paths.
+
+``resource_exists(package_or_requirement, resource_name)``
+ Does the named resource exist? Return ``True`` or ``False`` accordingly.
+
+``resource_stream(package_or_requirement, resource_name)``
+ Return a readable file-like object for the specified resource; it may be
+ an actual file, a ``StringIO``, or some similar object. The stream is
+ in "binary mode", in the sense that whatever bytes are in the resource
+ will be read as-is.
+
+``resource_string(package_or_requirement, resource_name)``
+ Return the specified resource as a string. The resource is read in
+ binary fashion, such that the returned string contains exactly the bytes
+ that are stored in the resource.
+
+``resource_isdir(package_or_requirement, resource_name)``
+ Is the named resource a directory? Return ``True`` or ``False``
+ accordingly.
+
+``resource_listdir(package_or_requirement, resource_name)``
+ List the contents of the named resource directory, just like ``os.listdir``
+ except that it works even if the resource is in a zipfile.
+
+Note that only ``resource_exists()`` and ``resource_isdir()`` are insensitive
+as to the resource type. You cannot use ``resource_listdir()`` on a file
+resource, and you can't use ``resource_string()`` or ``resource_stream()`` on
+directory resources. Using an inappropriate method for the resource type may
+result in an exception or undefined behavior, depending on the platform and
+distribution format involved.
+
+
+Resource Extraction
+-------------------
+
+``resource_filename(package_or_requirement, resource_name)``
+ Sometimes, it is not sufficient to access a resource in string or stream
+ form, and a true filesystem filename is needed. In such cases, you can
+ use this method (or module-level function) to obtain a filename for a
+ resource. If the resource is in an archive distribution (such as a zipped
+ egg), it will be extracted to a cache directory, and the filename within
+ the cache will be returned. If the named resource is a directory, then
+ all resources within that directory (including subdirectories) are also
+ extracted. If the named resource is a C extension or "eager resource"
+ (see the ``setuptools`` documentation for details), then all C extensions
+ and eager resources are extracted at the same time.
+
+ Archived resources are extracted to a cache location that can be managed by
+ the following two methods:
+
+``set_extraction_path(path)``
+ Set the base path where resources will be extracted to, if needed.
+
+ If you do not call this routine before any extractions take place, the
+ path defaults to the return value of ``get_default_cache()``. (Which is
+ based on the ``PYTHON_EGG_CACHE`` environment variable, with various
+ platform-specific fallbacks. See that routine's documentation for more
+ details.)
+
+ Resources are extracted to subdirectories of this path based upon
+ information given by the resource provider. You may set this to a
+ temporary directory, but then you must call ``cleanup_resources()`` to
+ delete the extracted files when done. There is no guarantee that
+ ``cleanup_resources()`` will be able to remove all extracted files. (On
+ Windows, for example, you can't unlink .pyd or .dll files that are still
+ in use.)
+
+ Note that you may not change the extraction path for a given resource
+ manager once resources have been extracted, unless you first call
+ ``cleanup_resources()``.
+
+``cleanup_resources(force=False)``
+ Delete all extracted resource files and directories, returning a list
+ of the file and directory names that could not be successfully removed.
+ This function does not have any concurrency protection, so it should
+ generally only be called when the extraction path is a temporary
+ directory exclusive to a single process. This method is not
+ automatically called; you must call it explicitly or register it as an
+ ``atexit`` function if you wish to ensure cleanup of a temporary
+ directory used for extractions.
+
+
+"Provider" Interface
+--------------------
+
+If you are implementing an ``IResourceProvider`` and/or ``IMetadataProvider``
+for a new distribution archive format, you may need to use the following
+``IResourceManager`` methods to co-ordinate extraction of resources to the
+filesystem. If you're not implementing an archive format, however, you have
+no need to use these methods. Unlike the other methods listed above, they are
+*not* available as top-level functions tied to the global ``ResourceManager``;
+you must therefore have an explicit ``ResourceManager`` instance to use them.
+
+``get_cache_path(archive_name, names=())``
+ Return absolute location in cache for `archive_name` and `names`
+
+ The parent directory of the resulting path will be created if it does
+ not already exist. `archive_name` should be the base filename of the
+ enclosing egg (which may not be the name of the enclosing zipfile!),
+ including its ".egg" extension. `names`, if provided, should be a
+ sequence of path name parts "under" the egg's extraction location.
+
+ This method should only be called by resource providers that need to
+ obtain an extraction location, and only for names they intend to
+ extract, as it tracks the generated names for possible cleanup later.
+
+``extraction_error()``
+ Raise an ``ExtractionError`` describing the active exception as interfering
+ with the extraction process. You should call this if you encounter any
+ OS errors extracting the file to the cache path; it will format the
+ operating system exception for you, and add other information to the
+ ``ExtractionError`` instance that may be needed by programs that want to
+ wrap or handle extraction errors themselves.
+
+``postprocess(tempname, filename)``
+ Perform any platform-specific postprocessing of `tempname`.
+ Resource providers should call this method ONLY after successfully
+ extracting a compressed resource. They must NOT call it on resources
+ that are already in the filesystem.
+
+ `tempname` is the current (temporary) name of the file, and `filename`
+ is the name it will be renamed to by the caller after this routine
+ returns.
+
+
+Metadata API
+============
+
+The metadata API is used to access metadata resources bundled in a pluggable
+distribution. Metadata resources are virtual files or directories containing
+information about the distribution, such as might be used by an extensible
+application or framework to connect "plugins". Like other kinds of resources,
+metadata resource names are ``/``-separated and should not contain ``..`` or
+begin with a ``/``. You should not use ``os.path`` routines to manipulate
+resource paths.
+
+The metadata API is provided by objects implementing the ``IMetadataProvider``
+or ``IResourceProvider`` interfaces. ``Distribution`` objects implement this
+interface, as do objects returned by the ``get_provider()`` function:
+
+``get_provider(package_or_requirement)``
+ If a package name is supplied, return an ``IResourceProvider`` for the
+ package. If a ``Requirement`` is supplied, resolve it by returning a
+ ``Distribution`` from the current working set (searching the current
+ ``Environment`` if necessary and adding the newly found ``Distribution``
+ to the working set). If the named package can't be imported, or the
+ ``Requirement`` can't be satisfied, an exception is raised.
+
+ NOTE: if you use a package name rather than a ``Requirement``, the object
+ you get back may not be a pluggable distribution, depending on the method
+ by which the package was installed. In particular, "development" packages
+ and "single-version externally-managed" packages do not have any way to
+ map from a package name to the corresponding project's metadata. Do not
+ write code that passes a package name to ``get_provider()`` and then tries
+ to retrieve project metadata from the returned object. It may appear to
+ work when the named package is in an ``.egg`` file or directory, but
+ it will fail in other installation scenarios. If you want project
+ metadata, you need to ask for a *project*, not a package.
+
+
+``IMetadataProvider`` Methods
+-----------------------------
+
+The methods provided by objects (such as ``Distribution`` instances) that
+implement the ``IMetadataProvider`` or ``IResourceProvider`` interfaces are:
+
+``has_metadata(name)``
+ Does the named metadata resource exist?
+
+``metadata_isdir(name)``
+ Is the named metadata resource a directory?
+
+``metadata_listdir(name)``
+ List of metadata names in the directory (like ``os.listdir()``)
+
+``get_metadata(name)``
+ Return the named metadata resource as a string. The data is read in binary
+ mode; i.e., the exact bytes of the resource file are returned.
+
+``get_metadata_lines(name)``
+ Yield named metadata resource as list of non-blank non-comment lines. This
+ is short for calling ``yield_lines(provider.get_metadata(name))``. See the
+ section on `yield_lines()`_ below for more information on the syntax it
+ recognizes.
+
+``run_script(script_name, namespace)``
+ Execute the named script in the supplied namespace dictionary. Raises
+ ``ResolutionError`` if there is no script by that name in the ``scripts``
+ metadata directory. `namespace` should be a Python dictionary, usually
+ a module dictionary if the script is being run as a module.
+
+
+Exceptions
+==========
+
+``pkg_resources`` provides a simple exception hierarchy for problems that may
+occur when processing requests to locate and activate packages::
+
+ ResolutionError
+ DistributionNotFound
+ VersionConflict
+ UnknownExtra
+
+ ExtractionError
+
+``ResolutionError``
+ This class is used as a base class for the other three exceptions, so that
+ you can catch all of them with a single "except" clause. It is also raised
+ directly for miscellaneous requirement-resolution problems like trying to
+ run a script that doesn't exist in the distribution it was requested from.
+
+``DistributionNotFound``
+ A distribution needed to fulfill a requirement could not be found.
+
+``VersionConflict``
+ The requested version of a project conflicts with an already-activated
+ version of the same project.
+
+``UnknownExtra``
+ One of the "extras" requested was not recognized by the distribution it
+ was requested from.
+
+``ExtractionError``
+ A problem occurred extracting a resource to the Python Egg cache. The
+ following attributes are available on instances of this exception:
+
+ manager
+ The resource manager that raised this exception
+
+ cache_path
+ The base directory for resource extraction
+
+ original_error
+ The exception instance that caused extraction to fail
+
+
+Supporting Custom Importers
+===========================
+
+By default, ``pkg_resources`` supports normal filesystem imports, and
+``zipimport`` importers. If you wish to use the ``pkg_resources`` features
+with other (PEP 302-compatible) importers or module loaders, you may need to
+register various handlers and support functions using these APIs:
+
+``register_finder(importer_type, distribution_finder)``
+ Register `distribution_finder` to find distributions in ``sys.path`` items.
+ `importer_type` is the type or class of a PEP 302 "Importer" (``sys.path``
+ item handler), and `distribution_finder` is a callable that, when passed a
+ path item, the importer instance, and an `only` flag, yields
+ ``Distribution`` instances found under that path item. (The `only` flag,
+ if true, means the finder should yield only ``Distribution`` objects whose
+ ``location`` is equal to the path item provided.)
+
+ See the source of the ``pkg_resources.find_on_path`` function for an
+ example finder function.
+
+``register_loader_type(loader_type, provider_factory)``
+ Register `provider_factory` to make ``IResourceProvider`` objects for
+ `loader_type`. `loader_type` is the type or class of a PEP 302
+ ``module.__loader__``, and `provider_factory` is a function that, when
+ passed a module object, returns an `IResourceProvider`_ for that module,
+ allowing it to be used with the `ResourceManager API`_.
+
+``register_namespace_handler(importer_type, namespace_handler)``
+ Register `namespace_handler` to declare namespace packages for the given
+ `importer_type`. `importer_type` is the type or class of a PEP 302
+ "importer" (sys.path item handler), and `namespace_handler` is a callable
+ with a signature like this::
+
+ def namespace_handler(importer, path_entry, moduleName, module):
+ # return a path_entry to use for child packages
+
+ Namespace handlers are only called if the relevant importer object has
+ already agreed that it can handle the relevant path item. The handler
+ should only return a subpath if the module ``__path__`` does not already
+ contain an equivalent subpath. Otherwise, it should return None.
+
+ For an example namespace handler, see the source of the
+ ``pkg_resources.file_ns_handler`` function, which is used for both zipfile
+ importing and regular importing.
+
+
+IResourceProvider
+-----------------
+
+``IResourceProvider`` is an abstract class that documents what methods are
+required of objects returned by a `provider_factory` registered with
+``register_loader_type()``. ``IResourceProvider`` is a subclass of
+``IMetadataProvider``, so objects that implement this interface must also
+implement all of the `IMetadataProvider Methods`_ as well as the methods
+shown here. The `manager` argument to the methods below must be an object
+that supports the full `ResourceManager API`_ documented above.
+
+``get_resource_filename(manager, resource_name)``
+ Return a true filesystem path for `resource_name`, co-ordinating the
+ extraction with `manager`, if the resource must be unpacked to the
+ filesystem.
+
+``get_resource_stream(manager, resource_name)``
+ Return a readable file-like object for `resource_name`.
+
+``get_resource_string(manager, resource_name)``
+ Return a string containing the contents of `resource_name`.
+
+``has_resource(resource_name)``
+ Does the package contain the named resource?
+
+``resource_isdir(resource_name)``
+ Is the named resource a directory? Return a false value if the resource
+ does not exist or is not a directory.
+
+``resource_listdir(resource_name)``
+ Return a list of the contents of the resource directory, ala
+ ``os.listdir()``. Requesting the contents of a non-existent directory may
+ raise an exception.
+
+Note, by the way, that your provider classes need not (and should not) subclass
+``IResourceProvider`` or ``IMetadataProvider``! These classes exist solely
+for documentation purposes and do not provide any useful implementation code.
+You may instead wish to subclass one of the `built-in resource providers`_.
+
+
+Built-in Resource Providers
+---------------------------
+
+``pkg_resources`` includes several provider classes that are automatically used
+where appropriate. Their inheritance tree looks like this::
+
+ NullProvider
+ EggProvider
+ DefaultProvider
+ PathMetadata
+ ZipProvider
+ EggMetadata
+ EmptyProvider
+ FileMetadata
+
+
+``NullProvider``
+ This provider class is just an abstract base that provides for common
+ provider behaviors (such as running scripts), given a definition for just
+ a few abstract methods.
+
+``EggProvider``
+ This provider class adds in some egg-specific features that are common
+ to zipped and unzipped eggs.
+
+``DefaultProvider``
+ This provider class is used for unpacked eggs and "plain old Python"
+ filesystem modules.
+
+``ZipProvider``
+ This provider class is used for all zipped modules, whether they are eggs
+ or not.
+
+``EmptyProvider``
+ This provider class always returns answers consistent with a provider that
+ has no metadata or resources. ``Distribution`` objects created without
+ a ``metadata`` argument use an instance of this provider class instead.
+ Since all ``EmptyProvider`` instances are equivalent, there is no need
+ to have more than one instance. ``pkg_resources`` therefore creates a
+ global instance of this class under the name ``empty_provider``, and you
+ may use it if you have need of an ``EmptyProvider`` instance.
+
+``PathMetadata(path, egg_info)``
+ Create an ``IResourceProvider`` for a filesystem-based distribution, where
+ `path` is the filesystem location of the importable modules, and `egg_info`
+ is the filesystem location of the distribution's metadata directory.
+ `egg_info` should usually be the ``EGG-INFO`` subdirectory of `path` for an
+ "unpacked egg", and a ``ProjectName.egg-info`` subdirectory of `path` for
+ a "development egg". However, other uses are possible for custom purposes.
+
+``EggMetadata(zipimporter)``
+ Create an ``IResourceProvider`` for a zipfile-based distribution. The
+ `zipimporter` should be a ``zipimport.zipimporter`` instance, and may
+ represent a "basket" (a zipfile containing multiple ".egg" subdirectories)
+ a specific egg *within* a basket, or a zipfile egg (where the zipfile
+ itself is a ".egg"). It can also be a combination, such as a zipfile egg
+ that also contains other eggs.
+
+``FileMetadata(path_to_pkg_info)``
+ Create an ``IResourceProvider`` that provides exactly one metadata
+ resource: ``PKG-INFO``. The supplied path should be a distutils PKG-INFO
+ file. This is basically the same as an ``EmptyProvider``, except that
+ requests for ``PKG-INFO`` will be answered using the contents of the
+ designated file. (This provider is used to wrap ``.egg-info`` files
+ installed by vendor-supplied system packages.)
+
+
+Utility Functions
+=================
+
+In addition to its high-level APIs, ``pkg_resources`` also includes several
+generally-useful utility routines. These routines are used to implement the
+high-level APIs, but can also be quite useful by themselves.
+
+
+Parsing Utilities
+-----------------
+
+``parse_version(version)``
+ Parse a project's version string, returning a value that can be used to
+ compare versions by chronological order. Semantically, the format is a
+ rough cross between distutils' ``StrictVersion`` and ``LooseVersion``
+ classes; if you give it versions that would work with ``StrictVersion``,
+ then they will compare the same way. Otherwise, comparisons are more like
+ a "smarter" form of ``LooseVersion``. It is *possible* to create
+ pathological version coding schemes that will fool this parser, but they
+ should be very rare in practice.
+
+ The returned value will be a tuple of strings. Numeric portions of the
+ version are padded to 8 digits so they will compare numerically, but
+ without relying on how numbers compare relative to strings. Dots are
+ dropped, but dashes are retained. Trailing zeros between alpha segments
+ or dashes are suppressed, so that e.g. "2.4.0" is considered the same as
+ "2.4". Alphanumeric parts are lower-cased.
+
+ The algorithm assumes that strings like "-" and any alpha string that
+ alphabetically follows "final" represents a "patch level". So, "2.4-1"
+ is assumed to be a branch or patch of "2.4", and therefore "2.4.1" is
+ considered newer than "2.4-1", which in turn is newer than "2.4".
+
+ Strings like "a", "b", "c", "alpha", "beta", "candidate" and so on (that
+ come before "final" alphabetically) are assumed to be pre-release versions,
+ so that the version "2.4" is considered newer than "2.4a1". Any "-"
+ characters preceding a pre-release indicator are removed. (In versions of
+ setuptools prior to 0.6a9, "-" characters were not removed, leading to the
+ unintuitive result that "0.2-rc1" was considered a newer version than
+ "0.2".)
+
+ Finally, to handle miscellaneous cases, the strings "pre", "preview", and
+ "rc" are treated as if they were "c", i.e. as though they were release
+ candidates, and therefore are not as new as a version string that does not
+ contain them. And the string "dev" is treated as if it were an "@" sign;
+ that is, a version coming before even "a" or "alpha".
+
+.. _yield_lines():
+
+``yield_lines(strs)``
+ Yield non-empty/non-comment lines from a string/unicode or a possibly-
+ nested sequence thereof. If `strs` is an instance of ``basestring``, it
+ is split into lines, and each non-blank, non-comment line is yielded after
+ stripping leading and trailing whitespace. (Lines whose first non-blank
+ character is ``#`` are considered comment lines.)
+
+ If `strs` is not an instance of ``basestring``, it is iterated over, and
+ each item is passed recursively to ``yield_lines()``, so that an arbitarily
+ nested sequence of strings, or sequences of sequences of strings can be
+ flattened out to the lines contained therein. So for example, passing
+ a file object or a list of strings to ``yield_lines`` will both work.
+ (Note that between each string in a sequence of strings there is assumed to
+ be an implicit line break, so lines cannot bridge two strings in a
+ sequence.)
+
+ This routine is used extensively by ``pkg_resources`` to parse metadata
+ and file formats of various kinds, and most other ``pkg_resources``
+ parsing functions that yield multiple values will use it to break up their
+ input. However, this routine is idempotent, so calling ``yield_lines()``
+ on the output of another call to ``yield_lines()`` is completely harmless.
+
+``split_sections(strs)``
+ Split a string (or possibly-nested iterable thereof), yielding ``(section,
+ content)`` pairs found using an ``.ini``-like syntax. Each ``section`` is
+ a whitespace-stripped version of the section name ("``[section]``")
+ and each ``content`` is a list of stripped lines excluding blank lines and
+ comment-only lines. If there are any non-blank, non-comment lines before
+ the first section header, they're yielded in a first ``section`` of
+ ``None``.
+
+ This routine uses ``yield_lines()`` as its front end, so you can pass in
+ anything that ``yield_lines()`` accepts, such as an open text file, string,
+ or sequence of strings. ``ValueError`` is raised if a malformed section
+ header is found (i.e. a line starting with ``[`` but not ending with
+ ``]``).
+
+ Note that this simplistic parser assumes that any line whose first nonblank
+ character is ``[`` is a section heading, so it can't support .ini format
+ variations that allow ``[`` as the first nonblank character on other lines.
+
+``safe_name(name)``
+ Return a "safe" form of a project's name, suitable for use in a
+ ``Requirement`` string, as a distribution name, or a PyPI project name.
+ All non-alphanumeric runs are condensed to single "-" characters, such that
+ a name like "The $$$ Tree" becomes "The-Tree". Note that if you are
+ generating a filename from this value you should combine it with a call to
+ ``to_filename()`` so all dashes ("-") are replaced by underscores ("_").
+ See ``to_filename()``.
+
+``safe_version(version)``
+ Similar to ``safe_name()`` except that spaces in the input become dots, and
+ dots are allowed to exist in the output. As with ``safe_name()``, if you
+ are generating a filename from this you should replace any "-" characters
+ in the output with underscores.
+
+``safe_extra(extra)``
+ Return a "safe" form of an extra's name, suitable for use in a requirement
+ string or a setup script's ``extras_require`` keyword. This routine is
+ similar to ``safe_name()`` except that non-alphanumeric runs are replaced
+ by a single underbar (``_``), and the result is lowercased.
+
+``to_filename(name_or_version)``
+ Escape a name or version string so it can be used in a dash-separated
+ filename (or ``#egg=name-version`` tag) without ambiguity. You
+ should only pass in values that were returned by ``safe_name()`` or
+ ``safe_version()``.
+
+
+Platform Utilities
+------------------
+
+``get_build_platform()``
+ Return this platform's identifier string. For Windows, the return value
+ is ``"win32"``, and for Mac OS X it is a string of the form
+ ``"macosx-10.4-ppc"``. All other platforms return the same uname-based
+ string that the ``distutils.util.get_platform()`` function returns.
+ This string is the minimum platform version required by distributions built
+ on the local machine. (Backward compatibility note: setuptools versions
+ prior to 0.6b1 called this function ``get_platform()``, and the function is
+ still available under that name for backward compatibility reasons.)
+
+``get_supported_platform()`` (New in 0.6b1)
+ This is the similar to ``get_build_platform()``, but is the maximum
+ platform version that the local machine supports. You will usually want
+ to use this value as the ``provided`` argument to the
+ ``compatible_platforms()`` function.
+
+``compatible_platforms(provided, required)``
+ Return true if a distribution built on the `provided` platform may be used
+ on the `required` platform. If either platform value is ``None``, it is
+ considered a wildcard, and the platforms are therefore compatible.
+ Likewise, if the platform strings are equal, they're also considered
+ compatible, and ``True`` is returned. Currently, the only non-equal
+ platform strings that are considered compatible are Mac OS X platform
+ strings with the same hardware type (e.g. ``ppc``) and major version
+ (e.g. ``10``) with the `provided` platform's minor version being less than
+ or equal to the `required` platform's minor version.
+
+``get_default_cache()``
+ Determine the default cache location for extracting resources from zipped
+ eggs. This routine returns the ``PYTHON_EGG_CACHE`` environment variable,
+ if set. Otherwise, on Windows, it returns a "Python-Eggs" subdirectory of
+ the user's "Application Data" directory. On all other systems, it returns
+ ``os.path.expanduser("~/.python-eggs")`` if ``PYTHON_EGG_CACHE`` is not
+ set.
+
+
+PEP 302 Utilities
+-----------------
+
+``get_importer(path_item)``
+ Retrieve a PEP 302 "importer" for the given path item (which need not
+ actually be on ``sys.path``). This routine simulates the PEP 302 protocol
+ for obtaining an "importer" object. It first checks for an importer for
+ the path item in ``sys.path_importer_cache``, and if not found it calls
+ each of the ``sys.path_hooks`` and caches the result if a good importer is
+ found. If no importer is found, this routine returns an ``ImpWrapper``
+ instance that wraps the builtin import machinery as a PEP 302-compliant
+ "importer" object. This ``ImpWrapper`` is *not* cached; instead a new
+ instance is returned each time.
+
+ (Note: When run under Python 2.5, this function is simply an alias for
+ ``pkgutil.get_importer()``, and instead of ``pkg_resources.ImpWrapper``
+ instances, it may return ``pkgutil.ImpImporter`` instances.)
+
+
+File/Path Utilities
+-------------------
+
+``ensure_directory(path)``
+ Ensure that the parent directory (``os.path.dirname``) of `path` actually
+ exists, using ``os.makedirs()`` if necessary.
+
+``normalize_path(path)``
+ Return a "normalized" version of `path`, such that two paths represent
+ the same filesystem location if they have equal ``normalized_path()``
+ values. Specifically, this is a shortcut for calling ``os.path.realpath``
+ and ``os.path.normcase`` on `path`. Unfortunately, on certain platforms
+ (notably Cygwin and Mac OS X) the ``normcase`` function does not accurately
+ reflect the platform's case-sensitivity, so there is always the possibility
+ of two apparently-different paths being equal on such platforms.
+
+History
+-------
+
+0.6c9
+ * Fix ``resource_listdir('')`` always returning an empty list for zipped eggs.
+
+0.6c7
+ * Fix package precedence problem where single-version eggs installed in
+ ``site-packages`` would take precedence over ``.egg`` files (or directories)
+ installed in ``site-packages``.
+
+0.6c6
+ * Fix extracted C extensions not having executable permissions under Cygwin.
+
+ * Allow ``.egg-link`` files to contain relative paths.
+
+ * Fix cache dir defaults on Windows when multiple environment vars are needed
+ to construct a path.
+
+0.6c4
+ * Fix "dev" versions being considered newer than release candidates.
+
+0.6c3
+ * Python 2.5 compatibility fixes.
+
+0.6c2
+ * Fix a problem with eggs specified directly on ``PYTHONPATH`` on
+ case-insensitive filesystems possibly not showing up in the default
+ working set, due to differing normalizations of ``sys.path`` entries.
+
+0.6b3
+ * Fixed a duplicate path insertion problem on case-insensitive filesystems.
+
+0.6b1
+ * Split ``get_platform()`` into ``get_supported_platform()`` and
+ ``get_build_platform()`` to work around a Mac versioning problem that caused
+ the behavior of ``compatible_platforms()`` to be platform specific.
+
+ * Fix entry point parsing when a standalone module name has whitespace
+ between it and the extras.
+
+0.6a11
+ * Added ``ExtractionError`` and ``ResourceManager.extraction_error()`` so that
+ cache permission problems get a more user-friendly explanation of the
+ problem, and so that programs can catch and handle extraction errors if they
+ need to.
+
+0.6a10
+ * Added the ``extras`` attribute to ``Distribution``, the ``find_plugins()``
+ method to ``WorkingSet``, and the ``__add__()`` and ``__iadd__()`` methods
+ to ``Environment``.
+
+ * ``safe_name()`` now allows dots in project names.
+
+ * There is a new ``to_filename()`` function that escapes project names and
+ versions for safe use in constructing egg filenames from a Distribution
+ object's metadata.
+
+ * Added ``Distribution.clone()`` method, and keyword argument support to other
+ ``Distribution`` constructors.
+
+ * Added the ``DEVELOP_DIST`` precedence, and automatically assign it to
+ eggs using ``.egg-info`` format.
+
+0.6a9
+ * Don't raise an error when an invalid (unfinished) distribution is found
+ unless absolutely necessary. Warn about skipping invalid/unfinished eggs
+ when building an Environment.
+
+ * Added support for ``.egg-info`` files or directories with version/platform
+ information embedded in the filename, so that system packagers have the
+ option of including ``PKG-INFO`` files to indicate the presence of a
+ system-installed egg, without needing to use ``.egg`` directories, zipfiles,
+ or ``.pth`` manipulation.
+
+ * Changed ``parse_version()`` to remove dashes before pre-release tags, so
+ that ``0.2-rc1`` is considered an *older* version than ``0.2``, and is equal
+ to ``0.2rc1``. The idea that a dash *always* meant a post-release version
+ was highly non-intuitive to setuptools users and Python developers, who
+ seem to want to use ``-rc`` version numbers a lot.
+
+0.6a8
+ * Fixed a problem with ``WorkingSet.resolve()`` that prevented version
+ conflicts from being detected at runtime.
+
+ * Improved runtime conflict warning message to identify a line in the user's
+ program, rather than flagging the ``warn()`` call in ``pkg_resources``.
+
+ * Avoid giving runtime conflict warnings for namespace packages, even if they
+ were declared by a different package than the one currently being activated.
+
+ * Fix path insertion algorithm for case-insensitive filesystems.
+
+ * Fixed a problem with nested namespace packages (e.g. ``peak.util``) not
+ being set as an attribute of their parent package.
+
+0.6a6
+ * Activated distributions are now inserted in ``sys.path`` (and the working
+ set) just before the directory that contains them, instead of at the end.
+ This allows e.g. eggs in ``site-packages`` to override unmanaged modules in
+ the same location, and allows eggs found earlier on ``sys.path`` to override
+ ones found later.
+
+ * When a distribution is activated, it now checks whether any contained
+ non-namespace modules have already been imported and issues a warning if
+ a conflicting module has already been imported.
+
+ * Changed dependency processing so that it's breadth-first, allowing a
+ depender's preferences to override those of a dependee, to prevent conflicts
+ when a lower version is acceptable to the dependee, but not the depender.
+
+ * Fixed a problem extracting zipped files on Windows, when the egg in question
+ has had changed contents but still has the same version number.
+
+0.6a4
+ * Fix a bug in ``WorkingSet.resolve()`` that was introduced in 0.6a3.
+
+0.6a3
+ * Added ``safe_extra()`` parsing utility routine, and use it for Requirement,
+ EntryPoint, and Distribution objects' extras handling.
+
+0.6a1
+ * Enhanced performance of ``require()`` and related operations when all
+ requirements are already in the working set, and enhanced performance of
+ directory scanning for distributions.
+
+ * Fixed some problems using ``pkg_resources`` w/PEP 302 loaders other than
+ ``zipimport``, and the previously-broken "eager resource" support.
+
+ * Fixed ``pkg_resources.resource_exists()`` not working correctly, along with
+ some other resource API bugs.
+
+ * Many API changes and enhancements:
+
+ * Added ``EntryPoint``, ``get_entry_map``, ``load_entry_point``, and
+ ``get_entry_info`` APIs for dynamic plugin discovery.
+
+ * ``list_resources`` is now ``resource_listdir`` (and it actually works)
+
+ * Resource API functions like ``resource_string()`` that accepted a package
+ name and resource name, will now also accept a ``Requirement`` object in
+ place of the package name (to allow access to non-package data files in
+ an egg).
+
+ * ``get_provider()`` will now accept a ``Requirement`` instance or a module
+ name. If it is given a ``Requirement``, it will return a corresponding
+ ``Distribution`` (by calling ``require()`` if a suitable distribution
+ isn't already in the working set), rather than returning a metadata and
+ resource provider for a specific module. (The difference is in how
+ resource paths are interpreted; supplying a module name means resources
+ path will be module-relative, rather than relative to the distribution's
+ root.)
+
+ * ``Distribution`` objects now implement the ``IResourceProvider`` and
+ ``IMetadataProvider`` interfaces, so you don't need to reference the (no
+ longer available) ``metadata`` attribute to get at these interfaces.
+
+ * ``Distribution`` and ``Requirement`` both have a ``project_name``
+ attribute for the project name they refer to. (Previously these were
+ ``name`` and ``distname`` attributes.)
+
+ * The ``path`` attribute of ``Distribution`` objects is now ``location``,
+ because it isn't necessarily a filesystem path (and hasn't been for some
+ time now). The ``location`` of ``Distribution`` objects in the filesystem
+ should always be normalized using ``pkg_resources.normalize_path()``; all
+ of the setuptools and EasyInstall code that generates distributions from
+ the filesystem (including ``Distribution.from_filename()``) ensure this
+ invariant, but if you use a more generic API like ``Distribution()`` or
+ ``Distribution.from_location()`` you should take care that you don't
+ create a distribution with an un-normalized filesystem path.
+
+ * ``Distribution`` objects now have an ``as_requirement()`` method that
+ returns a ``Requirement`` for the distribution's project name and version.
+
+ * Distribution objects no longer have an ``installed_on()`` method, and the
+ ``install_on()`` method is now ``activate()`` (but may go away altogether
+ soon). The ``depends()`` method has also been renamed to ``requires()``,
+ and ``InvalidOption`` is now ``UnknownExtra``.
+
+ * ``find_distributions()`` now takes an additional argument called ``only``,
+ that tells it to only yield distributions whose location is the passed-in
+ path. (It defaults to False, so that the default behavior is unchanged.)
+
+ * ``AvailableDistributions`` is now called ``Environment``, and the
+ ``get()``, ``__len__()``, and ``__contains__()`` methods were removed,
+ because they weren't particularly useful. ``__getitem__()`` no longer
+ raises ``KeyError``; it just returns an empty list if there are no
+ distributions for the named project.
+
+ * The ``resolve()`` method of ``Environment`` is now a method of
+ ``WorkingSet`` instead, and the ``best_match()`` method now uses a working
+ set instead of a path list as its second argument.
+
+ * There is a new ``pkg_resources.add_activation_listener()`` API that lets
+ you register a callback for notifications about distributions added to
+ ``sys.path`` (including the distributions already on it). This is
+ basically a hook for extensible applications and frameworks to be able to
+ search for plugin metadata in distributions added at runtime.
+
+0.5a13
+ * Fixed a bug in resource extraction from nested packages in a zipped egg.
+
+0.5a12
+ * Updated extraction/cache mechanism for zipped resources to avoid inter-
+ process and inter-thread races during extraction. The default cache
+ location can now be set via the ``PYTHON_EGGS_CACHE`` environment variable,
+ and the default Windows cache is now a ``Python-Eggs`` subdirectory of the
+ current user's "Application Data" directory, if the ``PYTHON_EGGS_CACHE``
+ variable isn't set.
+
+0.5a10
+ * Fix a problem with ``pkg_resources`` being confused by non-existent eggs on
+ ``sys.path`` (e.g. if a user deletes an egg without removing it from the
+ ``easy-install.pth`` file).
+
+ * Fix a problem with "basket" support in ``pkg_resources``, where egg-finding
+ never actually went inside ``.egg`` files.
+
+ * Made ``pkg_resources`` import the module you request resources from, if it's
+ not already imported.
+
+0.5a4
+ * ``pkg_resources.AvailableDistributions.resolve()`` and related methods now
+ accept an ``installer`` argument: a callable taking one argument, a
+ ``Requirement`` instance. The callable must return a ``Distribution``
+ object, or ``None`` if no distribution is found. This feature is used by
+ EasyInstall to resolve dependencies by recursively invoking itself.
+
+0.4a4
+ * Fix problems with ``resource_listdir()``, ``resource_isdir()`` and resource
+ directory extraction for zipped eggs.
+
+0.4a3
+ * Fixed scripts not being able to see a ``__file__`` variable in ``__main__``
+
+ * Fixed a problem with ``resource_isdir()`` implementation that was introduced
+ in 0.4a2.
+
+0.4a1
+ * Fixed a bug in requirements processing for exact versions (i.e. ``==`` and
+ ``!=``) when only one condition was included.
+
+ * Added ``safe_name()`` and ``safe_version()`` APIs to clean up handling of
+ arbitrary distribution names and versions found on PyPI.
+
+0.3a4
+ * ``pkg_resources`` now supports resource directories, not just the resources
+ in them. In particular, there are ``resource_listdir()`` and
+ ``resource_isdir()`` APIs.
+
+ * ``pkg_resources`` now supports "egg baskets" -- .egg zipfiles which contain
+ multiple distributions in subdirectories whose names end with ``.egg``.
+ Having such a "basket" in a directory on ``sys.path`` is equivalent to
+ having the individual eggs in that directory, but the contained eggs can
+ be individually added (or not) to ``sys.path``. Currently, however, there
+ is no automated way to create baskets.
+
+ * Namespace package manipulation is now protected by the Python import lock.
+
+0.3a1
+ * Initial release.
+
diff --git a/vendor/distribute-0.6.36/docs/python3.txt b/vendor/distribute-0.6.36/docs/python3.txt
new file mode 100644
index 0000000000000000000000000000000000000000..2f6cde4ab35ec9ddfd3d551310cac2586091ab46
--- /dev/null
+++ b/vendor/distribute-0.6.36/docs/python3.txt
@@ -0,0 +1,121 @@
+=====================================================
+Supporting both Python 2 and Python 3 with Distribute
+=====================================================
+
+Starting with version 0.6.2, Distribute supports Python 3. Installing and
+using distribute for Python 3 code works exactly the same as for Python 2
+code, but Distribute also helps you to support Python 2 and Python 3 from
+the same source code by letting you run 2to3 on the code as a part of the
+build process, by setting the keyword parameter ``use_2to3`` to True.
+
+
+Distribute as help during porting
+=================================
+
+Distribute can make the porting process much easier by automatically running
+2to3 as a part of the test running. To do this you need to configure the
+setup.py so that you can run the unit tests with ``python setup.py test``.
+
+See :ref:`test` for more information on this.
+
+Once you have the tests running under Python 2, you can add the use_2to3
+keyword parameters to setup(), and start running the tests under Python 3.
+The test command will now first run the build command during which the code
+will be converted with 2to3, and the tests will then be run from the build
+directory, as opposed from the source directory as is normally done.
+
+Distribute will convert all Python files, and also all doctests in Python
+files. However, if you have doctests located in separate text files, these
+will not automatically be converted. By adding them to the
+``convert_2to3_doctests`` keyword parameter Distrubute will convert them as
+well.
+
+By default, the conversion uses all fixers in the ``lib2to3.fixers`` package.
+To use additional fixers, the parameter ``use_2to3_fixers`` can be set
+to a list of names of packages containing fixers. To exclude fixers, the
+parameter ``use_2to3_exclude_fixers`` can be set to fixer names to be
+skipped.
+
+A typical setup.py can look something like this::
+
+ from setuptools import setup
+
+ setup(
+ name='your.module',
+ version = '1.0',
+ description='This is your awesome module',
+ author='You',
+ author_email='your@email',
+ package_dir = {'': 'src'},
+ packages = ['your', 'you.module'],
+ test_suite = 'your.module.tests',
+ use_2to3 = True,
+ convert_2to3_doctests = ['src/your/module/README.txt'],
+ use_2to3_fixers = ['your.fixers'],
+ use_2to3_exclude_fixers = ['lib2to3.fixes.fix_import'],
+ )
+
+Differential conversion
+-----------------------
+
+Note that a file will only be copied and converted during the build process
+if the source file has been changed. If you add a file to the doctests
+that should be converted, it will not be converted the next time you run
+the tests, since it hasn't been modified. You need to remove it from the
+build directory. Also if you run the build, install or test commands before
+adding the use_2to3 parameter, you will have to remove the build directory
+before you run the test command, as the files otherwise will seem updated,
+and no conversion will happen.
+
+In general, if code doesn't seem to be converted, deleting the build directory
+and trying again is a good saferguard against the build directory getting
+"out of sync" with the source directory.
+
+Distributing Python 3 modules
+=============================
+
+You can distribute your modules with Python 3 support in different ways. A
+normal source distribution will work, but can be slow in installing, as the
+2to3 process will be run during the install. But you can also distribute
+the module in binary format, such as a binary egg. That egg will contain the
+already converted code, and hence no 2to3 conversion is needed during install.
+
+Advanced features
+=================
+
+If you don't want to run the 2to3 conversion on the doctests in Python files,
+you can turn that off by setting ``setuptools.use_2to3_on_doctests = False``.
+
+Note on compatibility with setuptools
+=====================================
+
+Setuptools do not know about the new keyword parameters to support Python 3.
+As a result it will warn about the unknown keyword parameters if you use
+setuptools instead of Distribute under Python 2. This is not an error, and
+install process will continue as normal, but if you want to get rid of that
+error this is easy. Simply conditionally add the new parameters into an extra
+dict and pass that dict into setup()::
+
+ from setuptools import setup
+ import sys
+
+ extra = {}
+ if sys.version_info >= (3,):
+ extra['use_2to3'] = True
+ extra['convert_2to3_doctests'] = ['src/your/module/README.txt']
+ extra['use_2to3_fixers'] = ['your.fixers']
+
+ setup(
+ name='your.module',
+ version = '1.0',
+ description='This is your awesome module',
+ author='You',
+ author_email='your@email',
+ package_dir = {'': 'src'},
+ packages = ['your', 'you.module'],
+ test_suite = 'your.module.tests',
+ **extra
+ )
+
+This way the parameters will only be used under Python 3, where you have to
+use Distribute.
diff --git a/vendor/distribute-0.6.36/docs/roadmap.txt b/vendor/distribute-0.6.36/docs/roadmap.txt
new file mode 100644
index 0000000000000000000000000000000000000000..ea5070eaaf8797a273928df2b3791ac669920cdb
--- /dev/null
+++ b/vendor/distribute-0.6.36/docs/roadmap.txt
@@ -0,0 +1,86 @@
+=======
+Roadmap
+=======
+
+Distribute has two branches:
+
+- 0.6.x : provides a Setuptools-0.6cX compatible version
+- 0.7.x : will provide a refactoring
+
+0.6.x
+=====
+
+Not "much" is going to happen here, we want this branch to be helpful
+to the community *today* by addressing the 40-or-so bugs
+that were found in Setuptools and never fixed. This is eventually
+happen soon because its development is
+fast : there are up to 5 commiters that are working on it very often
+(and the number grows weekly.)
+
+The biggest issue with this branch is that it is providing the same
+packages and modules setuptools does, and this
+requires some bootstrapping work where we make sure once Distribute is
+installed, all Distribution that requires Setuptools
+will continue to work. This is done by faking the metadata of
+Setuptools 0.6c9. That's the only way we found to do this.
+
+There's one major thing though: thanks to the work of Lennart, Alex,
+Martin, this branch supports Python 3,
+which is great to have to speed up Py3 adoption.
+
+The goal of the 0.6.x is to remove as much bugs as we can, and try if
+possible to remove the patches done
+on Distutils. We will support 0.6.x maintenance for years and we will
+promote its usage everywhere instead of
+Setuptools.
+
+Some new commands are added there, when they are helpful and don't
+interact with the rest. I am thinking
+about "upload_docs" that let you upload documentation to PyPI. The
+goal is to move it to Distutils
+at some point, if the documentation feature of PyPI stays and starts to be used.
+
+0.7.x
+=====
+
+We've started to refactor Distribute with this roadmap in mind (and
+no, as someone said, it's not vaporware,
+we've done a lot already)
+
+- 0.7.x can be installed and used with 0.6.x
+
+- easy_install is going to be deprecated ! use Pip !
+
+- the version system will be deprecated, in favor of the one in Distutils
+
+- no more Distutils monkey-patch that happens once you use the code
+ (things like 'from distutils import cmd; cmd.Command = CustomCommand')
+
+- no more custom site.py (that is: if something misses in Python's
+ site.py we'll add it there instead of patching it)
+
+- no more namespaced packages system, if PEP 382 (namespaces package
+ support) makes it to 2.7
+
+- The code is splitted in many packages and might be distributed under
+ several distributions.
+
+ - distribute.resources: that's the old pkg_resources, but
+ reorganized in clean, pep-8 modules. This package will
+ only contain the query APIs and will focus on being PEP 376
+ compatible. We will promote its usage and see if Pip wants
+ to use it as a basis.
+ It will probably shrink a lot though, once the stdlib provides PEP 376 support.
+
+ - distribute.entrypoints: that's the old pkg_resources entry points
+ system, but on its own. it uses distribute.resources
+
+ - distribute.index: that's package_index and a few other things.
+ everything required to interact with PyPI. We will promote
+ its usage and see if Pip wants to use it as a basis.
+
+ - distribute.core (might be renamed to main): that's everything
+ else, and uses the other packages.
+
+Goal: A first release before (or when) Python 2.7 / 3.2 is out.
+
diff --git a/vendor/distribute-0.6.36/docs/setuptools.txt b/vendor/distribute-0.6.36/docs/setuptools.txt
new file mode 100644
index 0000000000000000000000000000000000000000..fe8bb3f6155318a86e20cf1a67b12b63c20897fc
--- /dev/null
+++ b/vendor/distribute-0.6.36/docs/setuptools.txt
@@ -0,0 +1,3230 @@
+==================================================
+Building and Distributing Packages with Distribute
+==================================================
+
+``Distribute`` is a collection of enhancements to the Python ``distutils``
+(for Python 2.3.5 and up on most platforms; 64-bit platforms require a minimum
+of Python 2.4) that allow you to more easily build and distribute Python
+packages, especially ones that have dependencies on other packages.
+
+Packages built and distributed using ``setuptools`` look to the user like
+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`_ (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.
+
+.. _bootstrap module: http://nightly.ziade.org/distribute_setup.py
+
+Feature Highlights:
+
+* Automatically find/download/install/upgrade dependencies at build time using
+ the `EasyInstall tool <http://peak.telecommunity.com/DevCenter/EasyInstall>`_,
+ which supports downloading via HTTP, FTP, Subversion, and SourceForge, and
+ automatically scans web pages linked from PyPI to find download links. (It's
+ the closest thing to CPAN currently available for Python.)
+
+* Create `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_ -
+ 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
+ accessing data files in zipped packages too.)
+
+* Automatically include all packages in your source tree, without listing them
+ individually in setup.py
+
+* Automatically include all relevant files in your source distributions,
+ without needing to create a ``MANIFEST.in`` file, and without having to force
+ regeneration of the ``MANIFEST`` file when your source tree changes.
+
+* Automatically generate wrapper scripts or Windows (console and GUI) .exe
+ files for any number of "main" functions in your project. (Note: this is not
+ a py2exe replacement; the .exe files rely on the local Python installation.)
+
+* Transparent Pyrex support, so that your setup.py can list ``.pyx`` files and
+ still work even when the end-user doesn't have Pyrex installed (as long as
+ you include the Pyrex-generated C in your source distribution)
+
+* Command aliases - create project-specific, per-user, or site-wide shortcut
+ names for commonly used commands and options
+
+* PyPI upload support - upload your source distributions and eggs to PyPI
+
+* Deploy your project in "development mode", such that it's available on
+ ``sys.path``, yet can still be edited directly from its source checkout.
+
+* Easily extend the distutils with new commands or ``setup()`` arguments, and
+ distribute/reuse your extensions for multiple projects, without copying code.
+
+* Create extensible applications and frameworks that automatically discover
+ 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`_, 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**
+
+.. _distribute_setup.py: `bootstrap module`_
+
+
+-----------------
+Developer's Guide
+-----------------
+
+
+Installing ``setuptools``
+=========================
+
+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.
+
+.. _EasyInstall Installation Instructions: http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions
+
+.. _Custom Installation Locations: http://peak.telecommunity.com/DevCenter/EasyInstall#custom-installation-locations
+
+If you want the current in-development version of setuptools, you should first
+install a stable version, and then run::
+
+ distribute_setup.py setuptools==dev
+
+This will download and install the latest development (i.e. unstable) version
+of setuptools from the Python Subversion sandbox.
+
+
+Basic Use
+=========
+
+For basic use of setuptools, just import things from setuptools instead of
+the distutils. Here's a minimal setup script using setuptools::
+
+ from setuptools import setup, find_packages
+ setup(
+ name = "HelloWorld",
+ version = "0.1",
+ packages = find_packages(),
+ )
+
+As you can see, it doesn't take much to use setuptools in a project.
+Just by doing the above, this project will be able to produce eggs, upload to
+PyPI, and automatically include all packages in the directory where the
+setup.py lives. See the `Command Reference`_ section below to see what
+commands you can give to this setup script.
+
+Of course, before you release your project to PyPI, you'll want to add a bit
+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",
+ version = "0.1",
+ packages = find_packages(),
+ scripts = ['say_hello.py'],
+
+ # Project uses reStructuredText, so ensure that the docutils get
+ # installed or upgraded on the target machine
+ install_requires = ['docutils>=0.3'],
+
+ package_data = {
+ # If any package contains *.txt or *.rst files, include them:
+ '': ['*.txt', '*.rst'],
+ # And include any *.msg files found in the 'hello' package, too:
+ 'hello': ['*.msg'],
+ },
+
+ # metadata for upload to PyPI
+ author = "Me",
+ author_email = "me@example.com",
+ description = "This is an Example Package",
+ license = "PSF",
+ keywords = "hello world example examples",
+ url = "http://example.com/HelloWorld/", # project home page, if any
+
+ # could also include long_description, download_url, classifiers, etc.
+ )
+
+In the sections that follow, we'll explain what most of these ``setup()``
+arguments do (except for the metadata ones), and the various ways you might use
+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 or dash
+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`` and ``2.4-c1`` all
+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 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')
+ True
+ >>> 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
+====================================
+
+The following keyword arguments to ``setup()`` are added or changed by
+``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`_. 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
+ safely installed and run from a zip file. If this argument is not
+ supplied, the ``bdist_egg`` command will have to analyze all of your
+ project's contents for possible problems each time it buids an egg.
+
+``install_requires``
+ A string or list of strings specifying what other distributions need to
+ be installed when this one is. See the section below on `Declaring
+ Dependencies`_ for details and examples of the format of this argument.
+
+``entry_points``
+ A dictionary mapping entry point group names to strings or lists of strings
+ defining the entry points. Entry points are used to support dynamic
+ discovery of services or plugins provided by a project. See `Dynamic
+ Discovery of Services and Plugins`_ for details and examples of the format
+ of this argument. In addition, this keyword is used to support `Automatic
+ Script Creation`_.
+
+``extras_require``
+ A dictionary mapping names of "extras" (optional features of your project)
+ to strings or lists of strings specifying what other distributions must be
+ installed to support those features. See the section below on `Declaring
+ Dependencies`_ for details and examples of the format of this argument.
+
+``setup_requires``
+ A string or list of strings specifying what other distributions need to
+ be present in order for the *setup script* to run. ``setuptools`` will
+ attempt to obtain these (even going so far as to download them using
+ ``EasyInstall``) before processing the rest of the setup script or commands.
+ This argument is needed if you are using distutils extensions as part of
+ your build process; for example, extensions that process setup() arguments
+ and turn them into EGG-INFO metadata files.
+
+ (Note: projects listed in ``setup_requires`` will NOT be automatically
+ installed on the system where the setup script is being run. They are
+ simply downloaded to the setup directory if they're not locally available
+ already. If you want them to be installed, as well as being available
+ 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
+ distributions. For example, Zope 3's ``zope`` package is a namespace
+ package, because subpackages like ``zope.interface`` and ``zope.publisher``
+ may be distributed separately. The egg runtime system can automatically
+ merge such subpackages into a single parent package at runtime, as long
+ as you declare them in each project that contains any subpackages of the
+ namespace package, and as long as the namespace package's ``__init__.py``
+ does not contain any code other than a namespace declaration. See the
+ section below on `Namespace Packages`_ for more information.
+
+``test_suite``
+ 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
+ imported. This argument is only useful if the project will be installed as
+ a zipfile, and there is a need to have all of the listed resources be
+ extracted to the filesystem *as a unit*. Resources listed here
+ should be '/'-separated paths, relative to the source root, so to list a
+ resource ``foo.png`` in package ``bar.baz``, you would include the string
+ ``bar/baz/foo.png`` in this argument.
+
+ If you only need to obtain resources one at a time, or you don't have any C
+ extensions that access other files in the project (such as data files or
+ shared libraries), you probably do NOT need this argument and shouldn't
+ mess with it. For more details on how this argument works, see the section
+ below on `Automatic Resource Extraction`_.
+
+``use_2to3``
+ Convert the source code from Python 2 to Python 3 with 2to3 during the
+ build process. See :doc:`python3` for more details.
+
+``convert_2to3_doctests``
+ List of doctest source files that need to be converted with 2to3.
+ See :doc:`python3` for more details.
+
+``use_2to3_fixers``
+ A list of modules to search for additional fixers to be used during
+ the 2to3 conversion. See :doc:`python3` for more details.
+
+
+Using ``find_packages()``
+-------------------------
+
+For simple projects, it's usually easy enough to manually add packages to
+the ``packages`` argument of ``setup()``. However, for very large projects
+(Twisted, PEAK, Zope, Chandler, etc.), it can be a big burden to keep the
+package list updated. That's what ``setuptools.find_packages()`` is for.
+
+``find_packages()`` takes a source directory, and a list of package names or
+patterns to exclude. If omitted, the source directory defaults to the same
+directory as the setup script. Some projects use a ``src`` or ``lib``
+directory as the root of their source tree, and those projects would of course
+use ``"src"`` or ``"lib"`` as the first argument to ``find_packages()``. (And
+such projects also need something like ``package_dir = {'':'src'}`` in their
+``setup()`` arguments, but that's just a normal distutils thing.)
+
+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.
+
+Exclusion patterns are package names, optionally including wildcards. For
+example, ``find_packages(exclude=["*.tests"])`` will exclude all packages whose
+last name part is ``tests``. Or, ``find_packages(exclude=["*.tests",
+"*.tests.*"])`` will also exclude any subpackages of packages named ``tests``,
+but it still won't exclude a top-level ``tests`` package or the children
+thereof. In fact, if you really want no ``tests`` packages at all, you'll need
+something like this::
+
+ find_packages(exclude=["*.tests", "*.tests.*", "tests.*", "tests"])
+
+in order to cover all the bases. Really, the exclusion patterns are intended
+to cover simpler use cases than this, like excluding a single, specified
+package and its subpackages.
+
+Regardless of the target directory or exclusions, the ``find_packages()``
+function returns a list of package names suitable for use as the ``packages``
+argument to ``setup()``, and so is usually the easiest way to set that
+argument in your setup script. Especially since it frees you from having to
+remember to modify your setup script whenever your project grows additional
+top-level packages or subpackages.
+
+
+Automatic Script Creation
+=========================
+
+Packaging and installing scripts can be a bit awkward with the distutils. For
+one thing, there's no easy way to have a script's filename match local
+conventions on both Windows and POSIX platforms. For another, you often have
+to create a separate file just for the "main" script, when your actual "main"
+is a function in a module somewhere. And even in Python 2.4, using the ``-m``
+option only works for actual ``.py`` files that aren't installed in a package.
+
+``setuptools`` fixes all of these problems by automatically generating scripts
+for you with the correct extension, and on Windows it will even create an
+``.exe`` file so that users don't have to change their ``PATHEXT`` settings.
+The way to use this feature is to define "entry points" in your setup script
+that indicate what function the generated script should import and run. For
+example, to create two console scripts called ``foo`` and ``bar``, and a GUI
+script called ``baz``, you might do something like this::
+
+ setup(
+ # other arguments here...
+ entry_points = {
+ 'console_scripts': [
+ 'foo = my_package.some_module:main_func',
+ 'bar = other_module:some_func',
+ ],
+ 'gui_scripts': [
+ 'baz = my_package_gui.start_func',
+ ]
+ }
+ )
+
+When this project is installed on non-Windows platforms (using "setup.py
+install", "setup.py develop", or by using EasyInstall), a set of ``foo``,
+``bar``, and ``baz`` scripts will be installed that import ``main_func`` and
+``some_func`` from the specified modules. The functions you specify are called
+with no arguments, and their return value is passed to ``sys.exit()``, so you
+can return an errorlevel or message to print to stderr.
+
+On Windows, a set of ``foo.exe``, ``bar.exe``, and ``baz.exe`` launchers are
+created, alongside a set of ``foo.py``, ``bar.py``, and ``baz.pyw`` files. The
+``.exe`` wrappers find and execute the right version of Python to run the
+``.py`` or ``.pyw`` file.
+
+You may define as many "console script" and "gui script" entry points as you
+like, and each one can optionally specify "extras" that it depends on, that
+will be added to ``sys.path`` when the script is run. For more information on
+"extras", see the section below on `Declaring Extras`_. For more information
+on "entry points" in general, see the section below on `Dynamic Discovery of
+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 distribute_setup 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
+======================
+
+``setuptools`` supports automatically installing dependencies when a package is
+installed, and including information about dependencies in Python Eggs (so that
+package management tools like EasyInstall can use the information).
+
+``setuptools`` and ``pkg_resources`` use a common syntax for specifying a
+project's required dependencies. This syntax consists of a project's PyPI
+name, optionally followed by a comma-separated list of "extras" in square
+brackets, optionally followed by a comma-separated list of version
+specifiers. A version specifier is one of the operators ``<``, ``>``, ``<=``,
+``>=``, ``==`` or ``!=``, followed by a version identifier. Tokens may be
+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
+
+ # comment lines and \ continuations are allowed in requirement strings
+ BazSpam ==1.1, ==1.2, ==1.3, ==1.4, ==1.5, \
+ ==1.6, ==1.7 # and so are line-end comments
+
+ PEAK[FastCGI, reST]>=0.5a4
+
+ setuptools==0.5a7
+
+The simplest way to include requirement specifiers is to use the
+``install_requires`` argument to ``setup()``. It takes a string or list of
+strings containing requirement specifiers. If you include more than one
+requirement in a string, each requirement must begin on a new line.
+
+This has three effects:
+
+1. When your project is installed, either by using EasyInstall, ``setup.py
+ install``, or ``setup.py develop``, all of the dependencies not already
+ installed will be located (via PyPI), downloaded, built (if necessary),
+ and installed.
+
+2. Any scripts in your project will be installed with wrappers that verify
+ the availability of the specified dependencies at runtime, and ensure that
+ the correct versions are added to ``sys.path`` (e.g. if multiple versions
+ have been installed).
+
+3. Python Egg distributions will include a metadata file listing the
+ dependencies.
+
+Note, by the way, that if you declare your dependencies in ``setup.py``, you do
+*not* need to use the ``require()`` function in your scripts or modules, as
+long as you either install the project or use ``setup.py develop`` to do
+development work on it. (See `"Development Mode"`_ below for more details on
+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,
+- a single ``.py`` file, or
+- a VCS repository (Subversion, Mercurial, or Git).
+
+You just need to add some URLs to the ``dependency_links`` argument to
+``setup()``.
+
+The URLs must be either:
+
+1. direct download URLs,
+2. the URLs of web pages that contain direct download links, or
+3. the repository's URL
+
+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.
+
+In the case of a VCS checkout, you should also append ``#egg=project-version``
+in order to identify for what package that checkout should be used. You can
+append ``@REV`` to the URL's path (before the fragment) to specify a revision.
+Additionally, you can also force the VCS being used by prepending the URL with
+a certain prefix. Currently available are:
+
+- ``svn+URL`` for Subversion,
+- ``git+URL`` for Git, and
+- ``hg+URL`` for Mercurial
+
+A more complete example would be:
+
+ ``vcs+proto://host/path@revision#egg=project-version``
+
+Be careful with the version. It should match the one inside the project files.
+If you want do disregard the version, you have to omit it both in the
+``requires`` and in the URL's fragment.
+
+This will do a checkout (or a clone, in Git and Mercurial parlance) to a
+temporary folder and run ``setup.py bdist_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:
+
+
+Declaring "Extras" (optional features with their own dependencies)
+------------------------------------------------------------------
+
+Sometimes a project has "recommended" dependencies, that are not required for
+all uses of the project. For example, a project might offer optional PDF
+output if ReportLab is installed, and reStructuredText support if docutils is
+installed. These optional features are called "extras", and setuptools allows
+you to define their requirements as well. In this way, other projects that
+require these optional features can force the additional requirements to be
+installed, by naming the desired extras in their ``install_requires``.
+
+For example, let's say that Project A offers optional PDF and reST support::
+
+ setup(
+ name="Project-A",
+ ...
+ extras_require = {
+ 'PDF': ["ReportLab>=1.2", "RXP"],
+ 'reST': ["docutils>=0.3"],
+ }
+ )
+
+As you can see, the ``extras_require`` argument takes a dictionary mapping
+names of "extra" features, to strings or lists of strings describing those
+features' requirements. These requirements will *not* be automatically
+installed unless another package depends on them (directly or indirectly) by
+including the desired "extras" in square brackets after the associated project
+name. (Or if the extras were listed in a requirement spec on the EasyInstall
+command line.)
+
+Extras can be used by a project's `entry points`_ to specify dynamic
+dependencies. For example, if Project A includes a "rst2pdf" script, it might
+declare it like this, so that the "PDF" requirements are only resolved if the
+"rst2pdf" script is run::
+
+ setup(
+ name="Project-A",
+ ...
+ entry_points = {
+ 'console_scripts':
+ ['rst2pdf = project_a.tools.pdfgen [PDF]'],
+ ['rst2html = project_a.tools.htmlgen'],
+ # more script entry points ...
+ }
+ )
+
+Projects can also use another project's extras when specifying dependencies.
+For example, if project B needs "project A" with PDF support installed, it
+might declare the dependency like this::
+
+ setup(
+ name="Project-B",
+ install_requires = ["Project-A[PDF]"],
+ ...
+ )
+
+This will cause ReportLab to be installed along with project A, if project B is
+installed -- even if project A was already installed. In this way, a project
+can encapsulate groups of optional "downstream dependencies" under a feature
+name, so that packages that depend on it don't have to know what the downstream
+dependencies are. If a later version of Project A builds in PDF support and
+no longer needs ReportLab, or if it ends up needing other dependencies besides
+ReportLab in order to provide PDF support, Project B's setup information does
+not need to change, but the right packages will still be installed if needed.
+
+Note, by the way, that if a project ends up not needing any other packages to
+support a feature, it should keep an empty requirements list for that feature
+in its ``extras_require`` argument, so that packages depending on that feature
+don't break (due to an invalid feature name). For example, if Project A above
+builds in PDF support and no longer needs ReportLab, it could change its
+setup to this::
+
+ setup(
+ name="Project-A",
+ ...
+ extras_require = {
+ 'PDF': [],
+ 'reST': ["docutils>=0.3"],
+ }
+ )
+
+so that Package B doesn't have to remove the ``[PDF]`` from its requirement
+specifier.
+
+
+Including Data Files
+====================
+
+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 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 the data files are not under version control, or are not in a supported
+version control system, or 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(
+ ...
+ package_data = {
+ # If any package contains *.txt or *.rst files, include them:
+ '': ['*.txt', '*.rst'],
+ # And include any *.msg files found in the 'hello' package, too:
+ 'hello': ['*.msg'],
+ }
+ )
+
+The ``package_data`` argument is a dictionary that maps from package names to
+lists of glob patterns. The globs may include subdirectory names, if the data
+files are contained in a subdirectory of the package. For example, if the
+package tree looks like this::
+
+ setup.py
+ src/
+ mypkg/
+ __init__.py
+ mypkg.txt
+ data/
+ somefile.dat
+ otherdata.dat
+
+The setuptools setup file might look 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
+
+ package_data = {
+ # If any package contains *.txt files, include them:
+ '': ['*.txt'],
+ # And include any *.dat files found in the 'data' subdirectory
+ # of the 'mypkg' package, also:
+ 'mypkg': ['data/*.dat'],
+ }
+ )
+
+Notice that if you list patterns in ``package_data`` under the empty string,
+these patterns are used to find files in every package, even ones that also
+have their own patterns listed. Thus, in the above example, the ``mypkg.txt``
+file gets included even though it's not listed in the patterns for ``mypkg``.
+
+Also notice that if you use paths, you *must* use a forward slash (``/``) as
+the path separator, even if you are on Windows. Setuptools automatically
+converts slashes to appropriate platform-specific separators at build time.
+
+(Note: although the ``package_data`` argument was previously only available in
+``setuptools``, it was also added to the Python ``distutils`` package as of
+Python 2.4; there is `some documentation for the feature`__ available on the
+python.org website. If using the setuptools-specific ``include_package_data``
+argument, files specified by ``package_data`` will *not* be automatically
+added to the manifest unless they are tracked by a supported version control
+system, or are listed in the MANIFEST.in file.)
+
+__ 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
+-------------------------------
+
+Typically, existing programs manipulate a package's ``__file__`` attribute in
+order to find the location of data files. However, this manipulation isn't
+compatible with PEP 302-based import hooks, including importing from zip files
+and Python Eggs. It is strongly recommended that, if you are using data files,
+you should use the `Resource Management API`_ of ``pkg_resources`` to access
+them. The ``pkg_resources`` module is distributed as part of setuptools, so if
+you're using setuptools to distribute your package, there is no reason not to
+use its resource management API. See also `Accessing Package Resources`_ for
+a quick example of converting code that uses ``__file__`` to use
+``pkg_resources`` instead.
+
+.. _Resource Management API: http://peak.telecommunity.com/DevCenter/PythonEggs#resource-management
+.. _Accessing Package Resources: http://peak.telecommunity.com/DevCenter/PythonEggs#accessing-package-resources
+
+
+Non-Package Data Files
+----------------------
+
+The ``distutils`` normally install general "data files" to a platform-specific
+location (e.g. ``/usr/share``). This feature intended to be used for things
+like documentation, example configuration files, and the like. ``setuptools``
+does not install these data files in a separate location, however. They are
+bundled inside the egg file or directory, alongside the Python modules and
+packages. The data files can also be accessed using the `Resource Management
+API`_, by specifying a ``Requirement`` instead of a package name::
+
+ from pkg_resources import Requirement, resource_filename
+ filename = resource_filename(Requirement.parse("MyProject"),"sample.conf")
+
+The above code will obtain the filename of the "sample.conf" file in the data
+root of the "MyProject" distribution.
+
+Note, by the way, that this encapsulation of data files means that you can't
+actually install data files to some arbitrary location on a user's machine;
+this is a feature, not a bug. You can always include a script in your
+distribution that extracts and copies your the documentation or data files to
+a user-specified location, at their discretion. If you put related data files
+in a single directory, you can use ``resource_filename()`` with the directory
+name to get a filesystem directory that then can be copied with the ``shutil``
+module. (Even if your package is installed as a zipfile, calling
+``resource_filename()`` on a directory will return an actual filesystem
+directory, whose contents will be that entire subtree of your distribution.)
+
+(Of course, if you're writing a new package, you can just as easily place your
+data files or directories inside one of your packages, rather than using the
+distutils' approach. However, if you're updating an existing application, it
+may be simpler not to change the way it currently specifies these data files.)
+
+
+Automatic Resource Extraction
+-----------------------------
+
+If you are using tools that expect your resources to be "real" files, or your
+project includes non-extension native libraries or other files that your C
+extensions expect to be able to access, you may need to list those files in
+the ``eager_resources`` argument to ``setup()``, so that the files will be
+extracted together, whenever a C extension in the project is imported.
+
+This is especially important if your project includes shared libraries *other*
+than distutils-built C extensions, and those shared libraries use file
+extensions other than ``.dll``, ``.so``, or ``.dylib``, which are the
+extensions that setuptools 0.6a8 and higher automatically detects as shared
+libraries and adds to the ``native_libs.txt`` file for you. Any shared
+libraries whose names do not end with one of those extensions should be listed
+as ``eager_resources``, because they need to be present in the filesystem when
+he C extensions that link to them are used.
+
+The ``pkg_resources`` runtime for compressed packages will automatically
+extract *all* C extensions and ``eager_resources`` at the same time, whenever
+*any* C extension or eager resource is requested via the ``resource_filename()``
+API. (C extensions are imported using ``resource_filename()`` internally.)
+This ensures that C extensions will see all of the "real" files that they
+expect to see.
+
+Note also that you can list directory resource names in ``eager_resources`` as
+well, in which case the directory's contents (including subdirectories) will be
+extracted whenever any C extension or eager resource is requested.
+
+Please note that if you're not sure whether you need to use this argument, you
+don't! It's really intended to support projects with lots of non-Python
+dependencies and as a last resort for crufty projects that can't otherwise
+handle being compressed. If your package is pure Python, Python plus data
+files, or Python plus C, you really don't need this. You've got to be using
+either C or an external program that needs "real" files in your project before
+there's any possibility of ``eager_resources`` being relevant to your project.
+
+
+Extensible Applications and Frameworks
+======================================
+
+
+.. _Entry Points:
+
+Dynamic Discovery of Services and Plugins
+-----------------------------------------
+
+``setuptools`` supports creating libraries that "plug in" to extensible
+applications and frameworks, by letting you register "entry points" in your
+project that can be imported by the application or framework.
+
+For example, suppose that a blogging tool wants to support plugins
+that provide translation for various file types to the blog's output format.
+The framework might define an "entry point group" called ``blogtool.parsers``,
+and then allow plugins to register entry points for the file extensions they
+support.
+
+This would allow people to create distributions that contain one or more
+parsers for different file types, and then the blogging tool would be able to
+find the parsers at runtime by looking up an entry point for the file
+extension (or mime type, or however it wants to).
+
+Note that if the blogging tool includes parsers for certain file formats, it
+can register these as entry points in its own setup script, which means it
+doesn't have to special-case its built-in formats. They can just be treated
+the same as any other plugin's entry points would be.
+
+If you're creating a project that plugs in to an existing application or
+framework, you'll need to know what entry points or entry point groups are
+defined by that application or framework. Then, you can register entry points
+in your setup script. Here are a few examples of ways you might register an
+``.rst`` file parser entry point in the ``blogtool.parsers`` entry point group,
+for our hypothetical blogging tool::
+
+ setup(
+ # ...
+ entry_points = {'blogtool.parsers': '.rst = some_module:SomeClass'}
+ )
+
+ setup(
+ # ...
+ entry_points = {'blogtool.parsers': ['.rst = some_module:a_func']}
+ )
+
+ setup(
+ # ...
+ entry_points = """
+ [blogtool.parsers]
+ .rst = some.nested.module:SomeClass.some_classmethod [reST]
+ """,
+ extras_require = dict(reST = "Docutils>=0.3.5")
+ )
+
+The ``entry_points`` argument to ``setup()`` accepts either a string with
+``.ini``-style sections, or a dictionary mapping entry point group names to
+either strings or lists of strings containing entry point specifiers. An
+entry point specifier consists of a name and value, separated by an ``=``
+sign. The value consists of a dotted module name, optionally followed by a
+``:`` and a dotted identifier naming an object within the module. It can
+also include a bracketed list of "extras" that are required for the entry
+point to be used. When the invoking application or framework requests loading
+of an entry point, any requirements implied by the associated extras will be
+passed to ``pkg_resources.require()``, so that an appropriate error message
+can be displayed if the needed package(s) are missing. (Of course, the
+invoking app or framework can ignore such errors if it wants to make an entry
+point optional if a requirement isn't installed.)
+
+
+Defining Additional Metadata
+----------------------------
+
+Some extensible applications and frameworks may need to define their own kinds
+of metadata to include in eggs, which they can then access using the
+``pkg_resources`` metadata APIs. Ordinarily, this is done by having plugin
+developers include additional files in their ``ProjectName.egg-info``
+directory. However, since it can be tedious to create such files by hand, you
+may want to create a distutils extension that will create the necessary files
+from arguments to ``setup()``, in much the same way that ``setuptools`` does
+for many of the ``setup()`` arguments it adds. See the section below on
+`Creating distutils Extensions`_ for more details, especially the subsection on
+`Adding new EGG-INFO Files`_.
+
+
+"Development Mode"
+==================
+
+Under normal circumstances, the ``distutils`` assume that you are going to
+build a distribution of your project, not use it in its "raw" or "unbuilt"
+form. If you were to use the ``distutils`` that way, you would have to rebuild
+and reinstall your project every time you made a change to it during
+development.
+
+Another problem that sometimes comes up with the ``distutils`` is that you may
+need to do development on two related projects at the same time. You may need
+to put both projects' packages in the same directory to run them, but need to
+keep them separate for revision control purposes. How can you do this?
+
+Setuptools allows you to deploy your projects for use in a common directory or
+staging area, but without copying any files. Thus, you can edit each project's
+code in its checkout directory, and only need to run build commands when you
+change a project's C extensions or similarly compiled files. You can even
+deploy a project into another project's checkout directory, if that's your
+preferred way of working (as opposed to using a common independent staging area
+or the site-packages directory).
+
+To do this, use the ``setup.py develop`` command. It works very similarly to
+``setup.py install`` or the EasyInstall tool, except that it doesn't actually
+install anything. Instead, it creates a special ``.egg-link`` file in the
+deployment directory, that links to your project's source code. And, if your
+deployment directory is Python's ``site-packages`` directory, it will also
+update the ``easy-install.pth`` file to include your project's source code,
+thereby making it available on ``sys.path`` for all programs using that Python
+installation.
+
+If you have enabled the ``use_2to3`` flag, then of course the ``.egg-link``
+will not link directly to your source code when run under Python 3, since
+that source code would be made for Python 2 and not work under Python 3.
+Instead the ``setup.py develop`` will build Python 3 code under the ``build``
+directory, and link there. This means that after doing code changes you will
+have to run ``setup.py build`` before these changes are picked up by your
+Python 3 installation.
+
+In addition, the ``develop`` command creates wrapper scripts in the target
+script directory that will run your in-development scripts after ensuring that
+all your ``install_requires`` packages are available on ``sys.path``.
+
+You can deploy the same project to multiple staging areas, e.g. if you have
+multiple projects on the same machine that are sharing the same project you're
+doing development work.
+
+When you're done with a given development task, you can remove the project
+source from a staging area using ``setup.py develop --uninstall``, specifying
+the desired staging area if it's not the default.
+
+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::
+
+ 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!
+---------------------------------------------
+
+Your users might not have ``setuptools`` installed on their machines, or even
+if they do, it might not be the right version. Fixing this is easy; just
+download `distribute_setup.py`_, and put it in the same directory as your ``setup.py``
+script. (Be sure to add it to your revision control system, too.) Then add
+these two lines to the very top of your setup script, before the script imports
+anything from setuptools:
+
+.. code-block:: python
+
+ import distribute_setup
+ distribute_setup.use_setuptools()
+
+That's it. The ``distribute_setup`` module will automatically download a matching
+version of ``setuptools`` from PyPI, if it isn't present on the target system.
+Whenever you install an updated version of setuptools, you should also update
+your projects' ``distribute_setup.py`` files, so that a matching version gets installed
+on the target machine(s).
+
+By the way, setuptools supports the new PyPI "upload" command, so you can use
+``setup.py sdist upload`` or ``setup.py bdist_egg upload`` to upload your
+source or egg distributions respectively. Your project's current version must
+be registered with PyPI first, of course; you can use ``setup.py register`` to
+do that. Or you can do it all in one step, e.g. ``setup.py register sdist
+bdist_egg upload`` will register the package, build source and egg
+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 ``distribute_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
+--------------------------
+
+If you're managing several projects that need to use ``distribute_setup``, and you
+are using Subversion as your revision control system, you can use the
+"svn:externals" property to share a single copy of ``distribute_setup`` between
+projects, so that it will always be up-to-date whenever you check out or update
+an individual project, without having to manually update each project to use
+a new version.
+
+However, because Subversion only supports using directories as externals, you
+have to turn ``distribute_setup.py`` into ``distribute_setup/__init__.py`` in order
+to do this, then create "externals" definitions that map the ``distribute_setup``
+directory into each project. Also, if any of your projects use
+``find_packages()`` on their setup directory, you will need to exclude the
+resulting ``distribute_setup`` package, to keep it from being included in your
+distributions, e.g.::
+
+ setup(
+ ...
+ packages = find_packages(exclude=['distribute_setup']),
+ )
+
+Of course, the ``distribute_setup`` package will still be included in your
+packages' source distributions, as it needs to be.
+
+For your convenience, you may use the following external definition, which will
+track the latest version of setuptools::
+
+ ez_setup svn://svn.eby-sarna.com/svnroot/ez_setup
+
+You can set this by executing this command in your project directory::
+
+ svn propedit svn:externals .
+
+And then adding the line shown above to the file that comes up for editing.
+
+
+Setting the ``zip_safe`` flag
+-----------------------------
+
+For maximum performance, Python packages are best installed as zip files.
+Not all packages, however, are capable of running in compressed form, because
+they may expect to be able to access either source code or data files as
+normal operating system files. So, ``setuptools`` can install your project
+as a zipfile or a directory, and its default choice is determined by the
+project's ``zip_safe`` flag.
+
+You can pass a True or False value for the ``zip_safe`` argument to the
+``setup()`` function, or you can omit it. If you omit it, the ``bdist_egg``
+command will analyze your project's contents to see if it can detect any
+conditions that would prevent it from working in a zipfile. It will output
+notices to the console about any such conditions that it finds.
+
+Currently, this analysis is extremely conservative: it will consider the
+project unsafe if it contains any C extensions or datafiles whatsoever. This
+does *not* mean that the project can't or won't work as a zipfile! It just
+means that the ``bdist_egg`` authors aren't yet comfortable asserting that
+the project *will* work. If the project contains no C or data files, and does
+no ``__file__`` or ``__path__`` introspection or source code manipulation, then
+there is an extremely solid chance the project will work when installed as a
+zipfile. (And if the project uses ``pkg_resources`` for all its data file
+access, then C extensions and other data files shouldn't be a problem at all.
+See the `Accessing Data Files at Runtime`_ section above for more information.)
+
+However, if ``bdist_egg`` can't be *sure* that your package will work, but
+you've checked over all the warnings it issued, and you are either satisfied it
+*will* work (or if you want to try it for yourself), then you should set
+``zip_safe`` to ``True`` in your ``setup()`` call. If it turns out that it
+doesn't work, you can always change it to ``False``, which will force
+``setuptools`` to install your project as a directory rather than as a zipfile.
+
+Of course, the end-user can still override either decision, if they are using
+EasyInstall to install your package. And, if you want to override for testing
+purposes, you can just run ``setup.py easy_install --zip-ok .`` or ``setup.py
+easy_install --always-unzip .`` in your project directory. to install the
+package as a zipfile or directory, respectively.
+
+In the future, as we gain more experience with different packages and become
+more satisfied with the robustness of the ``pkg_resources`` runtime, the
+"zip safety" analysis may become less conservative. However, we strongly
+recommend that you determine for yourself whether your project functions
+correctly when installed as a zipfile, correct any problems if you can, and
+then make an explicit declaration of ``True`` or ``False`` for the ``zip_safe``
+flag, so that it will not be necessary for ``bdist_egg`` or ``EasyInstall`` to
+try to guess whether your project can work as a zipfile.
+
+
+Namespace Packages
+------------------
+
+Sometimes, a large package is more useful if distributed as a collection of
+smaller eggs. However, Python does not normally allow the contents of a
+package to be retrieved from more than one location. "Namespace packages"
+are a solution for this problem. When you declare a package to be a namespace
+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 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. The argument should list the namespace packages that the egg
+participates in. For example, the ZopeInterface project might do this::
+
+ setup(
+ # ...
+ namespace_packages = ['zope']
+ )
+
+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. 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
+``peak.util`` package will be too.
+
+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
+*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
+------------------------------------------------
+
+When a set of related projects are under development, it may be important to
+track finer-grained version increments than you would normally use for e.g.
+"stable" releases. While stable releases might be measured in dotted numbers
+with alpha/beta/etc. status codes, development versions of a project often
+need to be tracked by revision or build number or even build date. This is
+especially true when projects in development need to refer to one another, and
+therefore may literally need an up-to-the-minute version of something!
+
+To support these scenarios, ``setuptools`` allows you to "tag" your source and
+egg distributions by adding one or more of the following to the project's
+"official" version identifier:
+
+* 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
+ 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``), 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, 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
+pattern. So, you can use a command line like::
+
+ setup.py egg_info -rbDEV bdist_egg rotate -m.egg -k3
+
+to build an egg whose version info includes 'DEV-rNNNN' (where NNNN is the
+most recent Subversion revision that affected the source tree), and then
+delete any egg files from the distribution directory except for the three
+that were built most recently.
+
+If you have to manage automated builds for multiple packages, each with
+different tagging and rotation policies, you may also want to check out the
+`alias`_ command, which would let each package define an alias like ``daily``
+that would perform the necessary tag, build, and rotate commands. Then, a
+simpler script or cron job could just run ``setup.py daily`` in each project
+directory. (And, you could also define sitewide or per-user default versions
+of the ``daily`` alias, so that projects that didn't define their own would
+use the appropriate defaults.)
+
+
+Generating Source Distributions
+-------------------------------
+
+``setuptools`` enhances the distutils' default algorithm for source file
+selection, so that all files managed by CVS or Subversion in your project tree
+are included in any source distribution you build. This is a big improvement
+over having to manually write a ``MANIFEST.in`` file and try to keep it in
+sync with your project. So, if you are using CVS or Subversion, and your
+source distributions only need to include files that you're tracking in
+revision control, don't create a a ``MANIFEST.in`` file for your project.
+(And, if you already have one, you might consider deleting it the next time
+you would otherwise have to change it.)
+
+(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
+---------------------------------------------
+
+If you use the ``register`` command (``setup.py register``) to register your
+package with PyPI, that's most of the battle right there. (See the
+`docs for the register command`_ for more details.)
+
+.. _docs for the register command: http://docs.python.org/dist/package-index.html
+
+If you also use the `upload`_ command to upload actual distributions of your
+package, that's even better, because EasyInstall will be able to find and
+download them directly from your project's PyPI page.
+
+However, there may be reasons why you don't want to upload distributions to
+PyPI, and just want your existing distributions (or perhaps a Subversion
+checkout) to be used instead.
+
+So here's what you need to do before running the ``register`` command. There
+are three ``setup()`` arguments that affect EasyInstall:
+
+``url`` and ``download_url``
+ These become links on your project's PyPI page. EasyInstall will examine
+ them to see if they link to a package ("primary links"), or whether they are
+ HTML pages. If they're HTML pages, EasyInstall scans all HREF's on the
+ page for primary links
+
+``long_description``
+ EasyInstall will check any URLs contained in this argument to see if they
+ are primary links.
+
+A URL is considered a "primary link" if it is a link to a .tar.gz, .tgz, .zip,
+.egg, .egg.zip, .tar.bz2, or .exe file, or if it has an ``#egg=project`` or
+``#egg=project-version`` fragment identifier attached to it. EasyInstall
+attempts to determine a project name and optional version number from the text
+of a primary link *without* downloading it. When it has found all the primary
+links, EasyInstall will select the best match based on requested version,
+platform compatibility, and other criteria.
+
+So, if your ``url`` or ``download_url`` point either directly to a downloadable
+source distribution, or to HTML page(s) that have direct links to such, then
+EasyInstall will be able to locate downloads automatically. If you want to
+make Subversion checkouts available, then you should create links with either
+``#egg=project`` or ``#egg=project-version`` added to the URL. You should
+replace ``project`` and ``version`` with the values they would have in an egg
+filename. (Be sure to actually generate an egg and then use the initial part
+of the filename, rather than trying to guess what the escaped form of the
+project name and version number will be.)
+
+Note that Subversion checkout links are of lower precedence than other kinds
+of distributions, so EasyInstall will not select a Subversion checkout for
+downloading unless it has a version included in the ``#egg=`` suffix, and
+it's a higher version than EasyInstall has seen in any other links for your
+project.
+
+As a result, it's a common practice to use mark checkout URLs with a version of
+"dev" (i.e., ``#egg=projectname-dev``), so that users can do something like
+this::
+
+ easy_install --editable projectname==dev
+
+in order to check out the in-development version of ``projectname``.
+
+
+Managing "Continuous Releases" Using Subversion
+-----------------------------------------------
+
+If you expect your users to track in-development versions of your project via
+Subversion, there are a few additional steps you should take to ensure that
+things work smoothly with EasyInstall. First, you should add the following
+to your project's ``setup.cfg`` file:
+
+.. code-block:: ini
+
+ [egg_info]
+ tag_build = .dev
+ tag_svn_revision = 1
+
+This will tell ``setuptools`` to generate package version numbers like
+``1.0a1.dev-r1263``, which will be considered to be an *older* release than
+``1.0a1``. Thus, when you actually release ``1.0a1``, the entire egg
+infrastructure (including ``setuptools``, ``pkg_resources`` and EasyInstall)
+will know that ``1.0a1`` supersedes any interim snapshots from Subversion, and
+handle upgrades accordingly.
+
+(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
+still under development, rather than a past version being patched. It is of
+course possible for a single project to have both situations, using
+post-release numbering on release branches, and pre-release numbering on the
+trunk. But you don't have to make things this complex if you don't want to.)
+
+Commonly, projects releasing code from Subversion will include a PyPI link to
+their checkout URL (as described in the previous section) with an
+``#egg=projectname-dev`` suffix. This allows users to request EasyInstall
+to download ``projectname==dev`` in order to get the latest in-development
+code. Note that if your project depends on such in-progress code, you may wish
+to specify your ``install_requires`` (or other requirements) to include
+``==dev``, e.g.:
+
+.. code-block:: python
+
+ install_requires = ["OtherProject>=0.2a1.dev-r143,==dev"]
+
+The above example says, "I really want at least this particular development
+revision number, but feel free to follow and use an ``#egg=OtherProject-dev``
+link if you find one". This avoids the need to have actual source or binary
+distribution snapshots of in-development code available, just to be able to
+depend on the latest and greatest a project has to offer.
+
+A final note for Subversion development: if you are using SVN revision tags
+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. 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
+-------------------------------------------
+
+``setuptools`` includes transparent support for building Pyrex extensions, as
+long as you define your extensions using ``setuptools.Extension``, *not*
+``distutils.Extension``. You must also not import anything from Pyrex in
+your setup script.
+
+If you follow these rules, you can safely list ``.pyx`` files as the source
+of your ``Extension`` objects in the setup script. ``setuptools`` will detect
+at build time whether Pyrex is installed or not. If it is, then ``setuptools``
+will use it. If not, then ``setuptools`` will silently change the
+``Extension`` objects to refer to the ``.c`` counterparts of the ``.pyx``
+files, so that the normal distutils C compilation process will occur.
+
+Of course, for this to work, your source distributions must include the C
+code generated by Pyrex, as well as your original ``.pyx`` files. This means
+that you will probably want to include current ``.c`` files in your revision
+control system, rebuilding them whenever you check changes in for the ``.pyx``
+source files. This will ensure that people tracking your project in CVS or
+Subversion will be able to build it even if they don't have Pyrex installed,
+and that your source releases will be similarly usable with or without Pyrex.
+
+
+-----------------
+Command Reference
+-----------------
+
+.. _alias:
+
+``alias`` - Define shortcuts for commonly used commands
+=======================================================
+
+Sometimes, you need to use the same commands over and over, but you can't
+necessarily set them as defaults. For example, if you produce both development
+snapshot releases and "stable" releases of a project, you may want to put
+the distributions in different places, or use different ``egg_info`` tagging
+options, etc. In these cases, it doesn't make sense to set the options in
+a distutils configuration file, because the values of the options changed based
+on what you're trying to do.
+
+Setuptools therefore allows you to define "aliases" - shortcut names for
+an arbitrary string of commands and options, using ``setup.py alias aliasname
+expansion``, where aliasname is the name of the new alias, and the remainder of
+the command line supplies its expansion. For example, this command defines
+a sitewide alias called "daily", that sets various ``egg_info`` tagging
+options::
+
+ setup.py alias --global-config daily egg_info --tag-svn-revision \
+ --tag-build=development
+
+Once the alias is defined, it can then be used with other setup commands,
+e.g.::
+
+ setup.py daily bdist_egg # generate a daily-build .egg file
+ setup.py daily sdist # generate a daily-build source distro
+ setup.py daily sdist bdist_egg # generate both
+
+The above commands are interpreted as if the word ``daily`` were replaced with
+``egg_info --tag-svn-revision --tag-build=development``.
+
+Note that setuptools will expand each alias *at most once* in a given command
+line. This serves two purposes. First, if you accidentally create an alias
+loop, it will have no effect; you'll instead get an error message about an
+unknown command. Second, it allows you to define an alias for a command, that
+uses that command. For example, this (project-local) alias::
+
+ setup.py alias bdist_egg bdist_egg rotate -k1 -m.egg
+
+redefines the ``bdist_egg`` command so that it always runs the ``rotate``
+command afterwards to delete all but the newest egg file. It doesn't loop
+indefinitely on ``bdist_egg`` because the alias is only expanded once when
+used.
+
+You can remove a defined alias with the ``--remove`` (or ``-r``) option, e.g.::
+
+ setup.py alias --global-config --remove daily
+
+would delete the "daily" alias we defined above.
+
+Aliases can be defined on a project-specific, per-user, or sitewide basis. The
+default is to define or remove a project-specific alias, but you can use any of
+the `configuration file options`_ (listed under the `saveopts`_ command, below)
+to determine which distutils configuration file an aliases will be added to
+(or removed from).
+
+Note that if you omit the "expansion" argument to the ``alias`` command,
+you'll get output showing that alias' current definition (and what
+configuration file it's defined in). If you omit the alias name as well,
+you'll get a listing of all current aliases along with their configuration
+file locations.
+
+
+``bdist_egg`` - Create a Python Egg for the project
+===================================================
+
+This command generates a Python Egg (``.egg`` file) for the project. Python
+Eggs are the preferred binary distribution format for EasyInstall, because they
+are cross-platform (for "pure" packages), directly importable, and contain
+project metadata including scripts and information about the project's
+dependencies. They can be simply downloaded and added to ``sys.path``
+directly, or they can be placed in a directory on ``sys.path`` and then
+automatically discovered by the egg runtime system.
+
+This command runs the `egg_info`_ command (if it hasn't already run) to update
+the project's metadata (``.egg-info``) directory. If you have added any extra
+metadata files to the ``.egg-info`` directory, those files will be included in
+the new egg file's metadata directory, for use by the egg runtime system or by
+any applications or frameworks that use that metadata.
+
+You won't usually need to specify any special options for this command; just
+use ``bdist_egg`` and you're done. But there are a few options that may
+be occasionally useful:
+
+``--dist-dir=DIR, -d DIR``
+ Set the directory where the ``.egg`` file will be placed. If you don't
+ supply this, then the ``--dist-dir`` setting of the ``bdist`` command
+ will be used, which is usually a directory named ``dist`` in the project
+ directory.
+
+``--plat-name=PLATFORM, -p PLATFORM``
+ Set the platform name string that will be embedded in the egg's filename
+ (assuming the egg contains C extensions). This can be used to override
+ the distutils default platform name with something more meaningful. Keep
+ in mind, however, that the egg runtime system expects to see eggs with
+ distutils platform names, so it may ignore or reject eggs with non-standard
+ platform names. Similarly, the EasyInstall program may ignore them when
+ searching web pages for download links. However, if you are
+ cross-compiling or doing some other unusual things, you might find a use
+ for this option.
+
+``--exclude-source-files``
+ Don't include any modules' ``.py`` files in the egg, just compiled Python,
+ C, and data files. (Note that this doesn't affect any ``.py`` files in the
+ EGG-INFO directory or its subdirectories, since for example there may be
+ scripts with a ``.py`` extension which must still be retained.) We don't
+ recommend that you use this option except for packages that are being
+ bundled for proprietary end-user applications, or for "embedded" scenarios
+ where space is at an absolute premium. On the other hand, if your package
+ is going to be installed and used in compressed form, you might as well
+ exclude the source because Python's ``traceback`` module doesn't currently
+ understand how to display zipped source code anyway, or how to deal with
+ files that are in a different place from where their code was compiled.
+
+There are also some options you will probably never need, but which are there
+because they were copied from similar ``bdist`` commands used as an example for
+creating this one. They may be useful for testing and debugging, however,
+which is why we kept them:
+
+``--keep-temp, -k``
+ Keep the contents of the ``--bdist-dir`` tree around after creating the
+ ``.egg`` file.
+
+``--bdist-dir=DIR, -b DIR``
+ Set the temporary directory for creating the distribution. The entire
+ contents of this directory are zipped to create the ``.egg`` file, after
+ running various installation commands to copy the package's modules, data,
+ and extensions here.
+
+``--skip-build``
+ Skip doing any "build" commands; just go straight to the
+ install-and-compress phases.
+
+
+.. _develop:
+
+``develop`` - Deploy the project source in "Development Mode"
+=============================================================
+
+This command allows you to deploy your project's source for use in one or more
+"staging areas" where it will be available for importing. This deployment is
+done in such a way that changes to the project source are immediately available
+in the staging area(s), without needing to run a build or install step after
+each change.
+
+The ``develop`` command works by creating an ``.egg-link`` file (named for the
+project) in the given staging area. If the staging area is Python's
+``site-packages`` directory, it also updates an ``easy-install.pth`` file so
+that the project is on ``sys.path`` by default for all programs run using that
+Python installation.
+
+The ``develop`` command also installs wrapper scripts in the staging area (or
+a separate directory, as specified) that will ensure the project's dependencies
+are available on ``sys.path`` before running the project's source scripts.
+And, it ensures that any missing project dependencies are available in the
+staging area, by downloading and installing them if necessary.
+
+Last, but not least, the ``develop`` command invokes the ``build_ext -i``
+command to ensure any C extensions in the project have been built and are
+up-to-date, and the ``egg_info`` command to ensure the project's metadata is
+updated (so that the runtime and wrappers know what the project's dependencies
+are). If you make any changes to the project's setup script or C extensions,
+you should rerun the ``develop`` command against all relevant staging areas to
+keep the project's scripts, metadata and extensions up-to-date. Most other
+kinds of changes to your project should not require any build operations or
+rerunning ``develop``, but keep in mind that even minor changes to the setup
+script (e.g. changing an entry point definition) require you to re-run the
+``develop`` or ``test`` commands to keep the distribution updated.
+
+Here are some of the options that the ``develop`` command accepts. Note that
+they affect the project's dependencies as well as the project itself, so if you
+have dependencies that need to be installed and you use ``--exclude-scripts``
+(for example), the dependencies' scripts will not be installed either! For
+this reason, you may want to use EasyInstall to install the project's
+dependencies before using the ``develop`` command, if you need finer control
+over the installation options for dependencies.
+
+``--uninstall, -u``
+ Un-deploy the current project. You may use the ``--install-dir`` or ``-d``
+ option to designate the staging area. The created ``.egg-link`` file will
+ be removed, if present and it is still pointing to the project directory.
+ The project directory will be removed from ``easy-install.pth`` if the
+ staging area is Python's ``site-packages`` directory.
+
+ Note that this option currently does *not* uninstall script wrappers! You
+ must uninstall them yourself, or overwrite them by using EasyInstall to
+ activate a different version of the package. You can also avoid installing
+ script wrappers in the first place, if you use the ``--exclude-scripts``
+ (aka ``-x``) option when you run ``develop`` to deploy the project.
+
+``--multi-version, -m``
+ "Multi-version" mode. Specifying this option prevents ``develop`` from
+ adding an ``easy-install.pth`` entry for the project(s) being deployed, and
+ if an entry for any version of a project already exists, the entry will be
+ removed upon successful deployment. In multi-version mode, no specific
+ version of the package is available for importing, unless you use
+ ``pkg_resources.require()`` to put it on ``sys.path``, or you are running
+ a wrapper script generated by ``setuptools`` or EasyInstall. (In which
+ case the wrapper script calls ``require()`` for you.)
+
+ Note that if you install to a directory other than ``site-packages``,
+ this option is automatically in effect, because ``.pth`` files can only be
+ used in ``site-packages`` (at least in Python 2.3 and 2.4). So, if you use
+ the ``--install-dir`` or ``-d`` option (or they are set via configuration
+ file(s)) your project and its dependencies will be deployed in multi-
+ version mode.
+
+``--install-dir=DIR, -d DIR``
+ Set the installation directory (staging area). If this option is not
+ directly specified on the command line or in a distutils configuration
+ file, the distutils default installation location is used. Normally, this
+ will be the ``site-packages`` directory, but if you are using distutils
+ configuration files, setting things like ``prefix`` or ``install_lib``,
+ then those settings are taken into account when computing the default
+ staging area.
+
+``--script-dir=DIR, -s DIR``
+ Set the script installation directory. If you don't supply this option
+ (via the command line or a configuration file), but you *have* supplied
+ an ``--install-dir`` (via command line or config file), then this option
+ defaults to the same directory, so that the scripts will be able to find
+ their associated package installation. Otherwise, this setting defaults
+ to the location where the distutils would normally install scripts, taking
+ any distutils configuration file settings into account.
+
+``--exclude-scripts, -x``
+ Don't deploy script wrappers. This is useful if you don't want to disturb
+ existing versions of the scripts in the staging area.
+
+``--always-copy, -a``
+ Copy all needed distributions to the staging area, even if they
+ are already present in another directory on ``sys.path``. By default, if
+ 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
+files), the ``develop`` command will use them as defaults, unless you override
+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
+=====================================================
+
+This command performs two operations: it updates a project's ``.egg-info``
+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``, ``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
+in the order shown, so if you use more than one, the requested tags will be
+added in the following order:
+
+``--tag-build=NAME, -b NAME``
+ Append NAME to the project's version string. Due to the way setuptools
+ processes "pre-release" version suffixes beginning with the letters "a"
+ through "e" (like "alpha", "beta", and "candidate"), you will usually want
+ to use a tag like ".build" or ".dev", as this will cause the version number
+ to be considered *lower* than the project's default version. (If you
+ want to make the version number *higher* than the default version, you can
+ 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
+ version string, where NNNN is the revision number of the most recent
+ modification to the current directory, as obtained from the ``svn info``
+ command.
+
+ If the current directory is not a Subversion checkout, the command will
+ look for a ``PKG-INFO`` file instead, and try to find the revision number
+ from that, by looking for a "-rNNNN" string at the end of the version
+ number. (This is so that building a package from a source distribution of
+ a Subversion snapshot will produce a binary with the correct version
+ number.)
+
+ 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
+ necessarily the same as your project directory; some projects use a ``src``
+ or ``lib`` subdirectory as the source root). You should not normally need
+ to specify this directory, as it is normally determined from the
+ ``package_dir`` argument to the ``setup()`` function, if any. If there is
+ no ``package_dir`` set, this option defaults to the current directory.
+
+
+``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:
+
+``rotate`` - Delete outdated distribution files
+===============================================
+
+As you develop new versions of your project, your distribution (``dist``)
+directory will gradually fill up with older source and/or binary distribution
+files. The ``rotate`` command lets you automatically clean these up, keeping
+only the N most-recently modified files matching a given pattern.
+
+``--match=PATTERNLIST, -m PATTERNLIST``
+ Comma-separated list of glob patterns to match. This option is *required*.
+ The project name and ``-*`` is prepended to the supplied patterns, in order
+ to match only distributions belonging to the current project (in case you
+ have a shared distribution directory for multiple projects). Typically,
+ 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
+ but the COUNT most-recently-modified files in that group. This option is
+ *required*.
+
+``--dist-dir=DIR, -d DIR``
+ Directory where the distributions are. This defaults to the value of the
+ ``bdist`` command's ``--dist-dir`` option, which will usually be the
+ project's ``dist`` subdirectory.
+
+**Example 1**: Delete all .tar.gz files from the distribution directory, except
+for the 3 most recently modified ones::
+
+ setup.py rotate --match=.tar.gz --keep=3
+
+**Example 2**: Delete all Python 2.3 or Python 2.4 eggs from the distribution
+directory, except the most recently modified one for each Python version::
+
+ setup.py rotate --match=-py2.3*.egg,-py2.4*.egg --keep=1
+
+
+.. _saveopts:
+
+``saveopts`` - Save used options to a configuration file
+========================================================
+
+Finding and editing ``distutils`` configuration files can be a pain, especially
+since you also have to translate the configuration options from command-line
+form to the proper configuration file format. You can avoid these hassles by
+using the ``saveopts`` command. Just add it to the command line to save the
+options you used. For example, this command builds the project using
+the ``mingw32`` C compiler, then saves the --compiler setting as the default
+for future builds (even those run implicitly by the ``install`` command)::
+
+ setup.py build --compiler=mingw32 saveopts
+
+The ``saveopts`` command saves all options for every commmand specified on the
+command line to the project's local ``setup.cfg`` file, unless you use one of
+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
+
+Note, however, that all of the commands specified are always run, regardless of
+where ``saveopts`` is placed on the command line.
+
+
+Configuration File Options
+--------------------------
+
+Normally, settings such as options and aliases are saved to the project's
+local ``setup.cfg`` file. But you can override this and save them to the
+global or per-user configuration files, or to a manually-specified filename.
+
+``--global-config, -g``
+ 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
+ with ``-g`` or ``-f``.
+
+``--filename=FILENAME, -f FILENAME``
+ Save settings to the specified configuration file to use. You can't
+ combine this option with ``-g`` or ``-u``. Note that if you specify a
+ non-standard filename, the ``distutils`` and ``setuptools`` will not
+ use the file's contents. This option is mainly included for use in
+ testing.
+
+These options are used by other ``setuptools`` commands that modify
+configuration files, such as the `alias`_ and `setopt`_ commands.
+
+
+.. _setopt:
+
+``setopt`` - Set a distutils or setuptools option in a config file
+==================================================================
+
+This command is mainly for use by scripts, but it can also be used as a quick
+and dirty way to change a distutils configuration option without having to
+remember what file the options are in and then open an editor.
+
+**Example 1**. Set the default C compiler to ``mingw32`` (using long option
+names)::
+
+ setup.py setopt --command=build --option=compiler --set-value=mingw32
+
+**Example 2**. Remove any setting for the distutils default package
+installation directory (short option names)::
+
+ setup.py setopt -c install -o install_lib -r
+
+
+Options for the ``setopt`` command:
+
+``--command=COMMAND, -c COMMAND``
+ Command to set the option for. This option is required.
+
+``--option=OPTION, -o OPTION``
+ The name of the option to set. This option is required.
+
+``--set-value=VALUE, -s VALUE``
+ The value to set the option to. Not needed if ``-r`` or ``--remove`` is
+ set.
+
+``--remove, -r``
+ Remove (unset) the option, instead of setting it.
+
+In addition to the above options, you may use any of the `configuration file
+options`_ (listed under the `saveopts`_ command, above) to determine which
+distutils configuration file the option will be added to (or removed from).
+
+
+.. _test:
+
+``test`` - Build package and run a unittest suite
+=================================================
+
+When doing test-driven development, or running automated builds that need
+testing before they are deployed for downloading or use, it's often useful
+to be able to run a project's unit tests without actually deploying the project
+anywhere, even using the ``develop`` command. The ``test`` command runs a
+project's unit tests without actually deploying it, by temporarily putting the
+project's source on ``sys.path``, after first running ``build_ext -i`` and
+``egg_info`` to ensure that any C extensions and project metadata are
+up-to-date.
+
+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
+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
+you supply the ``-q`` or ``--quiet`` option, either as a global option to
+the setup script (e.g. ``setup.py -q test``) or as an option for the ``test``
+command itself (e.g. ``setup.py test -q``). There is one other option
+available:
+
+``--test-suite=NAME, -s NAME``
+ Specify the test suite (or module, class, or method) to be run
+ (e.g. ``some_module.test_suite``). The default for this option can be
+ set by giving a ``test_suite`` argument to the ``setup()`` function, e.g.::
+
+ setup(
+ # ...
+ test_suite = "my_package.tests.test_all"
+ )
+
+ If you did not set a ``test_suite`` in your ``setup()`` call, and do not
+ provide a ``--test-suite`` option, an error will occur.
+
+
+.. _upload:
+
+``upload`` - Upload source and/or egg distributions to PyPI
+===========================================================
+
+PyPI now supports uploading project files for redistribution; uploaded files
+are easily found by EasyInstall, even if you don't have download links on your
+project's home page.
+
+Although Python 2.5 will support uploading all types of distributions to PyPI,
+setuptools only supports source distributions and eggs. (This is partly
+because PyPI's upload support is currently broken for various other file
+types.) To upload files, you must include the ``upload`` command *after* the
+``sdist`` or ``bdist_egg`` commands on the setup command line. For example::
+
+ 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
+command line, so that any registration problems can be found and fixed before
+building and uploading the distributions, e.g.::
+
+ setup.py register sdist bdist_egg upload
+
+This will update PyPI's listing for your project's current version.
+
+Note, by the way, that the metadata in your ``setup()`` call determines what
+will be listed in PyPI for your package. Try to fill out as much of it as
+possible, as it will save you a lot of trouble manually adding and updating
+your PyPI listings. Just put it in ``setup.py`` and use the ``register``
+comamnd to keep PyPI up to date.
+
+The ``upload`` command has a few options worth noting:
+
+``--sign, -s``
+ 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://pypi.python.org/pypi (i.e., the main PyPI installation).
+
+.. _upload_docs:
+
+``upload_docs`` - Upload package documentation to PyPI
+======================================================
+
+PyPI now supports uploading project documentation to the dedicated URL
+http://packages.python.org/<project>/.
+
+The ``upload_docs`` command will create the necessary zip file out of a
+documentation directory and will post to the repository.
+
+Note that to upload the documentation of a project, the corresponding version
+must already be registered with PyPI, using the distutils ``register``
+command -- just like the ``upload`` command.
+
+Assuming there is an ``Example`` project with documentation in the
+subdirectory ``docs``, e.g.::
+
+ Example/
+ |-- example.py
+ |-- setup.cfg
+ |-- setup.py
+ |-- docs
+ | |-- build
+ | | `-- html
+ | | | |-- index.html
+ | | | `-- tips_tricks.html
+ | |-- conf.py
+ | |-- index.txt
+ | `-- tips_tricks.txt
+
+You can simply pass the documentation directory path to the ``upload_docs``
+command::
+
+ python setup.py upload_docs --upload-dir=docs/build/html
+
+If no ``--upload-dir`` is given, ``upload_docs`` will attempt to run the
+``build_sphinx`` command to generate uploadable documentation.
+For the command to become available, `Sphinx <http://sphinx.pocoo.org/>`_
+must be installed in the same environment as distribute.
+
+As with other ``setuptools``-based commands, you can define useful
+defaults in the ``setup.cfg`` of your Python project, e.g.:
+
+.. code-block:: ini
+
+ [upload_docs]
+ upload-dir = docs/build/html
+
+The ``upload_docs`` command has the following options:
+
+``--upload-dir``
+ The directory to be uploaded to the repository.
+
+``--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://pypi.python.org/pypi (i.e., the main PyPI installation).
+
+
+--------------------------------
+Extending and Reusing Distribute
+--------------------------------
+
+Creating ``distutils`` Extensions
+=================================
+
+It can be hard to add new commands or setup arguments to the distutils. But
+the ``setuptools`` package makes it a bit easier, by allowing you to distribute
+a distutils extension as a separate project, and then have projects that need
+the extension just refer to it in their ``setup_requires`` argument.
+
+With ``setuptools``, your distutils extension projects can hook in new
+commands and ``setup()`` arguments just by defining "entry points". These
+are mappings from command or argument names to a specification of where to
+import a handler from. (See the section on `Dynamic Discovery of Services and
+Plugins`_ above for some more background on entry points.)
+
+
+Adding Commands
+---------------
+
+You can add new ``setup`` commands by defining entry points in the
+``distutils.commands`` group. For example, if you wanted to add a ``foo``
+command, you might add something like this to your distutils extension
+project's setup script::
+
+ setup(
+ # ...
+ entry_points = {
+ "distutils.commands": [
+ "foo = mypackage.some_module:foo",
+ ],
+ },
+ )
+
+(Assuming, of course, that the ``foo`` class in ``mypackage.some_module`` is
+a ``setuptools.Command`` subclass.)
+
+Once a project containing such entry points has been activated on ``sys.path``,
+(e.g. by running "install" or "develop" with a site-packages installation
+directory) the command(s) will be available to any ``setuptools``-based setup
+scripts. It is not necessary to use the ``--command-packages`` option or
+to monkeypatch the ``distutils.command`` package to install your commands;
+``setuptools`` automatically adds a wrapper to the distutils to search for
+entry points in the active distributions on ``sys.path``. In fact, this is
+how setuptools' own commands are installed: the setuptools project's setup
+script defines entry points for them!
+
+
+Adding ``setup()`` Arguments
+----------------------------
+
+Sometimes, your commands may need additional arguments to the ``setup()``
+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::
+
+ setup(
+ # ...
+ entry_points = {
+ "distutils.commands": [
+ "foo = mypackage.some_module:foo",
+ ],
+ "distutils.setup_keywords": [
+ "bar_baz = mypackage.some_module:validate_bar_baz",
+ ],
+ },
+ )
+
+The idea here is that the entry point defines a function that will be called
+to validate the ``setup()`` argument, if it's supplied. The ``Distribution``
+object will have the initial value of the attribute set to ``None``, and the
+validation function will only be called if the ``setup()`` call sets it to
+a non-None value. Here's an example validation function::
+
+ def assert_bool(dist, attr, value):
+ """Verify that value is True, False, 0, or 1"""
+ if bool(value) != value:
+ raise DistutilsSetupError(
+ "%r must be a boolean value (got %r)" % (attr,value)
+ )
+
+Your function should accept three arguments: the ``Distribution`` object,
+the attribute name, and the attribute value. It should raise a
+``DistutilsSetupError`` (from the ``distutils.errors`` module) if the argument
+is invalid. Remember, your function will only be called with non-None values,
+and the default value of arguments defined this way is always None. So, your
+commands should always be prepared for the possibility that the attribute will
+be ``None`` when they access it later.
+
+If more than one active distribution defines an entry point for the same
+``setup()`` argument, *all* of them will be called. This allows multiple
+distutils extensions to define a common argument, as long as they agree on
+what values of that argument are valid.
+
+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 any setup
+script using your extension lists your project in its ``setup_requires``
+argument.
+
+
+Adding new EGG-INFO Files
+-------------------------
+
+Some extensible applications or frameworks may want to allow third parties to
+develop plugins with application or framework-specific metadata included in
+the plugins' EGG-INFO directory, for easy access via the ``pkg_resources``
+metadata API. The easiest way to allow this is to create a distutils extension
+to be used from the plugin projects' setup scripts (via ``setup_requires``)
+that defines a new setup keyword, and then uses that data to write an EGG-INFO
+file when the ``egg_info`` command is run.
+
+The ``egg_info`` command looks for extension points in an ``egg_info.writers``
+group, and calls them to write the files. Here's a simple example of a
+distutils extension defining a setup argument ``foo_bar``, which is a list of
+lines that will be written to ``foo_bar.txt`` in the EGG-INFO directory of any
+project that uses the argument::
+
+ setup(
+ # ...
+ entry_points = {
+ "distutils.setup_keywords": [
+ "foo_bar = setuptools.dist:assert_string_list",
+ ],
+ "egg_info.writers": [
+ "foo_bar.txt = setuptools.command.egg_info:write_arg",
+ ],
+ },
+ )
+
+This simple example makes use of two utility functions defined by setuptools
+for its own use: a routine to validate that a setup keyword is a sequence of
+strings, and another one that looks up a setup argument and writes it to
+a file. Here's what the writer utility looks like::
+
+ def write_arg(cmd, basename, filename):
+ argname = os.path.splitext(basename)[0]
+ value = getattr(cmd.distribution, argname, None)
+ if value is not None:
+ value = '\n'.join(value)+'\n'
+ cmd.write_or_delete_file(argname, filename, value)
+
+As you can see, ``egg_info.writers`` entry points must be a function taking
+three arguments: a ``egg_info`` command instance, the basename of the file to
+write (e.g. ``foo_bar.txt``), and the actual full filename that should be
+written to.
+
+In general, writer functions should honor the command object's ``dry_run``
+setting when writing files, and use the ``distutils.log`` object to do any
+console output. The easiest way to conform to this requirement is to use
+the ``cmd`` object's ``write_file()``, ``delete_file()``, and
+``write_or_delete_file()`` methods exclusively for your file operations. See
+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:
+
+.. code-block:: python
+
+ 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).
+
+
+Subclassing ``Command``
+-----------------------
+
+Sorry, this section isn't written yet, and neither is a lot of what's below
+this point, except for the change log. You might want to `subscribe to changes
+in this page <setuptools?action=subscribe>`_ to see when new documentation is
+added or updated.
+
+XXX
+
+
+Reusing ``setuptools`` Code
+===========================
+
+``distribute_setup``
+--------------------
+
+XXX
+
+
+``setuptools.archive_util``
+---------------------------
+
+XXX
+
+
+``setuptools.sandbox``
+----------------------
+
+XXX
+
+
+``setuptools.package_index``
+----------------------------
+
+XXX
+
+History
+=======
+
+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.
+
+ * Made ``develop`` command accept all the same options as ``easy_install``,
+ and use the ``easy_install`` command's configuration settings as defaults.
+
+ * Made ``egg_info --tag-svn-revision`` fall back to extracting the revision
+ number from ``PKG-INFO`` in case it is being run on a source distribution of
+ a snapshot taken from a Subversion-based project.
+
+ * Automatically detect ``.dll``, ``.so`` and ``.dylib`` files that are being
+ installed as data, adding them to ``native_libs.txt`` automatically.
+
+ * Fixed some problems with fresh checkouts of projects that don't include
+ ``.egg-info/PKG-INFO`` under revision control and put the project's source
+ code directly in the project directory. If such a package had any
+ requirements that get processed before the ``egg_info`` command can be run,
+ the setup scripts would fail with a "Missing 'Version:' header and/or
+ PKG-INFO file" error, because the egg runtime interpreted the unbuilt
+ metadata in a directory on ``sys.path`` (i.e. the current directory) as
+ being a corrupted egg. Setuptools now monkeypatches the distribution
+ metadata cache to pretend that the egg has valid version information, until
+ it has a chance to make it actually be so (via the ``egg_info`` command).
+
+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;
+ other platforms are treated the same as for ``console_scripts``.)
+
+0.6a2
+ * Added ``console_scripts`` entry point group to allow installing scripts
+ without the need to create separate script files. On Windows, console
+ scripts get an ``.exe`` wrapper so you can just type their name. On other
+ platforms, the scripts are written without a file extension.
+
+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
+ different Python version.
+
+ * The ``upload`` command no longer attaches an extra ``.zip`` when uploading
+ eggs, as PyPI now supports egg uploads without trickery.
+
+ * The ``ez_setup`` script/module now displays a warning before downloading
+ the setuptools egg, and attempts to check the downloaded egg against an
+ internal MD5 checksum table.
+
+ * Fixed the ``--tag-svn-revision`` option of ``egg_info`` not finding the
+ latest revision number; it was using the revision number of the directory
+ containing ``setup.py``, not the highest revision number in the project.
+
+ * Added ``eager_resources`` setup argument
+
+ * The ``sdist`` command now recognizes Subversion "deleted file" entries and
+ does not include them in source distributions.
+
+ * ``setuptools`` now embeds itself more thoroughly into the distutils, so that
+ other distutils extensions (e.g. py2exe, py2app) will subclass setuptools'
+ versions of things, rather than the native distutils ones.
+
+ * Added ``entry_points`` and ``setup_requires`` arguments to ``setup()``;
+ ``setup_requires`` allows you to automatically find and download packages
+ that are needed in order to *build* your project (as opposed to running it).
+
+ * ``setuptools`` now finds its commands, ``setup()`` argument validators, and
+ metadata writers using entry points, so that they can be extended by
+ third-party packages. See `Creating distutils Extensions`_ above for more
+ details.
+
+ * 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
+ handle ``-m`` on zipped modules.
+
+0.5a11
+ * Fix breakage of the "develop" command that was caused by the addition of
+ ``--always-unzip`` to the ``easy_install`` command.
+
+0.5a9
+ * Include ``svn:externals`` directories in source distributions as well as
+ normal subversion-controlled files and directories.
+
+ * Added ``exclude=patternlist`` option to ``setuptools.find_packages()``
+
+ * Changed --tag-svn-revision to include an "r" in front of the revision number
+ for better readability.
+
+ * Added ability to build eggs without including source files (except for any
+ scripts, of course), using the ``--exclude-source-files`` option to
+ ``bdist_egg``.
+
+ * ``setup.py install`` now automatically detects when an "unmanaged" package
+ or module is going to be on ``sys.path`` ahead of a package being installed,
+ thereby preventing the newer version from being imported. If this occurs,
+ a warning message is output to ``sys.stderr``, but installation proceeds
+ anyway. The warning message informs the user what files or directories
+ need deleting, and advises them they can also use EasyInstall (with the
+ ``--delete-conflicting`` option) to do it automatically.
+
+ * The ``egg_info`` command now adds a ``top_level.txt`` file to the metadata
+ directory that lists all top-level modules and packages in the distribution.
+ This is used by the ``easy_install`` command to find possibly-conflicting
+ "unmanaged" packages when installing the distribution.
+
+ * Added ``zip_safe`` and ``namespace_packages`` arguments to ``setup()``.
+ Added package analysis to determine zip-safety if the ``zip_safe`` flag
+ is not given, and advise the author regarding what code might need changing.
+
+ * Fixed the swapped ``-d`` and ``-b`` options of ``bdist_egg``.
+
+0.5a8
+ * The "egg_info" command now always sets the distribution metadata to "safe"
+ forms of the distribution name and version, so that distribution files will
+ be generated with parseable names (i.e., ones that don't include '-' in the
+ name or version). Also, this means that if you use the various ``--tag``
+ options of "egg_info", any distributions generated will use the tags in the
+ version, not just egg distributions.
+
+ * Added support for defining command aliases in distutils configuration files,
+ under the "[aliases]" section. To prevent recursion and to allow aliases to
+ call the command of the same name, a given alias can be expanded only once
+ per command-line invocation. You can define new aliases with the "alias"
+ command, either for the local, global, or per-user configuration.
+
+ * Added "rotate" command to delete old distribution files, given a set of
+ patterns to match and the number of files to keep. (Keeps the most
+ recently-modified distribution files matching each pattern.)
+
+ * Added "saveopts" command that saves all command-line options for the current
+ invocation to the local, global, or per-user configuration file. Useful for
+ setting defaults without having to hand-edit a configuration file.
+
+ * Added a "setopt" command that sets a single option in a specified distutils
+ configuration file.
+
+0.5a7
+ * Added "upload" support for egg and source distributions, including a bug
+ fix for "upload" and a temporary workaround for lack of .egg support in
+ PyPI.
+
+0.5a6
+ * Beefed up the "sdist" command so that if you don't have a MANIFEST.in, it
+ will include all files under revision control (CVS or Subversion) in the
+ current directory, and it will regenerate the list every time you create a
+ source distribution, not just when you tell it to. This should make the
+ default "do what you mean" more often than the distutils' default behavior
+ did, while still retaining the old behavior in the presence of MANIFEST.in.
+
+ * Fixed the "develop" command always updating .pth files, even if you
+ specified ``-n`` or ``--dry-run``.
+
+ * Slightly changed the format of the generated version when you use
+ ``--tag-build`` on the "egg_info" command, so that you can make tagged
+ revisions compare *lower* than the version specified in setup.py (e.g. by
+ using ``--tag-build=dev``).
+
+0.5a5
+ * Added ``develop`` command to ``setuptools``-based packages. This command
+ installs an ``.egg-link`` pointing to the package's source directory, and
+ script wrappers that ``execfile()`` the source versions of the package's
+ scripts. This lets you put your development checkout(s) on sys.path without
+ having to actually install them. (To uninstall the link, use
+ use ``setup.py develop --uninstall``.)
+
+ * Added ``egg_info`` command to ``setuptools``-based packages. This command
+ just creates or updates the "projectname.egg-info" directory, without
+ building an egg. (It's used by the ``bdist_egg``, ``test``, and ``develop``
+ commands.)
+
+ * Enhanced the ``test`` command so that it doesn't install the package, but
+ instead builds any C extensions in-place, updates the ``.egg-info``
+ metadata, adds the source directory to ``sys.path``, and runs the tests
+ directly on the source. This avoids an "unmanaged" installation of the
+ package to ``site-packages`` or elsewhere.
+
+ * Made ``easy_install`` a standard ``setuptools`` command, moving it from
+ the ``easy_install`` module to ``setuptools.command.easy_install``. Note
+ that if you were importing or extending it, you must now change your imports
+ accordingly. ``easy_install.py`` is still installed as a script, but not as
+ a module.
+
+0.5a4
+ * Setup scripts using setuptools can now list their dependencies directly in
+ the setup.py file, without having to manually create a ``depends.txt`` file.
+ The ``install_requires`` and ``extras_require`` arguments to ``setup()``
+ are used to create a dependencies file automatically. If you are manually
+ creating ``depends.txt`` right now, please switch to using these setup
+ arguments as soon as practical, because ``depends.txt`` support will be
+ removed in the 0.6 release cycle. For documentation on the new arguments,
+ see the ``setuptools.dist.Distribution`` class.
+
+ * Setup scripts using setuptools now always install using ``easy_install``
+ internally, for ease of uninstallation and upgrading.
+
+0.5a1
+ * Added support for "self-installation" bootstrapping. Packages can now
+ include ``ez_setup.py`` in their source distribution, and add the following
+ to their ``setup.py``, in order to automatically bootstrap installation of
+ setuptools as part of their setup process::
+
+ from ez_setup import use_setuptools
+ use_setuptools()
+
+ from setuptools import setup
+ # etc...
+
+0.4a2
+ * Added ``ez_setup.py`` installer/bootstrap script to make initial setuptools
+ installation easier, and to allow distributions using setuptools to avoid
+ having to include setuptools in their source distribution.
+
+ * All downloads are now managed by the ``PackageIndex`` class (which is now
+ subclassable and replaceable), so that embedders can more easily override
+ download logic, give download progress reports, etc. The class has also
+ been moved to the new ``setuptools.package_index`` module.
+
+ * The ``Installer`` class no longer handles downloading, manages a temporary
+ directory, or tracks the ``zip_ok`` option. Downloading is now handled
+ by ``PackageIndex``, and ``Installer`` has become an ``easy_install``
+ command class based on ``setuptools.Command``.
+
+ * There is a new ``setuptools.sandbox.run_setup()`` API to invoke a setup
+ script in a directory sandbox, and a new ``setuptools.archive_util`` module
+ with an ``unpack_archive()`` API. These were split out of EasyInstall to
+ allow reuse by other tools and applications.
+
+ * ``setuptools.Command`` now supports reinitializing commands using keyword
+ arguments to set/reset options. Also, ``Command`` subclasses can now set
+ their ``command_consumes_arguments`` attribute to ``True`` in order to
+ receive an ``args`` option containing the rest of the command line.
+
+0.3a2
+ * Added new options to ``bdist_egg`` to allow tagging the egg's version number
+ with a subversion revision number, the current date, or an explicit tag
+ value. Run ``setup.py bdist_egg --help`` to get more information.
+
+ * Misc. bug fixes
+
+0.3a1
+ * Initial release.
+
+Mailing List and Bug Tracker
+============================
+
+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/
+
diff --git a/vendor/distribute-0.6.36/docs/using.txt b/vendor/distribute-0.6.36/docs/using.txt
new file mode 100644
index 0000000000000000000000000000000000000000..192f1dc234a30dc1351c7f3cb7accd10e439ae72
--- /dev/null
+++ b/vendor/distribute-0.6.36/docs/using.txt
@@ -0,0 +1,21 @@
+================================
+Using Distribute in your project
+================================
+
+To use Distribute in your project, the recommended way is to ship
+`distribute_setup.py` alongside your `setup.py` script and call
+it at the very begining of `setup.py` like this::
+
+ from distribute_setup import use_setuptools
+ use_setuptools()
+
+Another way is to add ``Distribute`` in the ``install_requires`` option::
+
+ from setuptools import setup
+
+ setup(...
+ install_requires=['distribute']
+ )
+
+
+XXX to be finished
diff --git a/vendor/distribute-0.6.35/easy_install.py b/vendor/distribute-0.6.36/easy_install.py
similarity index 100%
rename from vendor/distribute-0.6.35/easy_install.py
rename to vendor/distribute-0.6.36/easy_install.py
diff --git a/vendor/distribute-0.6.35/launcher.c b/vendor/distribute-0.6.36/launcher.c
similarity index 100%
rename from vendor/distribute-0.6.35/launcher.c
rename to vendor/distribute-0.6.36/launcher.c
diff --git a/vendor/distribute-0.6.35/pkg_resources.py b/vendor/distribute-0.6.36/pkg_resources.py
similarity index 100%
rename from vendor/distribute-0.6.35/pkg_resources.py
rename to vendor/distribute-0.6.36/pkg_resources.py
diff --git a/vendor/distribute-0.6.35/release.py b/vendor/distribute-0.6.36/release.py
similarity index 98%
rename from vendor/distribute-0.6.35/release.py
rename to vendor/distribute-0.6.36/release.py
index 983703047fff06b6a41ed579125720709bb85f7c..199ad65a516d5a7f4044088edac77d22dd8c4d5f 100644
--- a/vendor/distribute-0.6.35/release.py
+++ b/vendor/distribute-0.6.36/release.py
@@ -20,7 +20,7 @@ try:
except Exception:
pass
-VERSION = '0.6.35'
+VERSION = '0.6.36'
def get_next_version():
digits = map(int, VERSION.split('.'))
@@ -50,7 +50,7 @@ def get_mercurial_creds(system='https://bitbucket.org', username=None):
# todo: consider getting this from .hgrc
username = username or getpass.getuser()
keyring_username = '@@'.join((username, system))
- system = '@'.join((keyring_username, 'Mercurial'))
+ system = 'Mercurial'
password = (
keyring.get_password(system, keyring_username)
if 'keyring' in globals()
diff --git a/vendor/distribute-0.6.35/setup.cfg b/vendor/distribute-0.6.36/setup.cfg
similarity index 100%
rename from vendor/distribute-0.6.35/setup.cfg
rename to vendor/distribute-0.6.36/setup.cfg
diff --git a/vendor/distribute-0.6.35/setup.py b/vendor/distribute-0.6.36/setup.py
similarity index 99%
rename from vendor/distribute-0.6.35/setup.py
rename to vendor/distribute-0.6.36/setup.py
index cecb9e9fdad3476a7a4123d27d055696ab68975c..607954d03a4bc23eb07ec478e44987d8ea1a9178 100644
--- a/vendor/distribute-0.6.35/setup.py
+++ b/vendor/distribute-0.6.36/setup.py
@@ -46,7 +46,7 @@ exec(init_file.read(), d)
init_file.close()
SETUP_COMMANDS = d['__all__']
-VERSION = "0.6.35"
+VERSION = "0.6.36"
from setuptools import setup, find_packages
from setuptools.command.build_py import build_py as _build_py
diff --git a/vendor/distribute-0.6.35/setuptools/__init__.py b/vendor/distribute-0.6.36/setuptools/__init__.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/__init__.py
rename to vendor/distribute-0.6.36/setuptools/__init__.py
diff --git a/vendor/distribute-0.6.35/setuptools/archive_util.py b/vendor/distribute-0.6.36/setuptools/archive_util.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/archive_util.py
rename to vendor/distribute-0.6.36/setuptools/archive_util.py
diff --git a/vendor/distribute-0.6.35/setuptools/cli-32.exe b/vendor/distribute-0.6.36/setuptools/cli-32.exe
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/cli-32.exe
rename to vendor/distribute-0.6.36/setuptools/cli-32.exe
diff --git a/vendor/distribute-0.6.35/setuptools/cli-64.exe b/vendor/distribute-0.6.36/setuptools/cli-64.exe
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/cli-64.exe
rename to vendor/distribute-0.6.36/setuptools/cli-64.exe
diff --git a/vendor/distribute-0.6.35/setuptools/cli.exe b/vendor/distribute-0.6.36/setuptools/cli.exe
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/cli.exe
rename to vendor/distribute-0.6.36/setuptools/cli.exe
diff --git a/vendor/distribute-0.6.35/setuptools/command/__init__.py b/vendor/distribute-0.6.36/setuptools/command/__init__.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/__init__.py
rename to vendor/distribute-0.6.36/setuptools/command/__init__.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/alias.py b/vendor/distribute-0.6.36/setuptools/command/alias.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/alias.py
rename to vendor/distribute-0.6.36/setuptools/command/alias.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/bdist_egg.py b/vendor/distribute-0.6.36/setuptools/command/bdist_egg.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/bdist_egg.py
rename to vendor/distribute-0.6.36/setuptools/command/bdist_egg.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/bdist_rpm.py b/vendor/distribute-0.6.36/setuptools/command/bdist_rpm.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/bdist_rpm.py
rename to vendor/distribute-0.6.36/setuptools/command/bdist_rpm.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/bdist_wininst.py b/vendor/distribute-0.6.36/setuptools/command/bdist_wininst.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/bdist_wininst.py
rename to vendor/distribute-0.6.36/setuptools/command/bdist_wininst.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/build_ext.py b/vendor/distribute-0.6.36/setuptools/command/build_ext.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/build_ext.py
rename to vendor/distribute-0.6.36/setuptools/command/build_ext.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/build_py.py b/vendor/distribute-0.6.36/setuptools/command/build_py.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/build_py.py
rename to vendor/distribute-0.6.36/setuptools/command/build_py.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/develop.py b/vendor/distribute-0.6.36/setuptools/command/develop.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/develop.py
rename to vendor/distribute-0.6.36/setuptools/command/develop.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/easy_install.py b/vendor/distribute-0.6.36/setuptools/command/easy_install.py
similarity index 99%
rename from vendor/distribute-0.6.35/setuptools/command/easy_install.py
rename to vendor/distribute-0.6.36/setuptools/command/easy_install.py
index 0d72f75843c999f14664c1fed34458f530638ca9..98af26209793088c9bf75079c0acdf3427cb2020 100644
--- a/vendor/distribute-0.6.35/setuptools/command/easy_install.py
+++ b/vendor/distribute-0.6.36/setuptools/command/easy_install.py
@@ -522,6 +522,10 @@ Please make the appropriate changes for your system and try again.
"""Write all the scripts for `dist`, unless scripts are excluded"""
if not self.exclude_scripts and dist.metadata_isdir('scripts'):
for script_name in dist.metadata_listdir('scripts'):
+ if dist.metadata_isdir('scripts/' + script_name):
+ # The "script" is a directory, likely a Python 3
+ # __pycache__ directory, so skip it.
+ continue
self.install_script(
dist, script_name,
dist.get_metadata('scripts/'+script_name)
diff --git a/vendor/distribute-0.6.35/setuptools/command/egg_info.py b/vendor/distribute-0.6.36/setuptools/command/egg_info.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/egg_info.py
rename to vendor/distribute-0.6.36/setuptools/command/egg_info.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/install.py b/vendor/distribute-0.6.36/setuptools/command/install.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/install.py
rename to vendor/distribute-0.6.36/setuptools/command/install.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/install_egg_info.py b/vendor/distribute-0.6.36/setuptools/command/install_egg_info.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/install_egg_info.py
rename to vendor/distribute-0.6.36/setuptools/command/install_egg_info.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/install_lib.py b/vendor/distribute-0.6.36/setuptools/command/install_lib.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/install_lib.py
rename to vendor/distribute-0.6.36/setuptools/command/install_lib.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/install_scripts.py b/vendor/distribute-0.6.36/setuptools/command/install_scripts.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/install_scripts.py
rename to vendor/distribute-0.6.36/setuptools/command/install_scripts.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/register.py b/vendor/distribute-0.6.36/setuptools/command/register.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/register.py
rename to vendor/distribute-0.6.36/setuptools/command/register.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/rotate.py b/vendor/distribute-0.6.36/setuptools/command/rotate.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/rotate.py
rename to vendor/distribute-0.6.36/setuptools/command/rotate.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/saveopts.py b/vendor/distribute-0.6.36/setuptools/command/saveopts.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/saveopts.py
rename to vendor/distribute-0.6.36/setuptools/command/saveopts.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/sdist.py b/vendor/distribute-0.6.36/setuptools/command/sdist.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/sdist.py
rename to vendor/distribute-0.6.36/setuptools/command/sdist.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/setopt.py b/vendor/distribute-0.6.36/setuptools/command/setopt.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/setopt.py
rename to vendor/distribute-0.6.36/setuptools/command/setopt.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/test.py b/vendor/distribute-0.6.36/setuptools/command/test.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/test.py
rename to vendor/distribute-0.6.36/setuptools/command/test.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/upload.py b/vendor/distribute-0.6.36/setuptools/command/upload.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/upload.py
rename to vendor/distribute-0.6.36/setuptools/command/upload.py
diff --git a/vendor/distribute-0.6.35/setuptools/command/upload_docs.py b/vendor/distribute-0.6.36/setuptools/command/upload_docs.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/command/upload_docs.py
rename to vendor/distribute-0.6.36/setuptools/command/upload_docs.py
diff --git a/vendor/distribute-0.6.35/setuptools/depends.py b/vendor/distribute-0.6.36/setuptools/depends.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/depends.py
rename to vendor/distribute-0.6.36/setuptools/depends.py
diff --git a/vendor/distribute-0.6.35/setuptools/dist.py b/vendor/distribute-0.6.36/setuptools/dist.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/dist.py
rename to vendor/distribute-0.6.36/setuptools/dist.py
diff --git a/vendor/distribute-0.6.35/setuptools/extension.py b/vendor/distribute-0.6.36/setuptools/extension.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/extension.py
rename to vendor/distribute-0.6.36/setuptools/extension.py
diff --git a/vendor/distribute-0.6.35/setuptools/gui-32.exe b/vendor/distribute-0.6.36/setuptools/gui-32.exe
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/gui-32.exe
rename to vendor/distribute-0.6.36/setuptools/gui-32.exe
diff --git a/vendor/distribute-0.6.35/setuptools/gui-64.exe b/vendor/distribute-0.6.36/setuptools/gui-64.exe
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/gui-64.exe
rename to vendor/distribute-0.6.36/setuptools/gui-64.exe
diff --git a/vendor/distribute-0.6.35/setuptools/gui.exe b/vendor/distribute-0.6.36/setuptools/gui.exe
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/gui.exe
rename to vendor/distribute-0.6.36/setuptools/gui.exe
diff --git a/vendor/distribute-0.6.35/setuptools/package_index.py b/vendor/distribute-0.6.36/setuptools/package_index.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/package_index.py
rename to vendor/distribute-0.6.36/setuptools/package_index.py
diff --git a/vendor/distribute-0.6.35/setuptools/sandbox.py b/vendor/distribute-0.6.36/setuptools/sandbox.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/sandbox.py
rename to vendor/distribute-0.6.36/setuptools/sandbox.py
diff --git a/vendor/distribute-0.6.35/setuptools/script template (dev).py b/vendor/distribute-0.6.36/setuptools/script template (dev).py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/script template (dev).py
rename to vendor/distribute-0.6.36/setuptools/script template (dev).py
diff --git a/vendor/distribute-0.6.35/setuptools/script template.py b/vendor/distribute-0.6.36/setuptools/script template.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/script template.py
rename to vendor/distribute-0.6.36/setuptools/script template.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/__init__.py b/vendor/distribute-0.6.36/setuptools/tests/__init__.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/__init__.py
rename to vendor/distribute-0.6.36/setuptools/tests/__init__.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/doctest.py b/vendor/distribute-0.6.36/setuptools/tests/doctest.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/doctest.py
rename to vendor/distribute-0.6.36/setuptools/tests/doctest.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/indexes/test_links_priority/external.html b/vendor/distribute-0.6.36/setuptools/tests/indexes/test_links_priority/external.html
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/indexes/test_links_priority/external.html
rename to vendor/distribute-0.6.36/setuptools/tests/indexes/test_links_priority/external.html
diff --git a/vendor/distribute-0.6.35/setuptools/tests/indexes/test_links_priority/simple/foobar/index.html b/vendor/distribute-0.6.36/setuptools/tests/indexes/test_links_priority/simple/foobar/index.html
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/indexes/test_links_priority/simple/foobar/index.html
rename to vendor/distribute-0.6.36/setuptools/tests/indexes/test_links_priority/simple/foobar/index.html
diff --git a/vendor/distribute-0.6.35/setuptools/tests/py26compat.py b/vendor/distribute-0.6.36/setuptools/tests/py26compat.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/py26compat.py
rename to vendor/distribute-0.6.36/setuptools/tests/py26compat.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/server.py b/vendor/distribute-0.6.36/setuptools/tests/server.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/server.py
rename to vendor/distribute-0.6.36/setuptools/tests/server.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/test_bdist_egg.py b/vendor/distribute-0.6.36/setuptools/tests/test_bdist_egg.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/test_bdist_egg.py
rename to vendor/distribute-0.6.36/setuptools/tests/test_bdist_egg.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/test_build_ext.py b/vendor/distribute-0.6.36/setuptools/tests/test_build_ext.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/test_build_ext.py
rename to vendor/distribute-0.6.36/setuptools/tests/test_build_ext.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/test_develop.py b/vendor/distribute-0.6.36/setuptools/tests/test_develop.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/test_develop.py
rename to vendor/distribute-0.6.36/setuptools/tests/test_develop.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/test_dist_info.py b/vendor/distribute-0.6.36/setuptools/tests/test_dist_info.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/test_dist_info.py
rename to vendor/distribute-0.6.36/setuptools/tests/test_dist_info.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/test_easy_install.py b/vendor/distribute-0.6.36/setuptools/tests/test_easy_install.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/test_easy_install.py
rename to vendor/distribute-0.6.36/setuptools/tests/test_easy_install.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/test_markerlib.py b/vendor/distribute-0.6.36/setuptools/tests/test_markerlib.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/test_markerlib.py
rename to vendor/distribute-0.6.36/setuptools/tests/test_markerlib.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/test_packageindex.py b/vendor/distribute-0.6.36/setuptools/tests/test_packageindex.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/test_packageindex.py
rename to vendor/distribute-0.6.36/setuptools/tests/test_packageindex.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/test_resources.py b/vendor/distribute-0.6.36/setuptools/tests/test_resources.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/test_resources.py
rename to vendor/distribute-0.6.36/setuptools/tests/test_resources.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/test_sandbox.py b/vendor/distribute-0.6.36/setuptools/tests/test_sandbox.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/test_sandbox.py
rename to vendor/distribute-0.6.36/setuptools/tests/test_sandbox.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/test_sdist.py b/vendor/distribute-0.6.36/setuptools/tests/test_sdist.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/test_sdist.py
rename to vendor/distribute-0.6.36/setuptools/tests/test_sdist.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/test_test.py b/vendor/distribute-0.6.36/setuptools/tests/test_test.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/test_test.py
rename to vendor/distribute-0.6.36/setuptools/tests/test_test.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/test_upload_docs.py b/vendor/distribute-0.6.36/setuptools/tests/test_upload_docs.py
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/test_upload_docs.py
rename to vendor/distribute-0.6.36/setuptools/tests/test_upload_docs.py
diff --git a/vendor/distribute-0.6.35/setuptools/tests/win_script_wrapper.txt b/vendor/distribute-0.6.36/setuptools/tests/win_script_wrapper.txt
similarity index 100%
rename from vendor/distribute-0.6.35/setuptools/tests/win_script_wrapper.txt
rename to vendor/distribute-0.6.36/setuptools/tests/win_script_wrapper.txt
diff --git a/vendor/distribute-0.6.35/site.py b/vendor/distribute-0.6.36/site.py
similarity index 100%
rename from vendor/distribute-0.6.35/site.py
rename to vendor/distribute-0.6.36/site.py
diff --git a/vendor/distribute-0.6.35/tests/api_tests.txt b/vendor/distribute-0.6.36/tests/api_tests.txt
similarity index 100%
rename from vendor/distribute-0.6.35/tests/api_tests.txt
rename to vendor/distribute-0.6.36/tests/api_tests.txt
diff --git a/vendor/distribute-0.6.35/tests/install_test.py b/vendor/distribute-0.6.36/tests/install_test.py
similarity index 100%
rename from vendor/distribute-0.6.35/tests/install_test.py
rename to vendor/distribute-0.6.36/tests/install_test.py
diff --git a/vendor/distribute-0.6.35/tests/manual_test.py b/vendor/distribute-0.6.36/tests/manual_test.py
similarity index 100%
rename from vendor/distribute-0.6.35/tests/manual_test.py
rename to vendor/distribute-0.6.36/tests/manual_test.py
diff --git a/vendor/distribute-0.6.35/tests/shlib_test/hello.c b/vendor/distribute-0.6.36/tests/shlib_test/hello.c
similarity index 100%
rename from vendor/distribute-0.6.35/tests/shlib_test/hello.c
rename to vendor/distribute-0.6.36/tests/shlib_test/hello.c
diff --git a/vendor/distribute-0.6.35/tests/shlib_test/hello.pyx b/vendor/distribute-0.6.36/tests/shlib_test/hello.pyx
similarity index 100%
rename from vendor/distribute-0.6.35/tests/shlib_test/hello.pyx
rename to vendor/distribute-0.6.36/tests/shlib_test/hello.pyx
diff --git a/vendor/distribute-0.6.35/tests/shlib_test/hellolib.c b/vendor/distribute-0.6.36/tests/shlib_test/hellolib.c
similarity index 100%
rename from vendor/distribute-0.6.35/tests/shlib_test/hellolib.c
rename to vendor/distribute-0.6.36/tests/shlib_test/hellolib.c
diff --git a/vendor/distribute-0.6.35/tests/shlib_test/setup.py b/vendor/distribute-0.6.36/tests/shlib_test/setup.py
similarity index 100%
rename from vendor/distribute-0.6.35/tests/shlib_test/setup.py
rename to vendor/distribute-0.6.36/tests/shlib_test/setup.py
diff --git a/vendor/distribute-0.6.35/tests/shlib_test/test_hello.py b/vendor/distribute-0.6.36/tests/shlib_test/test_hello.py
similarity index 100%
rename from vendor/distribute-0.6.35/tests/shlib_test/test_hello.py
rename to vendor/distribute-0.6.36/tests/shlib_test/test_hello.py
diff --git a/vendor/distribute-0.6.35/tests/test_distribute_setup.py b/vendor/distribute-0.6.36/tests/test_distribute_setup.py
similarity index 100%
rename from vendor/distribute-0.6.35/tests/test_distribute_setup.py
rename to vendor/distribute-0.6.36/tests/test_distribute_setup.py