removed trailing spaces and added more examples on the RECORD file
This commit is contained in:
Tarek Ziadé
parent
0db50c5cd6
commit
b9d8c8e817
69
pep-0376.txt
69
pep-0376.txt
|
|
@ -85,7 +85,7 @@ extra module and executable scripts, three elements are installed in
|
|||
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 @@ The first format is automatically used when you install a distribution that
|
|||
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 @@ To address those issues, this PEP proposes a few changes:
|
|||
.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 @@ 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.
|
||||
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 @@ to a standard version string. Spaces become dots, and all other
|
|||
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 @@ Adding a RECORD file in the .egg-info directory
|
|||
|
||||
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 @@ Each record is composed of three elements.
|
|||
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 @@ Notice that:
|
|||
- `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 @@ The new functions added in the ``pkgutil`` are :
|
|||
|
||||
- ``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 @@ And following methods:
|
|||
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 @@ Extract from PEP 262 Requirements:
|
|||
|
||||
|
||||
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 @@ distribution.
|
|||
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 @@ Filtering
|
|||
---------
|
||||
|
||||
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 @@ References
|
|||
http://wiki.debian.org/DebianPython/NewPolicy
|
||||
|
||||
.. [#prototype]
|
||||
http://bitbucket.org/tarek/pep376/
|
||||
http://bitbucket.org/tarek/pep376/
|
||||
|
||||
Acknowledgements
|
||||
================
|
||||
|
|
|
|||
Loading…
Reference in New Issue