reflecting the last API discussions in the SIG
This commit is contained in:
Tarek Ziadé
parent
a259ff3c13
commit
31d3b9ed8a
141
pep-0376.txt
141
pep-0376.txt
|
|
@ -115,7 +115,7 @@ To address those issues, this PEP proposes a few changes:
|
|||
- a new `.egg-info` structure using a directory, based on the `EggFormats`
|
||||
standard from `setuptools` [#eggformats]_.
|
||||
- new APIs in `pkgutil` to be able to query the information of installed
|
||||
projects.
|
||||
projects.
|
||||
- a de-facto replacement for PEP 262
|
||||
- an uninstall function in Distutils.
|
||||
|
||||
|
|
@ -151,10 +151,10 @@ The syntax of the egg-info directory name is as follows::
|
|||
The egg-info directory name is created using a new function called
|
||||
``egg_info_dirname(name, version)`` added to ``pkgutil``. ``name`` is
|
||||
converted to a standard distribution name any runs of non-alphanumeric
|
||||
characters are replaced with a single '-'. ``version`` is converted
|
||||
to a standard version string. Spaces become dots, and all other
|
||||
non-alphanumeric characters become dashes, with runs of multiple dashes
|
||||
condensed to a single dash. Both attributes are then converted into their
|
||||
characters are replaced with a single '-'. ``version`` is converted
|
||||
to a standard version string. Spaces become dots, and all other
|
||||
non-alphanumeric characters become dashes, with runs of multiple dashes
|
||||
condensed to a single dash. Both attributes are then converted into their
|
||||
filename-escaped form. Any '-' characters are currently replaced with '_'.
|
||||
|
||||
Examples::
|
||||
|
|
@ -233,23 +233,33 @@ 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 three classes:
|
||||
|
||||
- ``EggInfo``: manages an `.egg-info` directory.
|
||||
- ``EggInfoDirectory``: manages a directory that contains some `.egg-info`
|
||||
directories.
|
||||
- ``EggInfoDirectories``: manages ``EggInfoDirectory`` instances.
|
||||
|
||||
EggInfo class
|
||||
-------------
|
||||
|
||||
A new class called ``EggInfo`` is created, which provides the following
|
||||
attributes:
|
||||
A new class called ``EggInfo`` is created with a the path of the `.egg-info`
|
||||
directory provided to the contructor. It reads the metadata contained in
|
||||
`PKG-INFO` when it is instanciated.
|
||||
|
||||
``EggInfo`` provides the following attributes:
|
||||
|
||||
- ``name``: The name of the project
|
||||
|
||||
- ``metadata``: A ``DistributionMetadata`` instance loaded with the project's
|
||||
PKG-INFO file
|
||||
|
||||
The following methods are provided:
|
||||
And following methods:
|
||||
|
||||
- ``get_installed_files(local=False)`` -> iterator of (path, md5, size)
|
||||
|
||||
Iterates over the `RECORD` entries and return a tuple ``(path, md5, size)``
|
||||
for each line. If ``local`` is ``True``, the path is transformed into a
|
||||
Iterates over the `RECORD` entries and return a tuple ``(path, md5, size)``
|
||||
for each line. If ``local`` is ``True``, the path is transformed into a
|
||||
local absolute path. Otherwise the raw value from `RECORD` is returned.
|
||||
|
||||
- ``uses(path)`` -> Boolean
|
||||
|
|
@ -257,30 +267,100 @@ The following methods are provided:
|
|||
Returns ``True`` if ``path`` is listed in `RECORD`. ``path``
|
||||
can be a local absolute path or a relative '/'-separated path.
|
||||
|
||||
- ``owns(path)`` -> Boolean
|
||||
|
||||
Returns ``True`` if ``path`` is owned by the project.
|
||||
Owned means that the path is used only by this project and is not used
|
||||
by any other project. ``path`` can be a local absolute path or a relative
|
||||
'/'-separated path.
|
||||
|
||||
- ``get_file(path, binary=False)`` -> file object
|
||||
|
||||
Returns a ``file`` instance for the file pointed by ``path``. ``path`` can be
|
||||
a local absolute path or a relative '/'-separated path. If ``binary`` is
|
||||
Returns a ``file`` instance for the file pointed by ``path``. ``path`` can be
|
||||
a local absolute path or a relative '/'-separated path. If ``binary`` is
|
||||
``True``, opens the file in binary mode.
|
||||
|
||||
EggInfoDirectory class
|
||||
----------------------
|
||||
|
||||
A new class called ``EggInfoDirectory`` is created with a path corresponding
|
||||
to a directory. For each `.egg-info` directory founded in `path`, the class
|
||||
creates a corresponding ``EggInfo``.
|
||||
|
||||
The class is iterable, and returns every ``EggInfo`` instance created.
|
||||
|
||||
It also provides two methods:
|
||||
|
||||
- ``file_users(path)`` -> Iterator of ``EggInfo``.
|
||||
|
||||
Returns all ``EggInfo`` which uses ``path``, by calling
|
||||
``EggInfo.uses(path)`` on all ``EggInfo`` instances.
|
||||
|
||||
- ``owner(path)`` -> ``EggInfo`` instance or None
|
||||
|
||||
If ``path`` is used by only one ``EggInfo`` instance, returns it.
|
||||
Otherwise returns None.
|
||||
|
||||
EggInfoDirectories class
|
||||
-------------------------
|
||||
|
||||
A new class called ``EggInfoDirectories`` is created. It's a collection of
|
||||
``EggInfoDirectory`` instances. The constructor takes one optional
|
||||
argument ``use_cache`` set to ``True`` by default. When ``True``,
|
||||
``EggInfoDirectories`` 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 ``EggInfoDirectory`` instances.
|
||||
When an ``EggInfoDirectories`` 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 iterable, and returns every ``EggInfo`` instance from every
|
||||
``EggInfoDirectory`` instance it contains.
|
||||
|
||||
``EggInfoDirectories`` also provides the following container and helper
|
||||
methods:
|
||||
|
||||
- ``append(path)``
|
||||
|
||||
Creates an ``EggInfoDirectory`` instance. for ``path`` appends it.
|
||||
|
||||
- ``remove(egg_info_dir)``
|
||||
|
||||
Removes the ``EggInfoDirectory`` instance for the given ``path``.
|
||||
|
||||
- ``clear()``
|
||||
|
||||
Removes all elements.
|
||||
|
||||
- ``load(paths)``
|
||||
|
||||
Creates and adds ``EggInfoDirectory`` instances corresponding to ``paths``.
|
||||
|
||||
- ``reload()``
|
||||
|
||||
Reloads existing entries.
|
||||
|
||||
- ``get_egg_infos()`` -> Iterator of ``EggInfo`` instances.
|
||||
|
||||
Iterates over all ``EggInfo`` contained in ``EggInfoDirectory`` instances.
|
||||
|
||||
- ``get_egg_info(project_name)`` -> ``EggInfo`` or None.
|
||||
|
||||
Returns an EggInfo instance for the given project name.
|
||||
If not found, returns None.
|
||||
|
||||
- ``get_file_users(path)`` -> Iterator of ``EggInfo`` instances.
|
||||
|
||||
Iterates over all projects to find out which project uses the file.
|
||||
Returns ``EggInfo`` instances.
|
||||
|
||||
.egg-info functions
|
||||
-------------------
|
||||
|
||||
The new functions added in the ``pkgutil`` are :
|
||||
|
||||
- ``get_egg_infos()`` -> iterator
|
||||
- ``get_egg_infos(paths=sys.path)`` -> iterator
|
||||
|
||||
Provides an iterator that looks for ``.egg-info`` directories in ``sys.path``
|
||||
and returns ``EggInfo`` instances for each one of them.
|
||||
|
||||
- ``get_egg_info(project_name)`` -> path or None
|
||||
- ``get_egg_info(project_name, paths=sys.path)`` -> path or None
|
||||
|
||||
Scans all elements in ``sys.path`` and looks for all directories ending with
|
||||
``.egg-info``. Returns an ``EggInfo`` corresponding to the ``.egg-info``
|
||||
|
|
@ -290,23 +370,14 @@ The new functions added in the ``pkgutil`` are :
|
|||
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 ``EggInfo`` instances.
|
||||
- ``get_file_users(path, paths=sys.path)`` -> iterator of ``EggInfo`` instances.
|
||||
|
||||
Iterates over all projects to find out which project uses ``path``.
|
||||
``path`` can be a local absolute path or a relative '/'-separated path.
|
||||
|
||||
Cache functions
|
||||
---------------
|
||||
|
||||
The functions from the previous section work with a global memory cache to
|
||||
reduce the numbers of I/O accesses and speed up the lookups.
|
||||
|
||||
The cache can be managed with these functions:
|
||||
|
||||
- ``purge_cache``: removes all entries from cache.
|
||||
- ``cache_enabled``: returns ``True`` if the cache is enabled.
|
||||
- ``enable_cache``: enables the cache.
|
||||
- ``disable_cache``: disables the cache.
|
||||
All these functions use the same global instance of ``EggInfoDirectories`` to
|
||||
use the cache. Notice that the cache is never emptied explicitely so it keeps
|
||||
on growing everytime it is used with new paths.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
|
@ -337,8 +408,6 @@ Let's use some of the new APIs with our `zlib` example::
|
|||
|
||||
>>> egg_info.uses('zlib/include/zlib.h')
|
||||
True
|
||||
>>> egg_info.owns('zlib/include/zlib.h')
|
||||
True
|
||||
|
||||
>>> egg_info.get_file('zlib/include/zlib.h')
|
||||
<open file at ...>
|
||||
|
|
|
|||
Loading…
Reference in New Issue