[Python-checkins] python/nondist/sandbox/setuptools EasyInstall.txt, 1.30, 1.31 setuptools.txt, 1.3, 1.4

[pje@users.sourceforge.net]

Update of /cvsroot/python/python/nondist/sandbox/setuptools
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv19865

Modified Files:
	EasyInstall.txt setuptools.txt 
Log Message:
Detect and handle conflicts with "unmanaged" packages when installing
packages managed by EasyInstall.  Also, add an option to exclude source
files from .egg distributions.


Index: EasyInstall.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/setuptools/EasyInstall.txt,v
retrieving revision 1.30
retrieving revision 1.31
diff -u -d -r1.30 -r1.31
--- EasyInstall.txt	8 Jul 2005 15:52:03 -0000	1.30
+++ EasyInstall.txt	10 Jul 2005 04:49:30 -0000	1.31
@@ -268,6 +268,36 @@
 more documentation on using distutils configuration files.
 
 
+Dealing with Installation Conflicts
+-----------------------------------
+
+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!
+
+
 Reference Manual
 ================
 
@@ -424,6 +454,23 @@
     every time you use EasyInstall (unless overridden on the command line) and
     thus may make startup slower.
 
+``--delete-conflicting, -D`` (New in 0.5a9)
+    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`` (New in 0.5a9)
+    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, -u URL`` (New in 0.4a1)
     Specifies the base URL of the Python Package Index.  The default is
     http://www.python.org/pypi if not specified.  When a package is requested
@@ -495,6 +542,20 @@
    in Exemaker.  So, don't use Exemaker to wrap ``easy_install.py``, or at any
    rate don't expect it to work with all packages.
 
+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.
+
 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.

Index: setuptools.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/setuptools/setuptools.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- setuptools.txt	9 Jul 2005 16:27:23 -0000	1.3
+++ setuptools.txt	10 Jul 2005 04:49:31 -0000	1.4
@@ -570,7 +570,7 @@
 any applications or frameworks that use that metadata.
 
 You won't usually need to specify any special options for this command; just
-use ``bdist_egg`` and you're done.  But there are a couple of options that may
+use ``bdist_egg`` and you're done.  But there are a few options that may
 be occasionally useful:
 
 ``--dist-dir=DIR, -d DIR``
@@ -590,6 +590,19 @@
     cross-compiling or doing some other unusual things, you might find a use
     for this option.
 
+``--exclude-source-files``
+    Don't include any modules' ``.py`` files in the egg, just compiled Python,
+    C, and data files.  (Note that this doesn't affect any ``.py`` files in the
+    EGG-INFO directory or its subdirectories, since for example there may be
+    scripts with a ``.py`` extension which must still be retained.)  We don't
+    recommend that you use this option except for packages that are being
+    bundled for proprietary end-user applications, or for "embedded" scenarios
+    where space is at an absolute premium.  On the other hand, if your package
+    is going to be installed and used in compressed form, you might as well
+    exclude the source because Python's ``traceback`` module doesn't currently
+    understand how to display zipped source code anyway, or how to deal with
+    files that are in a different place from where their code was compiled.
+
 There are also some options you will probably never need, but which are there
 because they were copied from similar ``bdist`` commands used as an example for
 creating this one.  They may be useful for testing and debugging, however,
@@ -726,8 +739,8 @@
 
 The following options can be used to modify the project's version string for
 all remaining commands on the setup command line.  The options are processed
-in the order shown, so if you use more than one, the request tags will be added
-in the following order:
+in the order shown, so if you use more than one, the requested tags will be
+added in the following order:
 
 ``--tag-build=NAME, -b NAME``
     Append NAME to the project's version string.  Due to the way setuptools
@@ -1049,6 +1062,23 @@
  * Changed --tag-svn-revision to include an "r" in front of the revision number
    for better readability.
 
+ * Added ability to build eggs without including source files (except for any
+   scripts, of course), using the ``--exclude-source-files`` option to
+   ``bdist_egg``.
+
+ * ``setup.py install`` now automatically detects when an "unmanaged" package
+   or module is going to be on ``sys.path`` ahead of a package being installed,
+   thereby preventing the newer version from being imported.  If this occurs,
+   a warning message is output to ``sys.stderr``, but installation proceeds
+   anyway.  The warning message informs the user what files or directories
+   need deleting, and advises them they can also use EasyInstall (with the
+   ``--delete-conflicting`` option) to do it automatically.
+
+ * The ``egg_info`` command now adds a ``top_level.txt`` file to the metadata
+   directory that lists all top-level modules and packages in the distribution.
+   This is used by the ``easy_install`` command to find possibly-conflicting
+   "unmanaged" packages when installing the distribution.
+
 0.5a8
  * The "egg_info" command now always sets the distribution metadata to "safe"
    forms of the distribution name and version, so that distribution files will