[Python-checkins] r73553 - peps/trunk/pep-0376.txt
tarek.ziade
python-checkins at python.org
Thu Jun 25 11:43:46 CEST 2009
Author: tarek.ziade
Date: Thu Jun 25 11:43:46 2009
New Revision: 73553
Log:
fixed english, thanks to brodie and vrialland
Modified:
peps/trunk/pep-0376.txt
Modified: peps/trunk/pep-0376.txt
==============================================================================
--- peps/trunk/pep-0376.txt (original)
+++ peps/trunk/pep-0376.txt Thu Jun 25 11:43:46 2009
@@ -17,21 +17,21 @@
This PEP proposes various enhancements for Distutils:
- A new format for the .egg-info structure.
-- Some APIs to read the meta-data of a distribution
-- A replacement PEP 262
-- An uninstall feature
+- Some APIs to read the meta-data of a distribution.
+- A replacement PEP 262.
+- An uninstall feature.
Definitions
===========
A **distribution** is a collection of files, which can be Python modules,
-extensions or data. A distribution is managed by a special module called
+extensions, or data. A distribution is managed by a special module called
`setup.py` which contains a call to the `distutils.core.setup` function.
The arguments passed to that function describe the distribution, like
its `name`, its `version`, and so on.
-Disutils provides among other things **commands** that can be called
-through the shell using the `setup.py` script. A `sdist` command is provided
+Disutils provides, among other things, **commands** that can be called
+through the shell using the `setup.py` script. An `sdist` command is provided
for instance to create a source distribution archive. An `install` command
is also provided to perform an installation of the distribution in the Python
installation the script is invoked with::
@@ -42,11 +42,11 @@
Once installed, the elements are located in various places in the system, like:
-- in Python's site-packages (Python modules, Python modules organized into
+- In Python's site-packages (Python modules, Python modules organized into
packages, Extensions, etc.)
-- in Python's `include` directory.
-- in Python's `bin` or `Script` directory.
-- etc.
+- In Python's `include` directory.
+- In Python's `bin` or `Script` directory.
+- Etc.
Rationale
=========
@@ -60,79 +60,80 @@
How distributions are installed
-------------------------------
-Right now, when a distribution is installed in Python, every elements its contains
-is installed in various directories.
+Right now, when a distribution is installed in Python, every element it
+contains is installed in various directories.
-The pure Python code for instance is installed in the `purelib` directory,
-which is located in the Python installation in ``lib\python2.6\site-packages``
-for example under unix-like systems or Mac OS X, and in ``Lib/site-packages``
+The pure Python code, for instance, is installed in the `purelib` directory
+which is located in the Python installation at ``lib\python2.6\site-packages``
+for example under Unix-like systems or Mac OS X, and in ``Lib/site-packages``
under Windows. This is done with the Distutils `install` command, which calls
various subcommands.
-The `install_egg_info` subcommand is called during this process, in order to
+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
`site-packages`:
-- `docutils` : the ``docutils`` pakage
-- `roman.py` : an extra module used by `docutils`
-- `docutils-0.5-py2.6.egg-info` : a file containing the distribution metadata
+- `docutils`: The ``docutils`` package.
+- `roman.py`: An extra module used by `docutils`.
+- `docutils-0.5-py2.6.egg-info`: A file containing the distribution metadata
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 `bin`
-directory of the Python installation.
+Some executable scripts, such as `rst2html.py`, will also be added in the
+`bin` directory of the Python installation.
The problem is that many people use `easy_install` (from the `setuptools`
project [#setuptools]_) or `pip` [#pip]_ to install their packages, and
these third-party tools do not install packages in the same way that Distutils
does:
-- `easy_install` creates an `EGG-INFO` directory inside an `.egg` directory,
+- `easy_install` creates an `EGG-INFO` directory inside an `.egg` directory
and adds a `PKG-INFO` file inside this directory. The `.egg` directory
- contains in that case all the elements of the distribution that are supposed
- to be installed in `site-packages`, and is placed in the `site-packages`
+ contains all the elements of the distribution that are supposed to be
+ installed in `site-packages` and is placed in the `site-packages`
directory.
- `pip` creates an `.egg-info` directory inside the `site-packages` directory
and adds a `PKG-INFO` file inside it. Elements of the distribution are then
installed in various places like Distutils does.
-They both add other files in the `EGG-INFO` or `.egg-info` directory, and
+They both add other files in the `EGG-INFO` or `.egg-info` directory and
create or modify `.pth` files.
Uninstall information
---------------------
-Distutils doesn't provide any `uninstall` command. If you want to uninstall
+Distutils doesn't provide an `uninstall` command. If you want to uninstall
a distribution, you have to be a power user and remove the various elements
-that were installed. Then look over the `.pth` file to clean them if necessary.
+that were installed, and then look over the `.pth` file to clean them if
+necessary.
-And the process differs, depending on the tools you have used to install the
-distribution, and if the distribution's `setup.py` uses Distutils or
+And the process differs depending on the tools you have used to install the
+distribution and if the distribution's `setup.py` uses Distutils or
Setuptools.
Under some circumstances, you might not be able to know for sure that you
have removed everything, or that you didn't break another distribution by
removing a file that is shared among several distributions.
-But there's common behavior: when you install a distribution, files are copied
-in your system. And there's a way to keep track of theses files, so to remove
-them.
+But there's a common behavior: when you install a distribution, files are
+copied in your system. And it's possible to keep track of these files for
+later removal.
What this PEP proposes
----------------------
To address those issues, this PEP proposes a few changes:
-- a new `.egg-info` structure using a directory, based on one form of
+- A new `.egg-info` structure using a directory, based on one form of
the `EggFormats` standard from `setuptools` [#eggformats]_.
-- new APIs in `pkgutil` to be able to query the information of installed
+- New APIs in `pkgutil` to be able to query the information of installed
distributions.
-- a de-facto replacement for PEP 262
-- an uninstall function in Distutils.
+- A de-facto replacement for PEP 262
+- An uninstall function in Distutils.
.egg-info becomes a directory
@@ -142,20 +143,20 @@
hold the `PKG-INFO` file built by the `write_pkg_file` method of
the `Distribution` class in Distutils.
-Notice that this change is based on the standard proposed by `EggFormats`.
-Although, this standard proposes two ways to install files :
+Notice that this change is based on the standard proposed by `EggFormats`,
+although this standard proposes two ways to install files:
-- a self-contained directory that can be zipped or left unzipped and that
- contains the distribution files *and* the `.egg-info` directory.
+- A self-contained directory that can be zipped or left unzipped and contains
+ the distribution files *and* the `.egg-info` directory.
-- a distinct `.egg-info` directory located in the site-packages directory.
+- A distinct `.egg-info` directory located in the site-packages directory.
You may refer to the `EggFormats` documentation for more details.
-This change will not impact Python itself, because `egg-info` files are not
+This change will not impact Python itself because `egg-info` files are not
used anywhere yet in the standard library besides Distutils.
-Although it will impact the `setuptools` and `pip` projects, but given
+However, it will 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.
@@ -224,7 +225,7 @@
- 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
- path, no matter what is the target system. This makes this information
+ path, no matter what the target system is. This makes this information
cross-compatible and allows simple installation to be relocatable.
- if the installed file is located elsewhere in the system, a
@@ -295,7 +296,7 @@
library a set of APIs. The best place to put these APIs seems to be `pkgutil`.
The API is organized in five classes that work with directories and Zip files
-(so its works with files included in Zip files, see PEP 273 for more details
+(so it works with files included in Zip files, see PEP 273 for more details
[#pep273]_.
- ``Distribution``: manages an `.egg-info` directory.
More information about the Python-checkins
mailing list