[Python-checkins] r73753 - peps/trunk/pep-0376.txt
tarek.ziade
python-checkins at python.org
Thu Jul 2 12:13:24 CEST 2009
Author: tarek.ziade
Date: Thu Jul 2 12:13:23 2009
New Revision: 73753
Log:
removed the future tense usage when not required
Modified:
peps/trunk/pep-0376.txt
Modified: peps/trunk/pep-0376.txt
==============================================================================
--- peps/trunk/pep-0376.txt (original)
+++ peps/trunk/pep-0376.txt Thu Jul 2 12:13:23 2009
@@ -73,7 +73,7 @@
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 @@
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 @@
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 @@
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 @@
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 @@
- 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 @@
'/'-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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
...
'/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 @@
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 @@
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
More information about the Python-checkins
mailing list