diff --git a/pep-0376.txt b/pep-0376.txt index 1a54bf647..4e55a984f 100644 --- a/pep-0376.txt +++ b/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 ==============