[Python-checkins] r73516 - peps/trunk/pep-0376.txt
python-checkins at python.org
Tue Jun 23 10:50:11 CEST 2009
Date: Tue Jun 23 10:50:10 2009
New Revision: 73516
Fixes from python-dev feedbacks
--- peps/trunk/pep-0376.txt (original)
+++ peps/trunk/pep-0376.txt Tue Jun 23 10:50:10 2009
@@ -24,15 +24,15 @@
-A **distribution** is a collection of files, which can be Python modules,
-extensions or data. A distribution is managed by a special module called
+A **distribution** is a collection of files, which can be Python modules,
+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
+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
-for instance, to create a source distribution archive. An `install` command
+Disutils provides among other things **commands** that can be called
+through the shell using the `setup.py` script. A `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,7 +42,7 @@
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.
@@ -51,7 +51,7 @@
-There are two problems right now in the way distributions are installed in
+There are two problems right now in the way distributions are installed in
- There are too many ways to do it.
@@ -72,17 +72,18 @@
The `install_egg_info` subcommand is called during this process, in order to
create an `.egg-info` file in the `purelib` directory.
-For example, if the `zlib` distribution (which contains one package) is
-installed, two elements will be installed in `site-packages`::
+For example, for the `docutils` distribution, which contains one package an
+extra module and executable scripts, three elements will be installed in
+ - 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
+ as described in PEP 314 [#pep314]_. This file corresponds to the file
+ called `PKG-INFO`, built by the `sdist` command.
- - zlib
- - zlib-2.5.2-py2.4.egg-info
-Where `zlib` is a Python package, and `zlib-2.5.2-py2.4.egg-info` is
-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.
The problem is that many people use `easy_install` (setuptools [#setuptools]_)
or `pip` [#pip]_ to install their packages, and these third-party tools do not
@@ -90,7 +91,7 @@
- `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
+ 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`
@@ -105,11 +106,11 @@
Distutils doesn't provide any `uninstall` command. If you want to uninstall
-a distribution, you have to be a power user and remove the various elements
+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.
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
+distribution, and if the distribution's `setup.py` uses Distutils or
Under some circumstances, you might not be able to know for sure that you
@@ -157,11 +158,12 @@
the fact that they already work with a directory that contains a `PKG-INFO`
file, the change will have no deep consequences.
-For example, if the `zlib` package is installed, the elements that
+For example, if the `docutils` package is installed, the elements that
will be installed in `site-packages` will become::
- - zlib
- - zlib-2.5.2.egg-info/
+ - docutils
+ - roman.py
+ - docutils-0.5-py2.6.egg-info/
The syntax of the egg-info directory name is as follows::
@@ -179,8 +181,8 @@
- >>> egginfo_dirname('zlib', '2.5.2')
+ >>> egginfo_dirname('docutils', '0.5')
>>> egginfo_dirname('python-ldap', '2.5')
@@ -213,13 +215,13 @@
- field delimiter : `,`
- quoting char : `"`.
-- line terminator : `\r\n`
+- line terminator : ``os.linesep`` (so `\r\n` or `\r`)
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
+ - 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
cross-compatible and allows simple installation to be relocatable.
@@ -228,7 +230,10 @@
'/'-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.
+ generated files will not have a 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
- the file's size in bytes
@@ -236,6 +241,11 @@
so the field separator will be ",". Any "," characters found within a field
will be 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
+reading a file produced on a platform that uses a different new line
@@ -282,8 +292,8 @@
To use the `.egg-info` directory content, we need to add in the standard
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
+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
- ``Distribution``: manages an `.egg-info` directory.
@@ -364,7 +374,7 @@
It also provides two methods besides the ones from ``set``:
-- ``file_users(path)`` -> Iterator of ``Distribution``.
+- ``get_file_users(path)`` -> Iterator of ``Distribution``.
Returns all ``Distribution`` which uses ``path``, by calling
``Distribution.uses(path)`` on all ``Distribution`` instances.
@@ -405,12 +415,7 @@
``DistributionDirectories`` also provides the following methods besides the ones
- Creates an ``DistributionDirectory`` (or ``ZippedDistributionDirectory``)
- instance for ``path`` and adds it in the mapping.
Creates and adds ``DistributionDirectory`` (or
``ZippedDistributionDirectory``) instances corresponding to ``paths``.
@@ -466,7 +471,7 @@
Iterates over all distributions to find out which distributions uses ``path``.
``path`` can be a local absolute path or a relative '/'-separated path.
-All these functions use the same global instance of ``DistributionDirectories``
+All these functions use the same global instance of ``DistributionDirectories``
to use the cache. Notice that the cache is never emptied explicitely.
@@ -482,7 +487,7 @@
>>> for path, hash, size in dist.get_installed_files()::
- ... print '%s %s %d %s' % (path, hash, size)
+ ... print '%s %s %d' % (path, hash, size)
zlib/include/zconf.h b690274f621402dda63bf11ba5373bf2 9544
zlib/include/zlib.h 9c4b84aff68aa55f2e9bf70481b94333 66188
@@ -520,12 +525,12 @@
Adding an Uninstall function
-Distutils already provides a very basic way to install a distribution, which
-is running the `install` command over the `setup.py` script of the
+Distutils already provides a very basic way to install a distribution, which
+is running the `install` command over the `setup.py` script of the
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
+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.
@@ -622,6 +627,10 @@
More information about the Python-checkins