removed the future tense usage when not required
This commit is contained in:
Tarek Ziadé
parent
d6a6a966c3
commit
b279051076
90
pep-0376.txt
90
pep-0376.txt
|
|
@ -73,7 +73,7 @@ The `install_egg_info` subcommand is called during this process in order to
|
|||
create an `.egg-info` file in the `purelib` directory.
|
||||
|
||||
For example, for the `docutils` distribution, which contains one package an
|
||||
extra module and executable scripts, three elements will be installed in
|
||||
extra module and executable scripts, three elements are installed in
|
||||
`site-packages`:
|
||||
|
||||
- `docutils`: The ``docutils`` package.
|
||||
|
|
@ -82,7 +82,7 @@ extra module and executable scripts, three elements will be installed in
|
|||
as described in PEP 314 [#pep314]_. This file corresponds to the file
|
||||
called `PKG-INFO`, built by the `sdist` command.
|
||||
|
||||
Some executable scripts, such as `rst2html.py`, will also be added in the
|
||||
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
|
||||
|
|
@ -101,7 +101,7 @@ 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 will install all distributions, including
|
||||
`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.
|
||||
|
|
@ -166,20 +166,20 @@ 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
|
||||
located in the site-packages directory, containing the metadata.
|
||||
|
||||
This `.egg-info` directory will contain 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 will not impact Python itself because the metadata files are not
|
||||
This change is not impacting Python itself because the metadata files are not
|
||||
used anywhere yet in the standard library besides Distutils.
|
||||
|
||||
However, it will impact the `setuptools` and `pip` projects, but given
|
||||
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 will be ignored by the new
|
||||
other existing pre-standardisation formats are ignored by the new
|
||||
system, as explained in the backward compatibility section of this document.
|
||||
|
||||
Let's take an example of the new format with the `docutils` distribution.
|
||||
The elements that will be installed in `site-packages` will become::
|
||||
The elements installed in `site-packages` are::
|
||||
|
||||
- docutils/
|
||||
- roman.py
|
||||
|
|
@ -215,13 +215,13 @@ Examples::
|
|||
Adding a RECORD file in the .egg-info directory
|
||||
===============================================
|
||||
|
||||
A `RECORD` file will be added inside the `.egg-info` directory at installation
|
||||
time. The `RECORD` file will hold the list of installed files. These correspond
|
||||
A `RECORD` file is added inside the `.egg-info` directory at installation
|
||||
time. 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 will allow uninstallation, as explained later in
|
||||
this PEP. The `install` command will also provide an option to prevent the
|
||||
`RECORD` file from being written and this option should be used when creating
|
||||
system packages.
|
||||
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
|
||||
should be used when creating system packages.
|
||||
|
||||
Third-party installation tools also should not overwrite or delete files
|
||||
that are not in a RECORD file without prompting or warning.
|
||||
|
|
@ -244,7 +244,7 @@ Each record is composed of three elements.
|
|||
- the file's full **path**
|
||||
|
||||
- if the installed file is located in the directory where the `.egg-info`
|
||||
directory of the package is located, it will be a '/'-separated relative
|
||||
directory of the package is located, it's a '/'-separated relative
|
||||
path, no matter what the target system is. This makes this information
|
||||
cross-compatible and allows simple installations to be relocatable.
|
||||
|
||||
|
|
@ -252,26 +252,25 @@ Each record is composed of three elements.
|
|||
'/'-separated absolute path is used.
|
||||
|
||||
- the **MD5** hash of the file, encoded in hex. Notice that `pyc` and `pyo`
|
||||
generated files will not have a hash because they are automatically produced
|
||||
generated files don't have any hash because they are automatically produced
|
||||
from `py` files. So checking the hash of the corresponding `py` file is
|
||||
enough to decide if the file and its associated `pyc` or `pyo` files have
|
||||
changed.
|
||||
|
||||
- the file's size in bytes
|
||||
|
||||
The ``csv`` module will be used to generate this file, so the field
|
||||
separator will be ",". Any "," characters found within a field
|
||||
will be escaped automatically by ``csv``.
|
||||
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``.
|
||||
|
||||
When the file is read, the `U` option will be used so the universal newline
|
||||
support (see PEP 278 [#pep278]_) will be activated, avoiding any trouble
|
||||
When the file is read, the `U` option is used so the universal newline
|
||||
support (see PEP 278 [#pep278]_) is activated, avoiding any trouble
|
||||
reading a file produced on a platform that uses a different new line
|
||||
terminator.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
Back to our `docutils` example, we will have::
|
||||
Back to our `docutils` example, we now have::
|
||||
|
||||
- docutils/
|
||||
- roman.py
|
||||
|
|
@ -279,7 +278,7 @@ Back to our `docutils` example, we will have::
|
|||
PKG-INFO
|
||||
RECORD
|
||||
|
||||
And the RECORD file will contain (extract)::
|
||||
And the RECORD file contains (extract)::
|
||||
|
||||
docutils/__init__.py,b690274f621402dda63bf11ba5373bf2,9544
|
||||
docutils/core.py,9c4b84aff68aa55f2e9bf70481b94333,66188
|
||||
|
|
@ -297,13 +296,13 @@ Notice that:
|
|||
Adding an INSTALLER file in the .egg-info directory
|
||||
===================================================
|
||||
|
||||
The `install` command will have a new option called `installer`. This option
|
||||
The `install` command has a new option called `installer`. This option
|
||||
is the name of the tool used to invoke the installation. It's an normalized
|
||||
lower-case string matching `[a-z0-9_\-\.]`.
|
||||
|
||||
$ python setup.py install --installer=pkg-system
|
||||
|
||||
It will default to `distutils` if not provided.
|
||||
It defaults to `distutils` if not provided.
|
||||
|
||||
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
|
||||
|
|
@ -334,7 +333,7 @@ The new functions added in the ``pkgutil`` are :
|
|||
for the `name` metadata.
|
||||
|
||||
Notice that there should be at most one result. The first result founded
|
||||
will be returned. If the directory is not found, returns None.
|
||||
is returned. If the directory is not found, returns None.
|
||||
|
||||
- ``get_file_users(path)`` -> iterator of ``Distribution`` instances.
|
||||
|
||||
|
|
@ -449,11 +448,11 @@ Extract from PEP 262 Requirements:
|
|||
|
||||
|
||||
Since the APIs proposed in the current PEP provide everything needed to meet
|
||||
this requirement, PEP 376 will replace PEP 262 and will become 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) will extend the Metadata
|
||||
standard and will fullfill the requirements described in PEP 262, like the
|
||||
The new version of PEP 345 (XXX work in progress) extends the Metadata
|
||||
standard and fullfills the requirements described in PEP 262, like the
|
||||
`REQUIRES` section.
|
||||
|
||||
Adding an Uninstall function
|
||||
|
|
@ -463,13 +462,13 @@ Distutils already provides a very basic way to install a distribution, which
|
|||
is running the `install` command over the `setup.py` script of the
|
||||
distribution.
|
||||
|
||||
Distutils will provide a very basic ``uninstall`` function, that will be added
|
||||
in ``distutils.util`` and will take the name of the distribution to uninstall
|
||||
as its argument. ``uninstall`` will use the APIs desribed earlier and remove all
|
||||
unique files, as long as their hash didn't change. Then it will remove
|
||||
empty directories left behind.
|
||||
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 desribed earlier and remove all
|
||||
unique files, as long as their hash didn't change. Then it removes empty
|
||||
directories left behind.
|
||||
|
||||
``uninstall`` will return a list of uninstalled files::
|
||||
``uninstall`` returns a list of uninstalled files::
|
||||
|
||||
>>> from distutils.util import uninstall
|
||||
>>> uninstall('docutils')
|
||||
|
|
@ -477,15 +476,15 @@ empty directories left behind.
|
|||
...
|
||||
'/opt/local/lib/python2.6/site-packages/docutils/__init__.py']
|
||||
|
||||
If the distribution is not found, a ``DistutilsUninstallError`` will be raised.
|
||||
If the distribution is not found, a ``DistutilsUninstallError`` is be raised.
|
||||
|
||||
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 will be
|
||||
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 will be removed. If it returns False, it will be left alone.
|
||||
file is removed. If it returns False, it's left alone.
|
||||
|
||||
Examples::
|
||||
|
||||
|
|
@ -514,8 +513,8 @@ To avoid removing distributions that where installed by another packaging system
|
|||
the ``uninstall`` function takes an extra argument ``installer`` which default
|
||||
to ``distutils``.
|
||||
|
||||
When called, ``uninstall`` will control that the ``INSTALLER`` file matches
|
||||
this argument. If not, it will raise a ``DistutilsUninstallError``::
|
||||
When called, ``uninstall`` controls that the ``INSTALLER`` file matches
|
||||
this argument. If not, it raises a ``DistutilsUninstallError``::
|
||||
|
||||
>>> uninstall('docutils')
|
||||
Traceback (most recent call last):
|
||||
|
|
@ -533,23 +532,22 @@ it has to undo at uninstallation time.
|
|||
Adding an Uninstall script
|
||||
==========================
|
||||
|
||||
An `uninstall` script will be added in Distutils. and will be used
|
||||
like this::
|
||||
An `uninstall` script is added in Distutils. and is used like this::
|
||||
|
||||
$ python -m distutils.uninstall packagename
|
||||
|
||||
Notice that script will not control if the removal of a distribution breaks
|
||||
another distribution. Although it will make sure that all the files it removes
|
||||
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.
|
||||
|
||||
|
||||
Backward compatibility and roadmap
|
||||
==================================
|
||||
|
||||
These changes will not introduce any compatibility problems with the previous
|
||||
These changes doesn'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 will be
|
||||
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 integrate them for Python 2.7 and Python 3.2
|
||||
|
|
|
|||
Loading…
Reference in New Issue