Fixes from python-dev feedbacks
This commit is contained in:
Tarek Ziadé
parent
42da260c3c
commit
76059d2cbb
93
pep-0376.txt
93
pep-0376.txt
|
|
@ -24,15 +24,15 @@ This PEP proposes various enhancements for Distutils:
|
|||
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
|
||||
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 @@ See the Distutils [distutils]_ documentation for more information.
|
|||
|
||||
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 @@ Once installed, the elements are located in various places in the system, like:
|
|||
Rationale
|
||||
=========
|
||||
|
||||
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
|
||||
Python:
|
||||
|
||||
- There are too many ways to do it.
|
||||
|
|
@ -72,17 +72,18 @@ various subcommands.
|
|||
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
|
||||
`site-packages`::
|
||||
|
||||
- zlib
|
||||
- zlib-2.5.2-py2.4.egg-info
|
||||
- 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.
|
||||
|
||||
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 @@ install packages in the same way that Distutils does:
|
|||
|
||||
- `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`
|
||||
directory.
|
||||
|
||||
|
|
@ -105,11 +106,11 @@ Uninstall information
|
|||
---------------------
|
||||
|
||||
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
|
||||
Setuptools.
|
||||
|
||||
Under some circumstances, you might not be able to know for sure that you
|
||||
|
|
@ -157,11 +158,12 @@ Although 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.
|
||||
|
||||
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/
|
||||
PKG-INFO
|
||||
|
||||
The syntax of the egg-info directory name is as follows::
|
||||
|
|
@ -179,8 +181,8 @@ filename-escaped form. Any '-' characters are currently replaced with '_'.
|
|||
|
||||
Examples::
|
||||
|
||||
>>> egginfo_dirname('zlib', '2.5.2')
|
||||
'zlib-2.5.2.egg-info'
|
||||
>>> egginfo_dirname('docutils', '0.5')
|
||||
'docutils-0.5.egg-info'
|
||||
|
||||
>>> egginfo_dirname('python-ldap', '2.5')
|
||||
'python_ldap-2.5.egg-info'
|
||||
|
|
@ -213,13 +215,13 @@ the `excel` dialect, which uses these options to read the file:
|
|||
|
||||
- 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 @@ Each record is composed of three elements.
|
|||
'/'-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
|
||||
changed.
|
||||
|
||||
- the file's size in bytes
|
||||
|
||||
|
|
@ -236,6 +241,11 @@ The ``csv`` module with its default options 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``.
|
||||
|
||||
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
|
||||
terminator.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
|
|
@ -282,8 +292,8 @@ New APIs in pkgutil
|
|||
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
|
||||
[pep273]_.
|
||||
|
||||
- ``Distribution``: manages an `.egg-info` directory.
|
||||
|
|
@ -364,7 +374,7 @@ provides a ``path`` attribute corresponding to the path is was created with.
|
|||
|
||||
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 @@ attributes.
|
|||
``DistributionDirectories`` also provides the following methods besides the ones
|
||||
from ``dict``::
|
||||
|
||||
- ``append(path)``
|
||||
|
||||
Creates an ``DistributionDirectory`` (or ``ZippedDistributionDirectory``)
|
||||
instance for ``path`` and adds it in the mapping.
|
||||
|
||||
- ``load(paths)``
|
||||
- ``load(*paths)``
|
||||
|
||||
Creates and adds ``DistributionDirectory`` (or
|
||||
``ZippedDistributionDirectory``) instances corresponding to ``paths``.
|
||||
|
|
@ -466,7 +471,7 @@ The new functions added in the ``pkgutil`` are :
|
|||
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.
|
||||
|
||||
Example
|
||||
|
|
@ -482,7 +487,7 @@ Let's use some of the new APIs with our `zlib` example::
|
|||
'2.5.2'
|
||||
|
||||
>>> 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 @@ standard and will fullfill the requirements described in PEP 262, like the
|
|||
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
|
||||
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
|
||||
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 @@ References
|
|||
.. [#pep273]
|
||||
http://www.python.org/dev/peps/pep-0273
|
||||
|
||||
.. [#pep2738]
|
||||
http://www.python.org/dev/peps/pep-0278
|
||||
|
||||
|
||||
.. [distutils]
|
||||
http://docs.python.org/distutils
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue