Ditch outdated TODO file, move docs to a new 'EasyInstall.txt' file. Fix

installation report for .egg files/directories.

--HG--
branch : setuptools
extra : convert_revision : svn%3A6015fed2-1504-0410-9fe1-9d1591cc4771/sandbox/trunk/setuptools%4041032

3 files changed, 274 insertions, 186 deletions

diff --git a/EasyInstall.txt b/EasyInstall.txt
new file mode 100755
index 00000000..0b94f61c
--- /dev/null
+++ b/EasyInstall.txt
@@ -0,0 +1,249 @@
+============
+Easy Install
+============
+
+Easy Install is a python module (``easy_install``) that lets you automatically
+download, build, install, and manage Python packages.
+
+(Please share your experiences with us! Whether you encountered success or
+difficulty installing a particular package, please add your notes to the
+`Experience Reports <http://peak.telecommunity.com/DevCenter/PackageNotes>`_
+page. You'll need to register for a Wiki ID if you don't already have one; you
+can do that from the `User Preferences
+<http://peak.telecommunity.com/DevCenter/UserPreferences>`_ page. Thanks!)
+
+.. contents:: **Table of Contents**
+
+
+Using "Easy Install"
+====================
+
+
+Installing "Easy Install"
+-------------------------
+
+Unix-like Systems (including Mac OS X and Cygwin)
+   Download either the `Python 2.3 easy_install shell script
+   <http://peak.telecommunity.com/dist/ez_install-0.3a3-py2.3-unix.sh>`_ or the
+   `Python 2.4 easy_install shell script
+   <http://peak.telecommunity.com/dist/ez_install-0.3a3-py2.4-unix.sh>`_. Place
+   the file somewhere on your PATH, after renaming it to ``easy_install``. Note
+   that these scripts assume you have ``python2.3`` or ``python2.4`` accessible
+   via the ``PATH`` environment variable. Then, you can use ``easy_install`` to
+   finish its own installation, by running one of the following, depending on
+   your Python version::
+
+     # Python 2.3
+     easy_install http://peak.telecommunity.com/dist/setuptools-0.3a3-py2.3.egg
+
+     # Python 2.4
+     easy_install http://peak.telecommunity.com/dist/setuptools-0.3a3-py2.4.egg
+
+
+All Other Systems
+   Download the `easy_install (aka setuptools) source distribution
+   <http://peak.telecommunity.com/dist/setuptools-0.3a3.zip>`_, and follow the
+   normal procedure for installing a source package with distutils. An
+   ``easy_install.py`` script will be installed in the normal location for
+   Python scripts on your platform. In the examples below, you'll need to
+   replace references to ``easy_install`` with the correct invocation to run
+   ``easy_install.py`` on your system. If you have Python 2.4 or better, you
+   can also use ``python -m easy_install``, which will have the same effect,
+   but which may be easier for you to type.
+
+
+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**. Download a source distribution, automatically building and
+installing it::
+
+    easy_install http://example.com/path/to/MyPackage-1.2.3.tgz
+
+**Example 2**. Install an already-downloaded .egg file::
+
+    easy_install /my_downloads/OtherPackage-3.2.1-py2.3.egg
+
+Easy Install recognizes distutils *source* (not binary) distribution files with
+extensions of .tgz, .tar, .tar.gz, .tar.bz2, or .zip. And of course it handles
+already-built .egg distributions.
+
+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.
+
+Packages installed to ``site-packages`` are added to an ``easy-install.pth``
+file, so that Python will be able to import the package by default. If you do
+not want this to happen, you should use the ``-m`` or ``--multi`` option, which
+allows multiple versions of the same package to be selected at runtime.
+
+Note that installing to a directory other than ``site-packages`` already
+implies the ``-m`` option, so if you cannot install to ``site-packages``,
+please see the `Command-Line Options`_ section below (under ``--multi``) to 
+find out how to select packages at runtime.
+
+
+Upgrading a Package
+-------------------
+
+You don't need to do anything special to upgrade a package: just install the
+new version. If you're using ``-m`` or ``--multi`` (or installing outside of
+``site-packages``), the runtime system automatically selects the newest
+available version of a package. If you're installing to ``site-packages`` and
+not using ``-m``, installing a package automatically replaces its older version
+in the ``easy-install.pth`` file, so that Python will import the latest version
+by default.
+
+``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 (``site-packages`` installs only)
+-------------------------------------------------------------
+
+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.
+Note that the named package and version must already have been installed to
+``site-packages``.
+
+If you'd like to switch to the latest version of ``PackageName``, you can do so
+like this::
+
+    easy_install PackageName
+
+This will activate the latest installed version.
+
+
+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.
+
+
+Reference Manual
+================
+
+
+Command-Line Options
+--------------------
+
+``--zip, -z``
+    Enable installing the package as a zip file. This can significantly
+    increase Python's overall import performance if you're installing to
+    ``site-packages`` and not using the ``--multi`` option, because Python
+    process zipfile entries on ``sys.path`` much faster than it does
+    directories. So, if you don't use this option, and you install a lot of
+    packages, some of them may be slower to import.
+
+    But, this option is disabled by default, unless you're installing from an
+    already-built binary zipfile (``.egg`` file). This is to avoid problems
+    when using packages that dosn't support running from a zip file. Such
+    packages usually access data files in their package directories using the
+    Python ``__file__`` or ``__path__`` attribute, instead of the
+    ``pkg_resources`` API. So, if you find that a package doesn't work properly
+    when used with this option, you may want to suggest to the author that they
+    switch to using the ``pkg_resources`` resource API, which will allow their
+    package to work whether it's installed as a zipfile or not.
+
+    (Note: this option only affects the installation of newly-built 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.)
+
+``--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.) Note that if you install to a directory other than ``site-packages``,
+    this option is automatically in effect, because ``.pth`` files can only be
+    used in ``site-packages`` (at least in Python 2.3 and 2.4). So, if you use
+    the ``--install-dir`` or ``-i`` options, you must also use ``require()`` to
+    enable packages at runtime
+
+``--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.
+
+``--build-directory=DIR, -b DIR`` (New in 0.3a3)
+    Set the directory used to download, extract, and install the package.  The
+    directory is not cleared before or after installation, so the downloaded
+    packages and extracted contents will remain there afterwards, allowing you
+    to read any documentation, examples, scripts, etc. that may have been
+    included with the source distribution (if any).
+
+
+Release Notes/Change History
+============================
+
+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)
+
+ * Added new options to ``bdist_egg`` to allow tagging the egg's version number
+   with a subversion revision number, the current date, or an explicit tag
+   value.  Run ``setup.py bdist_egg --help`` to get more information.
+
+ * Misc. bug fixes
+
+
+0.3a1
+ Initial release.
+
+
+
+Future Plans
+============
+
+* Support packages that include scripts
+
+* Automatic package download URL discovery via PyPI/CheeseShop
+
diff --git a/TODO.txt b/TODO.txt
deleted file mode 100644
index 368b2d73..00000000
--- a/TODO.txt
+++ /dev/null
@@ -1,38 +0,0 @@
-To-Do
-
-* Automatic download and installation of dependencies
-
-  * install_deps command (install runtime dependencies)
-
-    * OPEN ISSUE: should parent install command include child install's files?
-
-  * Dependency class
-
-    * Find appropriate release, or explain why not
-
-    * Base URL(s) and distribution name
-
-  * Release class
-
-    * Distro type - source v. binary (determine via extension?)
-
-    * Platform requirements, whether compiler needed (how can we check?)
-
-    * Download URL, default from extension + dependency
-
-    * Download + extract to target dir
-
-    * run child install
-
-  * build_deps command (install build-time dependencies)
-
-* Build and install documentation sets
-
-* Installation database similar to PEP 262
-
-  * Needs to write file *before* installing anything, so an aborted install
-    can be uninstalled.  Possibly should use 'unknown' for all metadata, then
-    replace with real metadata once it's known.
-
-  * REQUIRES should probably just be list of dependencies
-
diff --git a/easy_install.py b/easy_install.py
index 4bca9777..45590b62 100755
--- a/easy_install.py
+++ b/easy_install.py
@@ -1,165 +1,42 @@
 #!python
 """\
-Easy Install
-============
-
-Easy Install is a python module (easy_install) that lets you automatically
-download, build, install, and manage Python packages.
-
-.. contents:: **Table of Contents**
-
-
-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**. Download a source distribution, automatically building and
-installing it::
-
-    easy_install http://example.com/path/to/MyPackage-1.2.3.tgz
-
-**Example 2**. Install an already-downloaded .egg file::
-
-    easy_install /my_downloads/OtherPackage-3.2.1-py2.3.egg
-
-Easy Install recognizes distutils *source* (not binary) distribution files with
-extensions of .tgz, .tar, .tar.gz, .tar.bz2, or .zip. And of course it handles
-already-built .egg distributions.
-
-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.
-
-Packages installed to ``site-packages`` are added to an ``easy-install.pth``
-file, so that Python will be able to import the package by default. If you do
-not want this to happen, you should use the ``-m`` or ``--multi`` option, which
-allows multiple versions of the same package to be selected at runtime.
-
-Note that installing to a directory other than ``site-packages`` already
-implies the ``-m`` option, so if you cannot install to ``site-packages``,
-please see the `Options`_ section below (under ``--multi``) to find out how to
-select packages at runtime.
-
-
-Upgrading a Package
--------------------
-
-You don't need to do anything special to upgrade a package: just install the
-new version. If you're using ``-m`` or ``--multi`` (or installing outside of
-``site-packages``), the runtime system automatically selects the newest
-available version of a package. If you're installing to ``site-packages`` and
-not using ``-m``, installing a package automatically replaces its older version
-in the ``easy-install.pth`` file, so that Python will import the latest version
-by default.
-
-``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 (``site-packages`` installs only)
--------------------------------------------------------------
 
-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.
-Note that the named package and version must already have been installed to
-``site-packages``.
-
-If you'd like to switch to the latest version of ``PackageName``, you can do so
-like this::
-
-    easy_install PackageName
-
-This will activate the latest installed version.
-
-
-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).
+Easy Install
+------------
 
-If you want to delete the currently installed version of a package (or all
-versions of a package), you should first run::
+A tool for doing automatic download/extract/build of distutils-based Python
+packages.  For detailed documentation, see the accompanying EasyInstall.txt
+file, or visit the `EasyInstall home page`__.
 
-    easy_install -m PackageName
+__ http://peak.telecommunity.com/DevCenter/EasyInstall
 
-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.
+"""
 
