removed the future tense usage when not required

This commit is contained in:
Tarek Ziadé 2009-07-02 10:13:23 +00:00
parent d6a6a966c3
commit b279051076
1 changed files with 44 additions and 46 deletions

View File

@ -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