Commits

Lennart Regebro  committed d3b479b Merge

Merged Hannosh changes.

  • Participants
  • Parent commits f6e95a7, 538dfbc
  • Branches python3

Comments (0)

Files changed (20)

 distribute.egg-info
 build
 dist
+lib
+bin
+include
+\.Python
+=======
+CHANGES
+=======
+
+0.6
+===
+
+setuptools
+----------
+
+* Packages required at build time where not fully present at install time.
+  This closes http://bitbucket.org/tarek/distribute/issue/12.
+
+* Protected against failures in tarfile extraction. This closes
+  http://bitbucket.org/tarek/distribute/issue/10.
+
+* Made Jython api_tests.txt doctest compatible. This closes
+  http://bitbucket.org/tarek/distribute/issue/7.
+
+* sandbox.py replaced builtin type file with builtin function open. This
+  closes http://bitbucket.org/tarek/distribute/issue/6.
+
+* Immediately close all file handles. This closes
+  http://bitbucket.org/tarek/distribute/issue/3.
+
+* Added compatibility with Subversion 1.6. This references
+  http://bitbucket.org/tarek/distribute/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
+  http://bitbucket.org/tarek/distribute/issue/5.
+
+* Fixed a SandboxViolation for mkdir that could occur in certain cases.
+  This closes http://bitbucket.org/tarek/distribute/issue/13.
+
+* Allow to find_on_path on systems with tight permissions to fail gracefully.
+  This closes http://bitbucket.org/tarek/distribute/issue/9.
+
+* Corrected inconsistency between documentation and code of add_entry.
+  This closes http://bitbucket.org/tarek/distribute/issue/8.
+
+* Immediately close all file handles. This closes
+  http://bitbucket.org/tarek/distribute/issue/3.
+
+
+easy_install
+------------
+
+* Immediately close all file handles. This closes
+  http://bitbucket.org/tarek/distribute/issue/3.
+

File EasyInstall.txt

