removed implementation details from the PEP. A reference is kept
This commit is contained in:
Tarek Ziadé
parent
fc1b7137b8
commit
d6a6a966c3
213
pep-0376.txt
213
pep-0376.txt
|
|
@ -85,29 +85,30 @@ extra module and executable scripts, three elements will be installed in
|
|||
Some executable scripts, such as `rst2html.py`, will also be added in the
|
||||
`bin` directory of the Python installation.
|
||||
|
||||
Another project called `setuptools` [#setuptools]_ has introduced two new
|
||||
formats to install distributions:
|
||||
Another project called `setuptools` [#setuptools]_ has two other formats
|
||||
to install distributions, called `EggFormats` [#eggformats]_:
|
||||
|
||||
- a self-contained `.egg` directory, that contains all the distribution files
|
||||
and the distribution metadata in a file called `PKG-INFO` in a subdirectory
|
||||
called `EGG-INFO`. Other files are created in that directory for
|
||||
`setuptools` needs.
|
||||
called `EGG-INFO`. `setuptools` creates other fils in that directory that can
|
||||
be considered as complementary metadata.
|
||||
|
||||
- a `.egg-info` directory installed in `site-packages`, that contains the same
|
||||
files `EGG-INFO` has in the `.egg` format.
|
||||
|
||||
The first format is automatically used when you install a distribution that
|
||||
uses ``setuptools.setup`` function in its setup.py file, instead of
|
||||
``distutils.core.setup``.
|
||||
uses the ``setuptools.setup`` function in its setup.py file, instead of
|
||||
the ``distutils.core.setup`` one.
|
||||
|
||||
The `setuptools` project also provides an executable script called
|
||||
`easy_install` that will install all istributions, including distutils-based
|
||||
ones in self-contained `.egg` directories.
|
||||
`easy_install` [#easyinstall]_ that will install all distributions, including
|
||||
distutils-based ones in self-contained `.egg` directories.
|
||||
|
||||
If you want to have a standalone `.egg.info` directory with setuptools-based
|
||||
distributions, e.g. the second `setuptools` format, you have to force it
|
||||
using the `-–single-version-externally-managed` option **or** the `--root`
|
||||
option.
|
||||
If you want to have a standalone `.egg.info` directory distributions, e.g.
|
||||
the second `setuptools` format, you have to force it when you work
|
||||
with a setuptools-based distribution or with the `easy_install` script.
|
||||
You can force it by using the `-–single-version-externally-managed` option
|
||||
**or** the `--root` option.
|
||||
|
||||
This option is used by :
|
||||
|
||||
|
|
@ -140,8 +141,8 @@ 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
|
||||
the `EggFormats` standard from `setuptools` [#eggformats]_.
|
||||
- A new `.egg-info` structure using a directory, based on one format of
|
||||
the `EggFormats` standard from `setuptools`.
|
||||
- New APIs in `pkgutil` to be able to query the information of installed
|
||||
distributions.
|
||||
- A de-facto replacement for PEP 262
|
||||
|
|
@ -314,18 +315,31 @@ 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 is `pkgutil`.
|
||||
|
||||
The API is organized in five classes that work with directories and Zip files
|
||||
(so it works with files included in Zip files, see PEP 273 for more details
|
||||
[#pep273]_.
|
||||
Query functions
|
||||
---------------
|
||||
|
||||
- ``Distribution``: manages an `.egg-info` directory.
|
||||
- ``ZippedDistribution``: manages an `.egg-info` directory contained in a zip
|
||||
file.
|
||||
- ``DistributionDir``: manages a directory that contains some `.egg-info`
|
||||
directories.
|
||||
- ``ZippedDistributionDir``: manages a zipped directory that contains
|
||||
some `.egg.info` directory.
|
||||
- ``DistributionDirMap``: manages ``DistributionDir`` instances.
|
||||
The new functions added in the ``pkgutil`` are :
|
||||
|
||||
- ``get_distributions()`` -> iterator of ``Distribution`` instances.
|
||||
|
||||
Provides an iterator that looks for ``.egg-info`` directories in
|
||||
``sys.path`` and returns ``Distribution`` instances for
|
||||
each one of them.
|
||||
|
||||
- ``get_distribution(name)`` -> ``Distribution`` or None.
|
||||
|
||||
Scans all elements in ``sys.path`` and looks for all directories ending with
|
||||
``.egg-info``. Returns a ``Distribution`` corresponding to the
|
||||
``.egg-info`` directory that contains a PKG-INFO that matches `name`
|
||||
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.
|
||||
|
||||
- ``get_file_users(path)`` -> iterator of ``Distribution`` instances.
|
||||
|
||||
Iterates over all distributions to find out which distributions uses ``path``.
|
||||
``path`` can be a local absolute path or a relative '/'-separated path.
|
||||
|
||||
Distribution class
|
||||
------------------
|
||||
|
|
@ -385,145 +399,14 @@ And following methods:
|
|||
If ``local`` is ``True``, each path is transformed into a
|
||||
local absolute path. Otherwise the raw value from `RECORD` is returned.
|
||||
|
||||
ZippedDistribution class
|
||||
------------------------
|
||||
|
||||
A ``ZippedDistribution`` class is provided. It overrides the ``Distribution``
|
||||
class so its methods work with an `.egg.info` directory located in a zip file.
|
||||
Notice that the API is organized in five classes that work with directories
|
||||
and Zip files (so it works with files included in Zip files, see PEP 273 for
|
||||
more details [#pep273]_). These classes are described in the documentation
|
||||
of the prototype implementation for interested readers [#prototype]_.
|
||||
|
||||
``ZippedDistribution(zipfile, path)`` -> instance
|
||||
|
||||
Creates a ``ZippedDistribution`` instance for the given relative ``path``
|
||||
located in the ``zipfile`` file.
|
||||
|
||||
Other public methods and attributes are similar to ``Distribution``.
|
||||
|
||||
DistributionDir class
|
||||
---------------------
|
||||
|
||||
A new class called ``DistributionDir`` is created with a path
|
||||
corresponding to a directory. For each `.egg-info` directory founded in
|
||||
`path`, the class creates a corresponding ``Distribution``.
|
||||
|
||||
The class is a ``set`` of ``Distribution`` instances. ``DistributionDir``
|
||||
provides a ``path`` attribute corresponding to the path is was created with.
|
||||
|
||||
``DistributionDir(path)`` -> instance
|
||||
|
||||
Creates a ``DistributionDir`` instance for the given ``path``.
|
||||
|
||||
It also provides one extra method besides the ones from ``set``:
|
||||
|
||||
- ``get_file_users(path)`` -> Iterator of ``Distribution``.
|
||||
|
||||
Returns all ``Distribution`` which uses ``path``, by calling
|
||||
``Distribution.uses(path)`` on all ``Distribution`` instances.
|
||||
|
||||
|
||||
ZippedDistributionDir class
|
||||
---------------------------
|
||||
|
||||
A ``ZippedDistributionDir`` is provided. It overrides the
|
||||
``DistributionDir`` class so its methods work with a Zip file.
|
||||
|
||||
``ZippedDistributionDir(path)`` -> instance
|
||||
|
||||
Creates a ``ZippedDistributionDir`` instance for the given ``path``.
|
||||
|
||||
Other public methods and attributes are similar to ``DistributionDir``.
|
||||
|
||||
|
||||
DistributionDirMap class
|
||||
------------------------
|
||||
|
||||
A new class called ``DistributionDirMap`` is created. It's a collection of
|
||||
``DistributionDir`` and ``ZippedDistributionDir`` instances.
|
||||
|
||||
``DistributionDirMap(paths=None, use_cache=True)`` -> instance
|
||||
|
||||
If ``paths`` is not not, it's a sequence of paths the constructor loads
|
||||
in the instance.
|
||||
|
||||
The constructor also takes an optional ``use_cache`` argument.
|
||||
When it's ``True``, ``DistributionDirMap`` will use a global
|
||||
cache to reduce the numbers of I/O accesses and speed up the lookups.
|
||||
|
||||
The cache is a global mapping containing ``DistributionDir`` and
|
||||
``ZippedDistributionDir`` instances. When a
|
||||
``DistributionDirMap`` object is created, it will use the cache to
|
||||
add an entry for each path it visits, or reuse existing entries. The
|
||||
cache usage can be disabled at any time with the ``use_cache`` attribute.
|
||||
|
||||
The cache can also be emptied with the global ``purge_cache`` function.
|
||||
|
||||
The class is a ``dict`` where the values are ``DistributionDir``
|
||||
and ``ZippedDistributionDir`` instances and the keys are their path
|
||||
attributes.
|
||||
|
||||
``DistributionDirMap`` also provides the following methods besides the ones
|
||||
from ``dict``:
|
||||
|
||||
- ``load(*paths)``
|
||||
|
||||
Creates and adds ``DistributionDir`` (or
|
||||
``ZippedDistributionDir``) instances corresponding to ``paths``.
|
||||
|
||||
- ``reload()``
|
||||
|
||||
Reloads existing entries.
|
||||
|
||||
- ``get_distributions()`` -> Iterator of ``Distribution`` (or
|
||||
``ZippedDistribution``) instances.
|
||||
|
||||
Iterates over all ``Distribution`` and ``ZippedDistribution`` contained
|
||||
in ``DistributionDir`` and ``ZippedDistributionDir`` instances.
|
||||
|
||||
- ``get_distribution(dist_name)`` -> ``Distribution`` (or
|
||||
``ZippedDistribution``) or None.
|
||||
|
||||
Returns a ``Distribution`` (or ``ZippedDistribution``) instance for the
|
||||
given distribution name. If not found, returns None.
|
||||
|
||||
- ``get_file_users(path)`` -> Iterator of ``Distribution`` (or
|
||||
``ZippedDistribution``) instances.
|
||||
|
||||
Iterates over all distributions to find out which distributions use the file.
|
||||
Returns ``Distribution`` (or ``ZippedDistribution``) instances.
|
||||
|
||||
.egg-info functions
|
||||
-------------------
|
||||
|
||||
The new functions added in the ``pkgutil`` are :
|
||||
|
||||
- ``get_distributions()`` -> iterator of ``Distribution`` (or
|
||||
``ZippedDistribution``) instance.
|
||||
|
||||
Provides an iterator that looks for ``.egg-info`` directories in ``sys.path``
|
||||
and returns ``Distribution`` (or ``ZippedDistribution``) instances for
|
||||
each one of them.
|
||||
|
||||
- ``get_distribution(name)`` -> ``Distribution`` (or ``ZippedDistribution``)
|
||||
or None.
|
||||
|
||||
Scans all elements in ``sys.path`` and looks for all directories ending with
|
||||
``.egg-info``. Returns a ``Distribution`` (or ``ZippedDistribution``)
|
||||
corresponding to the ``.egg-info`` directory that contains a PKG-INFO that
|
||||
matches `name` 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.
|
||||
|
||||
- ``get_file_users(path)`` -> iterator of ``Distribution`` (or
|
||||
``ZippedDistribution``) instances.
|
||||
|
||||
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 ``DistributionDirMap``
|
||||
to use the cache. Notice that the cache is never emptied explicitely.
|
||||
|
||||
Example
|
||||
-------
|
||||
Usage example
|
||||
-------------
|
||||
|
||||
Let's use some of the new APIs with our `docutils` example::
|
||||
|
||||
|
|
@ -687,6 +570,9 @@ References
|
|||
.. [#setuptools]
|
||||
http://peak.telecommunity.com/DevCenter/setuptools
|
||||
|
||||
.. [#easyinstall]
|
||||
http://peak.telecommunity.com/DevCenter/EasyInstall
|
||||
|
||||
.. [#pip]
|
||||
http://pypi.python.org/pypi/pip
|
||||
|
||||
|
|
@ -705,6 +591,9 @@ References
|
|||
.. [#debian]
|
||||
http://wiki.debian.org/DebianPython/NewPolicy
|
||||
|
||||
.. [#prototype]
|
||||
http://bitbucket.org/tarek/pep376/
|
||||
|
||||
Aknowledgments
|
||||
==============
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue