[Python-checkins] r73752 - peps/trunk/pep-0376.txt
tarek.ziade
python-checkins at python.org
Thu Jul 2 11:46:05 CEST 2009
Author: tarek.ziade
Date: Thu Jul 2 11:46:04 2009
New Revision: 73752
Log:
removed implementation details from the PEP. A reference is kept
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 11:46:04 2009
@@ -85,29 +85,30 @@
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 @@
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 @@
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]_.
-
-- ``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.
+Query functions
+---------------
+
+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 @@
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.
-
-``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
+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]_.
- 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 @@
.. [#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 @@
.. [#debian]
http://wiki.debian.org/DebianPython/NewPolicy
+.. [#prototype]
+ http://bitbucket.org/tarek/pep376/
+
Aknowledgments
==============
More information about the Python-checkins
mailing list