diff --git a/pep-0376.txt b/pep-0376.txt index 42806ddb5..d8ba6eea4 100644 --- a/pep-0376.txt +++ b/pep-0376.txt @@ -30,7 +30,7 @@ extensions, or data. A distribution is managed by a special module called 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 @@ located in the site-packages directory, containing the metadata. 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 @@ When a distribution is installed, the INSTALLER file is generated in the `.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 @@ contained in `PKG-INFO` when it is instanciated. - ``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 @@ Let's use some of the new APIs with our `docutils` example:: >>> dist.get_egginfo_file('PKG-INFO') + >>> dist.requested + True + PEP 262 replacement =================== @@ -550,17 +582,24 @@ Notice that script doesn't control if the removal of a distribution breaks 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 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. -The plan is to integrate them for Python 2.7 and Python 3.2 +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 @@ References .. [#prototype] http://bitbucket.org/tarek/pep376/ -Aknowledgments -============== +Acknowledgements +================ Jim Fulton, Ian Bicking, Phillip Eby, and many people at Pycon and Distutils-SIG.