Author: tarek.ziade Date: Thu Mar 25 10:43:50 2010 New Revision: 79415 Log: removed trailing spaces and added more examples on the RECORD file Modified: peps/trunk/pep-0376.txt Modified: peps/trunk/pep-0376.txt ============================================================================== --- peps/trunk/pep-0376.txt (original) +++ peps/trunk/pep-0376.txt Thu Mar 25 10:43:50 2010 @@ -85,7 +85,7 @@ Some executable scripts, such as `rst2html.py`, are also be added in the `bin` directory of the Python installation. -Another project called `setuptools` [#setuptools]_ has two other formats +Another project called `setuptools` [#setuptools]_ has two other formats to install distributions, called `EggFormats` [#eggformats]_: - a self-contained `.egg` directory, that contains all the distribution files @@ -100,19 +100,19 @@ uses the ``setuptools.setup`` function in its setup.py file, instead of the ``distutils.core.setup`` one. -The `setuptools` project also provides an executable script called -`easy_install` [#easyinstall]_ that installs all distributions, including +The `setuptools` project also provides an executable script called +`easy_install` [#easyinstall]_ that installs all distributions, including distutils-based ones in self-contained `.egg` directories. -If you want to have a standalone `.egg.info` directory distributions, e.g. +If you want to have a standalone `.egg.info` directory distributions, e.g. the second `setuptools` format, you have to force it when you work with a setuptools-based distribution or with the `easy_install` script. -You can force it by using the `-–single-version-externally-managed` option +You can force it by using the `-–single-version-externally-managed` option **or** the `--root` option. This option is used by : -- the `pip` [#pip]_ installer +- the `pip` [#pip]_ installer - the Fedora packagers [#fedora]_. - the Debian packagers [#debian]_. @@ -152,21 +152,21 @@ .egg-info becomes a directory ============================= -As explained earlier, the `EggFormats` standard from `setuptools` proposes two +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 + 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 `.egg-info` directory +install the metadata of a distribution : a distinct `.egg-info` directory located in the site-packages directory, containing the metadata. -This `.egg-info` directory contains a `PKG-INFO` file built by the +This `.egg-info` directory contains a `PKG-INFO` file built by the `write_pkg_file` method of the `Distribution` class in Distutils. This change does not impact Python itself because the metadata files are not @@ -176,7 +176,7 @@ 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. +Let's take an example of the new format with the `docutils` distribution. The elements installed in `site-packages` are:: - docutils/ @@ -196,7 +196,7 @@ non-alphanumeric characters (except dots) become dashes, with runs of multiple dashes condensed to a single dash. Both attributes are then converted into their filename-escaped form, i.e. any '-' characters are -replaced with '_' other than the one in 'egg-info' and the one +replaced with '_' other than the one in 'egg-info' and the one separating the name from the version number. Examples:: @@ -215,15 +215,15 @@ A `RECORD` file is added inside the `.egg-info` directory at installation time when installing a source distribution using the `install` command. -Notice that when installing a binary distribution created with `bdist` command +Notice that when installing a binary distribution created with `bdist` command or a `bdist`-based command, the `RECORD` file will be installed as well since these commands use the `install` command to create a binary distributions. The `RECORD` file holds the list of installed files. These correspond to the files listed by the `record` option of the `install` command, and will be generated by default. This allows the implementation of an uninstallation -feature, as explained later in this PEP. The `install` command also provides -an option to prevent the `RECORD` file from being written and this option +feature, as explained later in this PEP. The `install` command also provides +an option to prevent the `RECORD` file from being written and this option should be used when creating system packages. Third-party installation tools also should not overwrite or delete files @@ -251,11 +251,11 @@ path, no matter what the target system is. This makes this information cross-compatible and allows simple installations to be relocatable. - - if the installed file is located under ``sys.prefix`` or + - if the installed file is located under ``sys.prefix`` or `sys.exec_prefix``, it's a it's a '/'-separated relative path prefixed by the `$PREFIX` or the `$EXEC_PREFIX` string. The `install` command decides which prefix to use depending on the files. For instance if - it's an executable script defined in the `scripts` option of the + it's an executable script defined in the `scripts` option of the setup script, `$EXEC_PREFIX` will be used. If `install` doesn't know which prefix to use, `$PREFIX` is preferred. @@ -301,6 +301,21 @@ - `docutils` and `docutils-0.5-py2.6.egg-info` are located in `site-packages` so the file paths are relative to it. +Example 2 +--------- + +If a project has files installed elswhere than under the Python installation +root, they are added in the RECORD file as full paths. For example a project +that installs a `config.ini` file in `/etc/myapp` will be added like this:: + + /etc/myapp/config.ini,b690274f621402dda63bf11ba5373bf2,9544 + +For a windows platform, the drive letter is added for the absolute paths, +so a file that is copied in `c:\MyApp\` will be:: + + c:\etc\myapp\config.ini,b690274f621402dda63bf11ba5373bf2,9544 + + Adding an INSTALLER file in the .egg-info directory =================================================== @@ -356,15 +371,15 @@ - ``get_distributions()`` -> iterator of ``Distribution`` instances. - Provides an iterator that looks for ``.egg-info`` directories in + Provides an iterator that looks for ``.egg-info`` directories in ``sys.path`` and returns ``Distribution`` instances for each one of them. - ``get_distribution(name)`` -> ``Distribution`` or None. Scans all elements in ``sys.path`` and looks for all directories ending with - ``.egg-info``. Returns a ``Distribution`` corresponding to the - ``.egg-info`` directory that contains a PKG-INFO that matches `name` + ``.egg-info``. Returns a ``Distribution`` corresponding to the + ``.egg-info`` directory that contains a PKG-INFO that matches `name` for the `name` metadata. Notice that there should be at most one result. The first result founded @@ -438,9 +453,9 @@ local absolute path. Otherwise the raw value from `RECORD` is returned. -Notice that the API is organized in five classes that work with directories +Notice that 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 [#pep273]_). These classes are described in the documentation +more details [#pep273]_). These classes are described in the documentation of the prototype implementation for interested readers [#prototype]_. Usage example @@ -490,11 +505,11 @@ Since the APIs proposed in the current PEP provide everything needed to meet -this requirement, PEP 376 replaces PEP 262 and becomes the official +this requirement, PEP 376 replaces PEP 262 and becomes the official `installation database` standard. The new version of PEP 345 (XXX work in progress) extends the Metadata -standard and fullfills the requirements described in PEP 262, like the +standard and fullfills the requirements described in PEP 262, like the `REQUIRES` section. Adding an Uninstall function @@ -507,7 +522,7 @@ Distutils will provide a very basic ``uninstall`` function, that is added in ``distutils.util`` and takes the name of the distribution to uninstall as its argument. ``uninstall`` uses the APIs described earlier and remove all -unique files, as long as their hash didn't change. Then it removes empty +unique files, as long as their hash didn't change. Then it removes empty directories left behind. ``uninstall`` returns a list of uninstalled files:: @@ -524,7 +539,7 @@ --------- To make it a reference API for third-party projects that wish to control -how `uninstall` works, a second callable argument can be used. It's +how `uninstall` works, a second callable argument can be used. It's called for each file that is removed. If the callable returns `True`, the file is removed. If it returns False, it's left alone. @@ -639,7 +654,7 @@ http://wiki.debian.org/DebianPython/NewPolicy .. [#prototype] - http://bitbucket.org/tarek/pep376/ + http://bitbucket.org/tarek/pep376/ Acknowledgements ================