removed the future tense usage when not required
This commit is contained in:
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.
|
create an `.egg-info` file in the `purelib` directory.
|
||||||
|
|
||||||
For example, for the `docutils` distribution, which contains one package an
|
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`:
|
`site-packages`:
|
||||||
|
|
||||||
- `docutils`: The ``docutils`` package.
|
- `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
|
as described in PEP 314 [#pep314]_. This file corresponds to the file
|
||||||
called `PKG-INFO`, built by the `sdist` command.
|
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.
|
`bin` directory of the Python installation.
|
||||||
|
|
||||||
Another project called `setuptools` [#setuptools]_ has two other formats
|
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 ``distutils.core.setup`` one.
|
||||||
|
|
||||||
The `setuptools` project also provides an executable script called
|
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.
|
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.
|
||||||
|
@ -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
|
install the metadata of a distribution : a distinct `.egg-info` directory
|
||||||
located in the site-packages directory, containing the metadata.
|
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.
|
`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.
|
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`
|
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
|
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.
|
system, as explained in the backward compatibility section of this document.
|
||||||
|
|
||||||
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 that will be installed in `site-packages` will become::
|
The elements installed in `site-packages` are::
|
||||||
|
|
||||||
- docutils/
|
- docutils/
|
||||||
- roman.py
|
- roman.py
|
||||||
|
@ -215,13 +215,13 @@ Examples::
|
||||||
Adding a RECORD file in the .egg-info directory
|
Adding a RECORD file in the .egg-info directory
|
||||||
===============================================
|
===============================================
|
||||||
|
|
||||||
A `RECORD` file will be added inside the `.egg-info` directory at installation
|
A `RECORD` file is added inside the `.egg-info` directory at installation
|
||||||
time. The `RECORD` file will hold the list of installed files. These correspond
|
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
|
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
|
be generated by default. This allows the implementation of an uninstallation
|
||||||
this PEP. The `install` command will also provide an option to prevent the
|
feature, as explained later in this PEP. The `install` command also provides
|
||||||
`RECORD` file from being written and this option should be used when creating
|
an option to prevent the `RECORD` file from being written and this option
|
||||||
system packages.
|
should be used when creating system packages.
|
||||||
|
|
||||||
Third-party installation tools also should not overwrite or delete files
|
Third-party installation tools also should not overwrite or delete files
|
||||||
that are not in a RECORD file without prompting or warning.
|
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**
|
- the file's full **path**
|
||||||
|
|
||||||
- if the installed file is located in the directory where the `.egg-info`
|
- 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
|
path, no matter what the target system is. This makes this information
|
||||||
cross-compatible and allows simple installations to be relocatable.
|
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.
|
'/'-separated absolute path is used.
|
||||||
|
|
||||||
- the **MD5** hash of the file, encoded in hex. Notice that `pyc` and `pyo`
|
- 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
|
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
|
enough to decide if the file and its associated `pyc` or `pyo` files have
|
||||||
changed.
|
changed.
|
||||||
|
|
||||||
- the file's size in bytes
|
- the file's size in bytes
|
||||||
|
|
||||||
The ``csv`` module will be used to generate this file, so the field
|
The ``csv`` module is used to generate this file, so the field separator is
|
||||||
separator will be ",". Any "," characters found within a field
|
",". Any "," characters found within a field is escaped automatically by ``csv``.
|
||||||
will be escaped automatically by ``csv``.
|
|
||||||
|
|
||||||
When the file is read, the `U` option will be used so the universal newline
|
When the file is read, the `U` option is used so the universal newline
|
||||||
support (see PEP 278 [#pep278]_) will be activated, avoiding any trouble
|
support (see PEP 278 [#pep278]_) is activated, avoiding any trouble
|
||||||
reading a file produced on a platform that uses a different new line
|
reading a file produced on a platform that uses a different new line
|
||||||
terminator.
|
terminator.
|
||||||
|
|
||||||
Example
|
Example
|
||||||
-------
|
-------
|
||||||
|
|
||||||
Back to our `docutils` example, we will have::
|
Back to our `docutils` example, we now have::
|
||||||
|
|
||||||
- docutils/
|
- docutils/
|
||||||
- roman.py
|
- roman.py
|
||||||
|
@ -279,7 +278,7 @@ Back to our `docutils` example, we will have::
|
||||||
PKG-INFO
|
PKG-INFO
|
||||||
RECORD
|
RECORD
|
||||||
|
|
||||||
And the RECORD file will contain (extract)::
|
And the RECORD file contains (extract)::
|
||||||
|
|
||||||
docutils/__init__.py,b690274f621402dda63bf11ba5373bf2,9544
|
docutils/__init__.py,b690274f621402dda63bf11ba5373bf2,9544
|
||||||
docutils/core.py,9c4b84aff68aa55f2e9bf70481b94333,66188
|
docutils/core.py,9c4b84aff68aa55f2e9bf70481b94333,66188
|
||||||
|
@ -297,13 +296,13 @@ Notice that:
|
||||||
Adding an INSTALLER file in the .egg-info directory
|
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
|
is the name of the tool used to invoke the installation. It's an normalized
|
||||||
lower-case string matching `[a-z0-9_\-\.]`.
|
lower-case string matching `[a-z0-9_\-\.]`.
|
||||||
|
|
||||||
$ python setup.py install --installer=pkg-system
|
$ 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
|
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
|
`.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.
|
for the `name` metadata.
|
||||||
|
|
||||||
Notice that there should be at most one result. The first result founded
|
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.
|
- ``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
|
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.
|
`installation database` standard.
|
||||||
|
|
||||||
The new version of PEP 345 (XXX work in progress) will extend the Metadata
|
The new version of PEP 345 (XXX work in progress) extends the Metadata
|
||||||
standard and will fullfill the requirements described in PEP 262, like the
|
standard and fullfills the requirements described in PEP 262, like the
|
||||||
`REQUIRES` section.
|
`REQUIRES` section.
|
||||||
|
|
||||||
Adding an Uninstall function
|
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
|
is running the `install` command over the `setup.py` script of the
|
||||||
distribution.
|
distribution.
|
||||||
|
|
||||||
Distutils will provide a very basic ``uninstall`` function, that will be added
|
Distutils will provide a very basic ``uninstall`` function, that is added
|
||||||
in ``distutils.util`` and will take the name of the distribution to uninstall
|
in ``distutils.util`` and takes the name of the distribution to uninstall
|
||||||
as its argument. ``uninstall`` will use the APIs desribed earlier and remove all
|
as its argument. ``uninstall`` uses the APIs desribed earlier and remove all
|
||||||
unique files, as long as their hash didn't change. Then it will remove
|
unique files, as long as their hash didn't change. Then it removes empty
|
||||||
empty directories left behind.
|
directories left behind.
|
||||||
|
|
||||||
``uninstall`` will return a list of uninstalled files::
|
``uninstall`` returns a list of uninstalled files::
|
||||||
|
|
||||||
>>> from distutils.util import uninstall
|
>>> from distutils.util import uninstall
|
||||||
>>> uninstall('docutils')
|
>>> uninstall('docutils')
|
||||||
|
@ -477,15 +476,15 @@ empty directories left behind.
|
||||||
...
|
...
|
||||||
'/opt/local/lib/python2.6/site-packages/docutils/__init__.py']
|
'/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
|
Filtering
|
||||||
---------
|
---------
|
||||||
|
|
||||||
To make it a reference API for third-party projects that wish to control
|
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
|
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::
|
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
|
the ``uninstall`` function takes an extra argument ``installer`` which default
|
||||||
to ``distutils``.
|
to ``distutils``.
|
||||||
|
|
||||||
When called, ``uninstall`` will control that the ``INSTALLER`` file matches
|
When called, ``uninstall`` controls that the ``INSTALLER`` file matches
|
||||||
this argument. If not, it will raise a ``DistutilsUninstallError``::
|
this argument. If not, it raises a ``DistutilsUninstallError``::
|
||||||
|
|
||||||
>>> uninstall('docutils')
|
>>> uninstall('docutils')
|
||||||
Traceback (most recent call last):
|
Traceback (most recent call last):
|
||||||
|
@ -533,23 +532,22 @@ it has to undo at uninstallation time.
|
||||||
Adding an Uninstall script
|
Adding an Uninstall script
|
||||||
==========================
|
==========================
|
||||||
|
|
||||||
An `uninstall` script will be added in Distutils. and will be used
|
An `uninstall` script is added in Distutils. and is used like this::
|
||||||
like this::
|
|
||||||
|
|
||||||
$ python -m distutils.uninstall packagename
|
$ python -m distutils.uninstall packagename
|
||||||
|
|
||||||
Notice that script will not control if the removal of a distribution breaks
|
Notice that script doesn't control if the removal of a distribution breaks
|
||||||
another distribution. Although it will make sure that all the files it removes
|
another distribution. Although it makes sure that all the files it removes
|
||||||
are not used by any other distribution, by using the uninstall function.
|
are not used by any other distribution, by using the uninstall function.
|
||||||
|
|
||||||
|
|
||||||
Backward compatibility and roadmap
|
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.
|
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.
|
provided so people can benefit from these new features.
|
||||||
|
|
||||||
The plan is to integrate them for Python 2.7 and Python 3.2
|
The plan is to integrate them for Python 2.7 and Python 3.2
|
||||||
|
|
Loading…
Reference in New Issue