From e0526346c59f4da890eca430516b9f8f803b93e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Thu, 1 Apr 2010 21:33:33 +0000 Subject: [PATCH] typo + clarified the dist-info section --- pep-0376.txt | 63 +++++++++++++++++++++++----------------------------- 1 file changed, 28 insertions(+), 35 deletions(-) diff --git a/pep-0376.txt b/pep-0376.txt index e6e06e687..edd5eb9d4 100644 --- a/pep-0376.txt +++ b/pep-0376.txt @@ -138,39 +138,31 @@ To address those issues, this PEP proposes a few changes: One .dist-info directory per installed distribution =================================================== -As explained earlier, the `EggFormats` standard from `setuptools` proposes two -formats to install the metadata information of a distribution: +This PEP proposes an installation format inspired by one of the options in the +`EggFormats` standard, the one that uses a distinct directory located in the +site-packages directory. -- A self-contained directory that can be zipped or left unzipped and contains - the distribution files *and* an `.egg-info` directory containing the - metadata. - -- A distinct `.egg-info` directory located in the site-packages directory, - with the metadata inside. - -This PEP proposes to keep just one format and make it the standard way to -install the metadata of a distribution : a distinct `.dist-info` directory -located in the site-packages directory, containing the PKG-INFO metadata -file, renamed to METADATA, and some other files. - -This change will not impact Python itself because the metadata files are not -used anywhere yet in the standard library besides Distutils. - -It will 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. - -The syntax of the `dist-info` directory name is as follows:: +This distinct directory is named as follows:: name + '-' + version + '.dist-info' -This `.dist-info` directory will contain these files: +This `.dist-info` directory can contain these files: -- `METADATA`: the metadata, as described in PEP 345, PEP 314 and PEP 241. -- `RECORD`: list of installed files -- `INSTALLER`: the installer that was used -- `REQUESTED`: a marker to know if the project was installed as a dependency - or not. +- `METADATA`: contains metadata, as described in PEP 345, PEP 314 and PEP 241. +- `RECORD`: records the list of installed files +- `INSTALLER`: records the name of the tool used to install the project +- `REQUESTED`: the presence of this file indicates that the project + installation was explicitly requested (i.e., not installed as a dependency). + +The METADATA, RECORD and INSTALLER files are mandatory, while REQUESTED may +be missing. + +This proposal will not impact Python itself because the metadata files are not +used anywhere yet in the standard library besides Distutils. + +It will 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. RECORD @@ -216,7 +208,8 @@ Each record is composed of three elements: - the file's size in bytes The ``csv`` module is used to generate this file, so the field separator is -",". Any "," characters found within a field is escaped automatically by ``csv``. +",". Any "," character found within a field is escaped automatically by +``csv``. When the file is read, the `U` option is used so the universal newline support (see PEP 278 [#pep278]_) is activated, avoiding any trouble @@ -469,7 +462,7 @@ directories left behind. ... '/opt/local/lib/python2.6/site-packages/docutils/__init__.py'] -If the distribution is not found, a ``DistutilsUninstallError`` is be raised. +If the distribution is not found, a ``DistutilsUninstallError`` is raised. Filtering ~~~~~~~~~ @@ -493,8 +486,8 @@ Examples:: ... >>> uninstall('docutils', _dry_run) -Of course, a third-party tool can use ``pkgutil`` APIs to implement -its own uninstall feature. +Of course, a third-party tool can use lower-level ``pkgutil`` APIs to +implement its own uninstall feature. Installer marker ~~~~~~~~~~~~~~~~ @@ -502,9 +495,9 @@ Installer marker As explained earlier in this PEP, the `install` command adds an `INSTALLER` file in the `.dist-info` directory with the name of the installer. -To avoid removing distributions that where installed by another packaging system, -the ``uninstall`` function takes an extra argument ``installer`` which default -to ``distutils``. +To avoid removing distributions that were installed by another packaging +system, the ``uninstall`` function takes an extra argument ``installer`` which +defaults to ``distutils``. When called, ``uninstall`` controls that the ``INSTALLER`` file matches this argument. If not, it raises a ``DistutilsUninstallError``::