-============
-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 ``ez_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
-
-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::
-
-    [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`_::
-
-    [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 the `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::
-
-    [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::
-
-    [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>`_.
-
-
-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.
-
-``--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.
-
-``--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.
-
-    (If you want to *make* a non-``PYTHONPATH`` directory support ``.pth``
-    files, please see the `Administrator Installation`_ section below.)
-
-``--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
------------------------------
-
-EasyInstall manages what packages are active using Python ``.pth`` files, which
-are normally only usable in Python's main ``site-packages`` directory.  On some
-platforms (such as Mac OS X), there are additional ``site-packages``
-directories that you can use besides the main one, but usually there is only
-one directory on the system where you can install packages without extra steps.
-
-There are many reasons, however, why you might want to install packages
-somewhere other than the ``site-packages`` directory.  For example, you might
-not have write access to that directory.  You may be working with unstable
-versions of packages that you don't want to install system-wide.  And so on.
-
-The following sections describe various approaches to custom installation; feel
-free to choose which one best suits your system and needs.
-
-`Administrator Installation`_
-    This approach is for when you have write access to ``site-packages`` (or
-    another directory where ``.pth`` files are processed), but don't want to
-    install packages there.  This can also be used by a system administrator
-    to enable each user having their own private directories that EasyInstall
-    will use to install packages.
-
-`Mac OS X "User" Installation`_
-    This approach produces a result similar to an administrator installation
-    that gives each user their own private package directory, but on Mac OS X
-    the hard part has already been done for you.  This is probably the best
-    approach for Mac OS X users.
-
-`Creating a "Virtual" Python`_
-    This approach is for when you don't have "root" or access to write to the
-    ``site-packages`` directory, and would like to be able to set up one or
-    more "virtual python" executables for your projects.  This approach
-    gives you the benefits of multiple Python installations, but without having
-    to actually install Python more than once and use up lots of disk space.
-    (Only the Python executable is copied; the libraries will be symlinked
-    from the systemwide Python.)
-
-    If you don't already have any ``PYTHONPATH`` customization or
-    special distutils configuration, and you can't use either of the preceding
-    approaches, this is probably the best one for you.
-
-`"Traditional" PYTHONPATH-based Installation`_
-    If you already have a custom ``PYTHONPATH``, and/or a custom distutils
-    configuration, and don't want to change any of your existing setup, you may
-    be interested in this approach.  (If you're using a custom ``.pth`` file to
-    point to your custom installation location, however, you should use
-    `Administrator Installation`_ to enable ``.pth`` processing in the custom
-    location instead, as that is easier and more flexible than this approach.)
-
-
-Administrator Installation
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you have root access to your machine, you can easily configure it to allow
-each user to have their own directory where Python packages can be installed
-and managed by EasyInstall.
-
-First, create an ``altinstall.pth`` file in Python's ``site-packages``
-directory,  containing the following line (substituting the correct Python
-version)::
-
-    import os, site; site.addsitedir(os.path.expanduser('~/lib/python2.3'))
-
-This will automatically add each user's ``~/lib/python2.X`` directory to
-``sys.path`` (if it exists), *and* it will process any ``.pth`` files in that
-directory -- which is what makes it usable with EasyInstall.
-
-The next step is to create or modify ``distutils.cfg`` in the ``distutils``
-directory of your Python library.  The correct directory will be something like
-``/usr/lib/python2.X/distutils`` on most Posix systems and something like
-``C:\\Python2X\Lib\distutils`` on Windows machines.  Add the following lines
-to the file, substituting the correct Python version if necessary::
-
-    [install]
-    install_lib = ~/lib/python2.3
-
-    # This next line is optional but often quite useful; it directs EasyInstall
-    # and the distutils to install scripts in the user's "bin" directory.  For
-    # Mac OS X framework Python builds, you should use /usr/local/bin instead,
-    # because neither ~/bin nor the default script installation location are on
-    # the system PATH.
-    #
-    install_scripts = ~/bin
-
-This will configure the distutils and EasyInstall to install packages to the
-user's home directory by default.
-
-Of course, you aren't limited to using a ``~/lib/python2.X`` directory with
-this approach.  You can substitute a specific systemwide directory if you like.
-You can also edit ``~/.pydistutils.cfg`` (or ``~/pydistutils.cfg`` on Windows)
-instead of changing the master ``distutils.cfg`` file.  The true keys of this
-approach are simply that:
-
-1. any custom installation directory must be added to ``sys.path`` using a
-   ``site.addsitedir()`` call from a working ``.pth`` file or
-   ``sitecustomize.py``.
-
-2. The active distutils configuration file(s) or ``easy_install`` command line
-   should include the custom directory in the ``--site-dirs`` option, so that
-   EasyInstall knows that ``.pth`` files will work in that location.  (This is
-   because Python does not keep track of what directories are or aren't enabled
-   for ``.pth`` processing, in any way that EasyInstall can find out.)
-
-As long as both of these things have been done, your custom installation
-location is good to go.
-
-
-Mac OS X "User" Installation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you are on a Mac OS X machine, you should just use the
-``~/Library/Python/2.x/site-packages`` directory as your custom installation
-location, because it is already configured to process ``.pth`` files, and
-EasyInstall already knows this.
-
-Before installing EasyInstall/setuptools, just create a ``~/.pydistutils.cfg``
-file with the following contents (or add this to the existing contents)::
-
-    [install]
-    install_lib = ~/Library/Python/$py_version_short/site-packages
-    install_scripts = ~/bin
-
-This will tell the distutils and EasyInstall to always install packages in
-your personal ``site-packages`` directory, and scripts to ``~/bin``.  (Note: do
-*not* replace ``$py_version_short`` with an actual Python version in the
-configuration file!  The distutils will substitute the correct value at
-runtime, so that the above configuration file should work correctly no matter
-what Python version you use, now or in the future.)
-
-Once you have done this, you can follow the normal `installation instructions`_
-and use ``easy_install`` without any other special options or steps.
-
-(Note, however, that ``~/bin`` is not in the default ``PATH``, so you may have
-to refer to scripts by their full location.  You may want to modify your shell
-startup script (likely ``.bashrc`` or ``.profile``) or your
-``~/.MacOSX/environment.plist`` to include ``~/bin`` in your ``PATH``.
-
-
-Creating a "Virtual" Python
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you are on a Linux, BSD, Cygwin, or other similar Unix-like operating
-system, but don't have root access, you can create your own "virtual"
-Python installation, which uses its own library directories and some symlinks
-to the site-wide Python.
-
-In the simplest case, your virtual Python installation will live under the
-``~/lib/python2.x``, ``~/include/python2.x``, and ``~/bin`` directories.  Just
-download `virtual-python.py`_ and run it using the site-wide Python.  If you
-want to customize the location, you can use the ``--prefix`` option to specify
-an installation base directory in place of ``~``.  (Use ``--help`` to get the
-complete list of options.)
-
-.. _virtual-python.py: http://peak.telecommunity.com/dist/virtual-python.py
-
-When you're done, you'll have a ``~/bin/python`` executable that's linked to
-the local Python installation and inherits all its current libraries, but which
-allows you to add as many new libraries as you want.  Simply use this new
-Python in place of your system-defined one, and you can modify it as you like
-without breaking anything that relies on the system Python.  You'll also still
-need to follow the standard `installation instructions`_ to install setuptools
-and EasyInstall, using your new ``~/bin/python`` executable in place of the
-system Python.
-
-Note that if you were previously setting a ``PYTHONPATH`` and/or had other
-special configuration options in your ``~/.pydistutils.cfg``, you may need to
-remove these settings *before* running ``virtual-python.py``.  This is because
-your new Python executable will not need *any* custom configuration for the
-distutils or EasyInstall; everything will go to the correct ``~/lib`` and
-``~/bin`` directories automatically.
-
-You should, however, also make sure that the ``bin`` subdirectory of your
-installation prefix (e.g. ``~/bin``) is on your ``PATH``, because that is where
-EasyInstall and the distutils will install new Python scripts.
-
-
-"Traditional" ``PYTHONPATH``-based Installation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This installation method is not as robust or as flexible as `creating a
-"virtual" python`_ installation, as it uses various tricks to fool Python into
-processing ``.pth`` files where it normally wouldn't.  We suggest you at least
-consider using one of the other approaches, as they will generally result in
-a cleaner, more usable Python configuration.  However, if for some reason you
-can't or won't use one of the other approaches, here's how to do it.
-
-Assuming that you want to install packages in a directory called ``~/py-lib``,
-and scripts in ``~/bin``, here's what you need to do:
-
-First, edit ``~/.pydistutils.cfg`` to include these settings, if you don't
-already have them::
-
-    [install]
-    install_lib = ~/py-lib
-    install_scripts = ~/bin
-
-Be sure to do this *before* you try to run the ``ez_setup.py`` installation
-script.  Then, follow the standard `installation instructions`_, but make
-sure that ``~/py-lib`` is listed in your ``PYTHONPATH`` environment variable.
-
-Your library installation directory *must* be in listed in ``PYTHONPATH``,
-not only when you install packages with EasyInstall, but also when you use
-any packages that are installed using EasyInstall.  You will probably want to
-edit your ``~/.profile`` or other configuration file(s) to ensure that it is
-set, if you haven't already got this set up on your machine.
-
-
-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
-    &amp;digest=([0-9a-f]{32})">md5</a>\)
-
-
-Release Notes/Change History
-============================
-
-0.6final
- * Immediately close all file handles. This closes
-   http://bitbucket.org/tarek/distribute/issue/3.
-
-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?
-
 recursive-include setuptools *.py *.txt *.exe
 recursive-include tests *.py *.c *.pyx
+recursive-include docs *.py *.txt Makefile
 include *.py
 include *.txt
 include MANIFEST.in

File api_tests.txt

-Pluggable Distributions of Python Software
-==========================================
-
-Distributions
--------------
-
-A "Distribution" is a collection of files that represent a "Release" of a
-"Project" as of a particular point in time, denoted by a
-"Version"::
-
-    >>> import sys, pkg_resources
-    >>> from pkg_resources import Distribution
-    >>> Distribution(project_name="Foo", version="1.2")
-    Foo 1.2
-
-Distributions have a location, which can be a filename, URL, or really anything
-else you care to use::
-
-    >>> dist = Distribution(
-    ...     location="http://example.com/something",
-    ...     project_name="Bar", version="0.9"
-    ... )
-
-    >>> dist
-    Bar 0.9 (http://example.com/something)
-
-
-Distributions have various introspectable attributes::
-
-    >>> dist.location
-    'http://example.com/something'
-
-    >>> dist.project_name
-    'Bar'
-
-    >>> dist.version
-    '0.9'
-
-    >>> dist.py_version == sys.version[:3]
-    True
-
-    >>> print dist.platform
-    None
-
-Including various computed attributes::
-
-    >>> from pkg_resources import parse_version
-    >>> dist.parsed_version == parse_version(dist.version)
-    True
-
-    >>> dist.key    # case-insensitive form of the project name
-    'bar'
-
-Distributions are compared (and hashed) by version first::
-
-    >>> Distribution(version='1.0') == Distribution(version='1.0')
-    True
-    >>> Distribution(version='1.0') == Distribution(version='1.1')
-    False
-    >>> Distribution(version='1.0') <  Distribution(version='1.1')
-    True
-
-but also by project name (case-insensitive), platform, Python version,
-location, etc.::
-
-    >>> Distribution(project_name="Foo",version="1.0") == \
-    ... Distribution(project_name="Foo",version="1.0")
-    True
-
-    >>> Distribution(project_name="Foo",version="1.0") == \
-    ... Distribution(project_name="foo",version="1.0")
-    True
-
-    >>> Distribution(project_name="Foo",version="1.0") == \
-    ... Distribution(project_name="Foo",version="1.1")
-    False
-
-    >>> Distribution(project_name="Foo",py_version="2.3",version="1.0") == \
-    ... Distribution(project_name="Foo",py_version="2.4",version="1.0")
-    False
-
-    >>> Distribution(location="spam",version="1.0") == \
-    ... Distribution(location="spam",version="1.0")
-    True
-
-    >>> Distribution(location="spam",version="1.0") == \
-    ... Distribution(location="baz",version="1.0")
-    False
-
-
-
-Hash and compare distribution by prio/plat
-
-Get version from metadata
-provider capabilities
-egg_name()
-as_requirement()
-from_location, from_filename (w/path normalization)
-
-Releases may have zero or more "Requirements", which indicate
-what releases of another project the release requires in order to
-function.  A Requirement names the other project, expresses some criteria
-as to what releases of that project are acceptable, and lists any "Extras"
-that the requiring release may need from that project.  (An Extra is an
-optional feature of a Release, that can only be used if its additional
-Requirements are satisfied.)
-
-
-
-The Working Set
----------------
-
-A collection of active distributions is called a Working Set.  Note that a
-Working Set can contain any importable distribution, not just pluggable ones.
-For example, the Python standard library is an importable distribution that
-will usually be part of the Working Set, even though it is not pluggable.
-Similarly, when you are doing development work on a project, the files you are
-editing are also a Distribution.  (And, with a little attention to the
-directory names used,  and including some additional metadata, such a
-"development distribution" can be made pluggable as well.)
-
-    >>> from pkg_resources import WorkingSet
-
-A working set's entries are the sys.path entries that correspond to the active
-distributions.  By default, the working set's entries are the items on
-``sys.path``::
-
-    >>> ws = WorkingSet()
-    >>> ws.entries == sys.path
-    True
-
-But you can also create an empty working set explicitly, and add distributions
-to it::
-
-    >>> ws = WorkingSet([])
-    >>> ws.add(dist)
-    >>> ws.entries
-    ['http://example.com/something']
-    >>> dist in ws
-    True
-    >>> Distribution('foo',version="") in ws
-    False
-
-And you can iterate over its distributions::
-
-    >>> list(ws)
-    [Bar 0.9 (http://example.com/something)]
-
-Adding the same distribution more than once is a no-op::
-
-    >>> ws.add(dist)
-    >>> list(ws)
-    [Bar 0.9 (http://example.com/something)]
-
-For that matter, adding multiple distributions for the same project also does
-nothing, because a working set can only hold one active distribution per
-project -- the first one added to it::
-
-    >>> ws.add(
-    ...     Distribution(
-    ...         'http://example.com/something', project_name="Bar",
-    ...         version="7.2"
-    ...     )
-    ... )
-    >>> list(ws)
-    [Bar 0.9 (http://example.com/something)]
-
-You can append a path entry to a working set using ``add_entry()``::
-
-    >>> ws.entries
-    ['http://example.com/something']
-    >>> ws.add_entry(pkg_resources.__file__)
-    >>> ws.entries == ['http://example.com/something', pkg_resources.__file__]
-    True
-
-Multiple additions result in multiple entries, even if the entry is already in
-the working set (because ``sys.path`` can contain the same entry more than
-once)::
-
-    >>> ws.add_entry(pkg_resources.__file__)
-    >>> ws.entries
-    ['...example.com...', '...pkg_resources...', '...pkg_resources...']
-
-And you can specify the path entry a distribution was found under, using the
-optional second parameter to ``add()``::
-
-    >>> ws = WorkingSet([])
-    >>> ws.add(dist,"foo")
-    >>> ws.entries
-    ['foo']
-
-But even if a distribution is found under multiple path entries, it still only
-shows up once when iterating the working set:
-
-    >>> ws.add_entry(ws.entries[0])
-    >>> list(ws)
-    [Bar 0.9 (http://example.com/something)]
-
-You can ask a WorkingSet to ``find()`` a distribution matching a requirement::
-
-    >>> from pkg_resources import Requirement
-    >>> print ws.find(Requirement.parse("Foo==1.0"))    # no match, return None
-    None
-
-    >>> ws.find(Requirement.parse("Bar==0.9"))  # match, return distribution
-    Bar 0.9 (http://example.com/something)
-
-Note that asking for a conflicting version of a distribution already in a
-working set triggers a ``pkg_resources.VersionConflict`` error:
-
-    >>> from pkg_resources import VersionConflict
-    >>> try:
-    ...     ws.find(Requirement.parse("Bar==1.0")) # doctest: +NORMALIZE_WHITESPACE
-    ...     print "Expected VersionConflict, got nothing"
-    ... except VersionConflict, e:
-    ...     print e.args
-    (Bar 0.9 (http://example.com/something), Requirement.parse('Bar==1.0'))
-
-You can subscribe a callback function to receive notifications whenever a new
-distribution is added to a working set.  The callback is immediately invoked
-once for each existing distribution in the working set, and then is called
-again for new distributions added thereafter::
-
-    >>> def added(dist): print "Added", dist
-    >>> ws.subscribe(added)
-    Added Bar 0.9
-    >>> foo12 = Distribution(project_name="Foo", version="1.2", location="f12") 
-    >>> ws.add(foo12)
-    Added Foo 1.2
-
-Note, however, that only the first distribution added for a given project name
-will trigger a callback, even during the initial ``subscribe()`` callback::
-
-    >>> foo14 = Distribution(project_name="Foo", version="1.4", location="f14") 
-    >>> ws.add(foo14)   # no callback, because Foo 1.2 is already active
-
-    >>> ws = WorkingSet([])
-    >>> ws.add(foo12)
-    >>> ws.add(foo14)
-    >>> ws.subscribe(added)
-    Added Foo 1.2
-    
-And adding a callback more than once has no effect, either::
-
-    >>> ws.subscribe(added)     # no callbacks
-
-    # and no double-callbacks on subsequent additions, either
-    >>> just_a_test = Distribution(project_name="JustATest", version="0.99")
-    >>> ws.add(just_a_test)
-    Added JustATest 0.99
-
-
-Finding Plugins
----------------
-
-``WorkingSet`` objects can be used to figure out what plugins in an
-``Environment`` can be loaded without any resolution errors::
-
-    >>> from pkg_resources import Environment
-
-    >>> plugins = Environment([])   # normally, a list of plugin directories
-    >>> plugins.add(foo12)
-    >>> plugins.add(foo14)
-    >>> plugins.add(just_a_test)
-    
-In the simplest case, we just get the newest version of each distribution in
-the plugin environment::
-
-    >>> ws = WorkingSet([])
-    >>> ws.find_plugins(plugins)
-    ([JustATest 0.99, Foo 1.4 (f14)], {})
-
-But if there's a problem with a version conflict or missing requirements, the
-method falls back to older versions, and the error info dict will contain an
-exception instance for each unloadable plugin::
-
-    >>> ws.add(foo12)   # this will conflict with Foo 1.4
-    >>> ws.find_plugins(plugins)
-    ([JustATest 0.99, Foo 1.2 (f12)], {Foo 1.4 (f14): VersionConflict(...)})
-
-But if you disallow fallbacks, the failed plugin will be skipped instead of
-trying older versions::
-
-    >>> ws.find_plugins(plugins, fallback=False)
-    ([JustATest 0.99], {Foo 1.4 (f14): VersionConflict(...)})
-
-
-
-Platform Compatibility Rules
-----------------------------
-
-On the Mac, there are potential compatibility issues for modules compiled
-on newer versions of Mac OS X than what the user is running. Additionally,
-Mac OS X will soon have two platforms to contend with: Intel and PowerPC.
-
-Basic equality works as on other platforms::
-
-    >>> from pkg_resources import compatible_platforms as cp
-    >>> reqd = 'macosx-10.4-ppc'
-    >>> cp(reqd, reqd)
-    True
-    >>> cp("win32", reqd)
-    False
-
-Distributions made on other machine types are not compatible::
-
-    >>> cp("macosx-10.4-i386", reqd)
-    False
-
-Distributions made on earlier versions of the OS are compatible, as
-long as they are from the same top-level version. The patchlevel version
-number does not matter::
-
-    >>> cp("macosx-10.4-ppc", reqd)
-    True
-    >>> cp("macosx-10.3-ppc", reqd)
-    True
-    >>> cp("macosx-10.5-ppc", reqd)
-    False
-    >>> cp("macosx-9.5-ppc", reqd)
-    False
-
-Backwards compatibility for packages made via earlier versions of 
-setuptools is provided as well::
-
-    >>> cp("darwin-8.2.0-Power_Macintosh", reqd)
-    True
-    >>> cp("darwin-7.2.0-Power_Macintosh", reqd)
-    True
-    >>> cp("darwin-8.2.0-Power_Macintosh", "macosx-10.3-ppc")