[Python-checkins] r73751 - peps/trunk/pep-0376.txt

[tarek.ziade]

Author: tarek.ziade
Date: Thu Jul  2 10:45:29 2009
New Revision: 73751

Log:
clarified the egg.info part and added references about fedora and debian

Modified:
   peps/trunk/pep-0376.txt

Modified: peps/trunk/pep-0376.txt
==============================================================================
--- peps/trunk/pep-0376.txt	(original)
+++ peps/trunk/pep-0376.txt	Thu Jul  2 10:45:29 2009
@@ -85,23 +85,35 @@
 Some executable scripts, such as `rst2html.py`, will also be added in the
 `bin` directory of the Python installation.
 
-The problem is that many people use `easy_install` (from the `setuptools`
-project [#setuptools]_) or `pip` [#pip]_ to install their packages, and 
-these third-party tools do not install packages in the same way that Distutils 
-does:
-
-- `easy_install` creates an `EGG-INFO` directory inside an `.egg` directory
-  and adds a `PKG-INFO` file inside this directory. The `.egg` directory
-  contains all the elements of the distribution that are supposed to be
-  installed in `site-packages` and is placed in the `site-packages`
-  directory.
-
-- `pip` creates an `.egg-info` directory inside the `site-packages` directory
-  and adds a `PKG-INFO` file inside it. Elements of the distribution are then
-  installed in various places like Distutils does.
+Another project called `setuptools` [#setuptools]_ has introduced two new 
+formats to install distributions:
 
-They both add other files in the `EGG-INFO` or `.egg-info` directory and
-create or modify `.pth` files.
+- a self-contained `.egg` directory, that contains all the distribution files
+  and the distribution metadata in a file called `PKG-INFO` in a subdirectory
+  called `EGG-INFO`. Other files are created in that directory for 
+  `setuptools` needs.
+
+- a `.egg-info` directory installed in `site-packages`, that contains the same
+  files `EGG-INFO` has in the `.egg` format.
+
+The first format is automatically used when you install a distribution that
+uses ``setuptools.setup`` function in its setup.py file, instead of
+``distutils.core.setup``. 
+
+The `setuptools` project also provides an executable script called 
+`easy_install` that will install all istributions, including distutils-based
+ones in self-contained `.egg` directories.
+
+If you want to have a standalone `.egg.info` directory with setuptools-based 
+distributions, e.g. the second `setuptools` format, you have to force it 
+using the `-–single-version-externally-managed` option **or** the `--root` 
+option.
+
+This option is used by :
+
+- the `pip` [#pip]_ installer 
+- the Fedora packagers [#fedora]_.
+- the Debian packagers [#debian]_.
 
 Uninstall information
 ---------------------
@@ -139,8 +151,8 @@
 .egg-info becomes a directory
 =============================
 
-The `EggFormats` standard from setuptools proposes two formats to install the
-metadata information of a distribution:
+As explained earlier, the `EggFormats` standard from `setuptools` proposes two 
+formats to install the metadata information of a distribution:
 
 - A self-contained directory that can be zipped or left unzipped and contains
   the distribution files *and* an `.egg-info` directory containing the 
@@ -300,7 +312,7 @@
 ===================
 
 To use the `.egg-info` directory content, we need to add in the standard
-library a set of APIs. The best place to put these APIs seems to be `pkgutil`.
+library a set of APIs. The best place to put these APIs is `pkgutil`.
 
 The API is organized in five classes that work with directories and Zip files
 (so it works with files included in Zip files, see PEP 273 for more details
@@ -387,7 +399,7 @@
 Other public methods and attributes are similar to  ``Distribution``.
 
 DistributionDir class
----------------------------
+---------------------
 
 A new class called ``DistributionDir`` is created with a path
 corresponding to a directory. For each `.egg-info` directory founded in
@@ -409,7 +421,7 @@
 
 
 ZippedDistributionDir class
----------------------------------
+---------------------------
 
 A ``ZippedDistributionDir`` is provided. It overrides the
 ``DistributionDir`` class so its methods work with a Zip file.
@@ -422,7 +434,7 @@
 
 
 DistributionDirMap class
------------------------------
+------------------------
 
 A new class called ``DistributionDirMap`` is created. It's a collection of
 ``DistributionDir`` and ``ZippedDistributionDir`` instances.
@@ -687,6 +699,11 @@
 .. [#pep278]
    http://www.python.org/dev/peps/pep-0278
 
+.. [#fedora]
+   http://fedoraproject.org/wiki/Packaging/Python/Eggs#Providing_Eggs_using_Setuptools
+
+.. [#debian]
+   http://wiki.debian.org/DebianPython/NewPolicy
 
 Aknowledgments
 ==============