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

[tarek.ziade]

Author: tarek.ziade
Date: Wed Oct 14 20:39:17 2009
New Revision: 75414

Log:
applying Carl's changes

Modified:
   peps/trunk/pep-0376.txt

Modified: peps/trunk/pep-0376.txt
==============================================================================
--- peps/trunk/pep-0376.txt	(original)
+++ peps/trunk/pep-0376.txt	Wed Oct 14 20:39:17 2009
@@ -30,7 +30,7 @@
 The arguments passed to that function describe the distribution, like
 its `name`, its `version`, and so on.
 
-Disutils provides, among other things, **commands** that can be called
+Distutils provides, among other things, **commands** that can be called
 through the shell using the `setup.py` script. An `sdist` command is provided
 for instance to create a source distribution archive. An `install` command
 is also provided to perform an installation of the distribution in the Python
@@ -169,14 +169,12 @@
 This `.egg-info` directory contains a `PKG-INFO` file built by the 
 `write_pkg_file` method of the `Distribution` class in Distutils.
 
-This change is not impacting Python itself because the metadata files are not
+This change does not impact Python itself because the metadata files are not
 used anywhere yet in the standard library besides Distutils.
 
-However, it is impacting the `setuptools` and `pip` projects, but given
-the fact that they already work with a directory that contains a `PKG-INFO`
-file, the change will have no deep consequences. That said, packages installed
-other existing pre-standardisation formats are ignored by the new
-system, as explained in the backward compatibility section of this document.
+It does impact the `setuptools` and `pip` projects, but given the fact that
+they already work with a directory that contains a `PKG-INFO` file, the change
+will have no deep consequences.
 
 Let's take an example of the new format with the `docutils` distribution. 
 The elements installed in `site-packages` are::
@@ -318,6 +316,33 @@
 `.egg-info` directory with this value, to keep track of **who** installed the
 distribution. The file is a single-line text file.
 
+Adding a REQUESTED file in the .egg-info directory
+==================================================
+
+Some install tools automatically detect unfulfilled dependencies and
+install them. In these cases, it is useful to track which
+distributions were installed purely as a dependency, so if their
+dependent distribution is later uninstalled, the user can be alerted
+to the orphaned dependency.
+
+If a distribution is installed by direct user request (the usual
+case), a file REQUESTED is added to the .egg-info directory of the
+installed distribution. The REQUESTED file may be empty, or may
+contain a marker comment line beginning with the "#" character.
+
+If an install tool installs a distribution automatically, as a
+dependency of another distribution, the REQUESTED file should not be
+created.
+
+The ``install`` command of distutils by default creates the REQUESTED
+file. It accepts --requested and --no-requested options to explicitly
+specify whether the file is created.
+
+If a package that was already installed on the system as a dependency
+is later installed by name, the distutils ``install`` command will
+create the REQUESTED file in the .egg-info directory of the existing
+installation.
+
 New APIs in pkgutil
 ===================
 
@@ -368,6 +393,10 @@
 - ``metadata``: A ``DistributionMetadata`` instance loaded with the
   distribution's PKG-INFO file.
 
+- ``requested``: A boolean that indicates whether the REQUESTED
+  metadata file is present (in other words, whether the package was
+  installed by user request).
+
 And following methods:
 
 - ``get_installed_files(local=False)`` -> iterator of (path, md5, size)
@@ -445,6 +474,9 @@
     >>> dist.get_egginfo_file('PKG-INFO')
     <open file at ...>
 
+    >>> dist.requested
+    True
+
 PEP 262 replacement
 ===================
 
@@ -550,17 +582,24 @@
 another distribution. Although it makes sure that all the files it removes
 are not used by any other distribution, by using the uninstall function.
 
+Also note that this uninstall script pays no attention to the
+REQUESTED metadata; that is provided only for use by external tools to
+provide more advanced dependency management.
 
 Backward compatibility and roadmap
 ==================================
 
-These changes doesn't introduce any compatibility problems with the previous
+These changes don't introduce any compatibility problems with the previous
 version of Distutils, and will also work with existing third-party tools.
 
-Although, a backport of the new Distutils for 2.5, 2.6, 3.0 and 3.1 is
-provided so people can benefit from these new features.
-
-The plan is to integrate them for Python 2.7 and Python 3.2
+The plan is to include the functionality outlined in this PEP in distutils for
+Python 2.7 and Python 3.2. A backport of the new distutils for 2.5, 2.6, 3.0
+and 3.1 is provided so people can benefit from these new features.
+
+Distributions installed using existing, pre-standardization formats do not have
+the necessary metadata available for the new API, and thus will be
+ignored. Third-party tools may of course to continue to support previous
+formats in addition to the new format, in order to ease the transition.
 
 
 References
@@ -602,8 +641,8 @@
 .. [#prototype]
    http://bitbucket.org/tarek/pep376/   
 
-Aknowledgments
-==============
+Acknowledgements
+================
 
 Jim Fulton, Ian Bicking, Phillip Eby, and many people at Pycon and Distutils-SIG.