[Python-checkins] r79415 - peps/trunk/pep-0376.txt
tarek.ziade
python-checkins at python.org
Thu Mar 25 10:43:51 CET 2010
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
================
More information about the Python-checkins
mailing list