+import sys
+import os.path
+import pkg_resources
+import re
+import zipimport
+import zipfile
+import tarfile
+import shutil
+import urlparse
+import urllib
+import tempfile
+import __builtin__
 
-Options
--------
+from distutils.sysconfig import get_python_lib
+from shutil import rmtree   # must have, because it can be called from __del__
+from pkg_resources import *
 
-``--zip, -z``
-    Enable installing the package as a zip file. This can significantly
-    increase Python's overall import performance if you're installing to
-    ``site-packages`` and not using the ``--multi`` option, because Python
-    process zipfile entries on ``sys.path`` much faster than it does
-    directories. So, if you don't use this option, and you install a lot of
-    packages, some of them may be slower to import.
+_os = sys.modules[os.name]
+_open = open
 
-    But, this option is disabled by default, unless you're installing from an
-    already-built binary zipfile (``.egg`` file). This is to avoid problems
-    when using packages that dosn't support running from a zip file. Such
-    packages usually access data files in their package directories using the
-    Python ``__file__`` or ``__path__`` attribute, instead of the
-    ``pkg_resources`` API. So, if you find that a package doesn't work properly
-    when used with this option, you may want to suggest to the author that they
-    switch to using the ``pkg_resources`` resource API, which will allow their
-    package to work whether it's installed as a zipfile or not.
 
-    (Note: this option only affects the installation of newly-built 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.)
 
-``--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.) Note that if you install to a directory other than ``site-packages``,
-    this option is automatically in effect, because ``.pth`` files can only be
-    used in ``site-packages`` (at least in Python 2.3 and 2.4). So, if you use
-    the ``--install-dir`` or ``-i`` options, you must also use ``require()`` to
-    enable packages at runtime
-
-``--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.
-"""
 
-import sys, os.path, pkg_resources, re, zipimport, zipfile, tarfile, shutil
-import urlparse, urllib, tempfile, __builtin__
-from distutils.sysconfig import get_python_lib
-from shutil import rmtree   # must have, because it can be called from __del__
-from pkg_resources import *
-_os = sys.modules[os.name]
-_open = open
 
 
 class Installer:
@@ -247,7 +124,7 @@ class Installer:
     def install_eggs(self, dist_filename):
         # .egg dirs or files are already built, so just return them
         if dist_filename.lower().endswith('.egg'):
-            return self.install_egg(dist_filename,True)
+            return [self.install_egg(dist_filename,True)]
 
         # Anything else, try to extract and build
         if os.path.isfile(dist_filename):