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

installation report for .egg files/directories.

1 files changed, 25 insertions, 148 deletions

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):