renamed APIs
This commit is contained in:
Tarek Ziadé
parent
4f2b209e23
commit
33aa877ff5
149
pep-0376.txt
149
pep-0376.txt
|
|
@ -156,7 +156,7 @@ The syntax of the egg-info directory name is as follows::
|
|||
name + '-' + version + '.egg-info'
|
||||
|
||||
The egg-info directory name is created using a new function called
|
||||
``egg_info_dirname(name, version)`` added to ``pkgutil``. ``name`` is
|
||||
``egginfo_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
|
||||
|
|
@ -166,13 +166,13 @@ filename-escaped form. Any '-' characters are currently replaced with '_'.
|
|||
|
||||
Examples::
|
||||
|
||||
>>> egg_info_dirname('zlib', '2.5.2')
|
||||
>>> egginfo_dirname('zlib', '2.5.2')
|
||||
'zlib-2.5.2.egg-info'
|
||||
|
||||
>>> egg_info_dirname('python-ldap', '2.5')
|
||||
>>> egginfo_dirname('python-ldap', '2.5')
|
||||
'python_ldap-2.5.egg-info'
|
||||
|
||||
>>> egg_info_dirname('python-ldap', '2.5 a---5')
|
||||
>>> egginfo_dirname('python-ldap', '2.5 a---5')
|
||||
'python_ldap-2.5.a_5.egg-info'
|
||||
|
||||
Adding a RECORD file in the .egg-info directory
|
||||
|
|
@ -271,24 +271,24 @@ 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`
|
||||
- ``Distribution``: manages an `.egg-info` directory.
|
||||
- ``DistributionDirectory``: manages a directory that contains some `.egg-info`
|
||||
directories.
|
||||
- ``EggInfoDirectories``: manages ``EggInfoDirectory`` instances.
|
||||
- ``DistributionDirectories``: manages ``EggInfoDirectory`` instances.
|
||||
|
||||
EggInfo class
|
||||
-------------
|
||||
Distribution class
|
||||
------------------
|
||||
|
||||
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.
|
||||
A new class called ``Distribution`` 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:
|
||||
``Distribution`` provides the following attributes:
|
||||
|
||||
- ``name``: The name of the project
|
||||
- ``name``: The name of the distribution.
|
||||
|
||||
- ``metadata``: A ``DistributionMetadata`` instance loaded with the project's
|
||||
PKG-INFO file
|
||||
- ``metadata``: A ``DistributionMetadata`` instance loaded with the
|
||||
distribution's PKG-INFO file.
|
||||
|
||||
And following methods:
|
||||
|
||||
|
|
@ -303,7 +303,7 @@ And following methods:
|
|||
Returns ``True`` if ``path`` is listed in `RECORD`. ``path``
|
||||
can be a local absolute path or a relative '/'-separated path.
|
||||
|
||||
- ``get_egg_info(path, binary=False)`` -> file object
|
||||
- ``get_egginfo_file(path, binary=False)`` -> file object
|
||||
|
||||
Returns a file located under the `.egg-info` directory.
|
||||
|
||||
|
|
@ -317,7 +317,7 @@ And following methods:
|
|||
|
||||
If ``binary`` is ``True``, opens the file in binary mode.
|
||||
|
||||
- ``get_egg_info_files(local=False)`` -> iterator of paths
|
||||
- ``get_egginfo_files(local=False)`` -> iterator of paths
|
||||
|
||||
Iterates over the `RECORD` entries and return paths for each line if the path
|
||||
is pointing a file located in the `.egg-info` directory or one of its
|
||||
|
|
@ -327,130 +327,119 @@ And following methods:
|
|||
local absolute path. Otherwise the raw value from `RECORD` is returned.
|
||||
|
||||
|
||||
EggInfoDirectory class
|
||||
----------------------
|
||||
DistributionDirectory 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``.
|
||||
A new class called ``DistributionDirectory`` 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 iterable, and returns every ``EggInfo`` instance created.
|
||||
The class is a ``set`` of ``Distribution`` instances. ``DistributionDirectory``
|
||||
provides a ``path`` attribute corresponding to the path is was created with.
|
||||
|
||||
It also provides two methods:
|
||||
It also provides two methods besides the ones from ``set``:
|
||||
|
||||
- ``file_users(path)`` -> Iterator of ``EggInfo``.
|
||||
- ``file_users(path)`` -> Iterator of ``Distribution``.
|
||||
|
||||
Returns all ``EggInfo`` which uses ``path``, by calling
|
||||
``EggInfo.uses(path)`` on all ``EggInfo`` instances.
|
||||
Returns all ``Distribution`` which uses ``path``, by calling
|
||||
``Distribution.uses(path)`` on all ``Distribution`` instances.
|
||||
|
||||
- ``owner(path)`` -> ``EggInfo`` instance or None
|
||||
- ``owner(path)`` -> ``Distribution`` instance or None
|
||||
|
||||
If ``path`` is used by only one ``EggInfo`` instance, returns it.
|
||||
If ``path`` is used by only one ``Distribution`` instance, returns it.
|
||||
Otherwise returns None.
|
||||
|
||||
EggInfoDirectories class
|
||||
-------------------------
|
||||
DistributionDirectories class
|
||||
-----------------------------
|
||||
|
||||
A new class called ``EggInfoDirectories`` is created. It's a collection of
|
||||
``EggInfoDirectory`` instances. The constructor takes one optional
|
||||
A new class called ``DistributionDirectories`` is created. It's a collection of
|
||||
``DistributionDirectory`` 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.
|
||||
``DistributionDirectories`` 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
|
||||
The cache is a global mapping containing ``DistributionDirectory`` instances.
|
||||
When an ``DistributionDirectories`` 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.
|
||||
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.
|
||||
The class is a ``dict`` where the values are ``DistributionDirectory``
|
||||
instances and the keys are their path attributes.
|
||||
|
||||
``EggInfoDirectories`` also provides the following container and helper
|
||||
methods:
|
||||
``EggInfoDirectories`` also provides the following methods besides the ones
|
||||
from ``dict``:
|
||||
|
||||
- ``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.
|
||||
Creates an ``DistributionDirectory`` instance for ``path`` and adds it
|
||||
in the mapping.
|
||||
|
||||
- ``load(paths)``
|
||||
|
||||
Creates and adds ``EggInfoDirectory`` instances corresponding to ``paths``.
|
||||
Creates and adds ``DistributionDirectory`` instances corresponding to
|
||||
``paths``.
|
||||
|
||||
- ``reload()``
|
||||
|
||||
Reloads existing entries.
|
||||
|
||||
- ``get_egg_infos()`` -> Iterator of ``EggInfo`` instances.
|
||||
- ``get_distributions()`` -> Iterator of ``Distribution`` instances.
|
||||
|
||||
Iterates over all ``EggInfo`` contained in ``EggInfoDirectory`` instances.
|
||||
Iterates over all ``Distribution`` contained in ``DistributionDirectory``
|
||||
instances.
|
||||
|
||||
- ``get_egg_info(project_name)`` -> ``EggInfo`` or None.
|
||||
- ``get_distribution(project_name)`` -> ``Distribution`` or None.
|
||||
|
||||
Returns an EggInfo instance for the given project name.
|
||||
Returns a ``Distribution`` instance for the given project name.
|
||||
If not found, returns None.
|
||||
|
||||
- ``get_file_users(path)`` -> Iterator of ``EggInfo`` instances.
|
||||
- ``get_file_users(path)`` -> Iterator of ``Distribution`` instances.
|
||||
|
||||
Iterates over all projects to find out which project uses the file.
|
||||
Returns ``EggInfo`` instances.
|
||||
Returns ``Distribution`` instances.
|
||||
|
||||
.egg-info functions
|
||||
-------------------
|
||||
|
||||
The new functions added in the ``pkgutil`` are :
|
||||
|
||||
- ``get_egg_infos(paths=sys.path)`` -> iterator
|
||||
- ``get_distributions()`` -> iterator of ``Distribution`` instance.
|
||||
|
||||
Provides an iterator that looks for ``.egg-info`` directories in ``sys.path``
|
||||
and returns ``EggInfo`` instances for each one of them.
|
||||
and returns ``Distribution`` instances for each one of them.
|
||||
|
||||
- ``get_egg_info(project_name, paths=sys.path)`` -> path or None
|
||||
- ``get_distribution(name)`` -> ``Distribution`` 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``
|
||||
directory that contains a PKG-INFO that matches `project_name` for the `name`
|
||||
``.egg-info``. Returns an ``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, paths=sys.path)`` -> iterator of ``EggInfo`` instances.
|
||||
- ``get_file_users(path)`` -> iterator of ``Distribution`` instances.
|
||||
|
||||
Iterates over all projects to find out which project uses ``path``.
|
||||
``path`` can be a local absolute path or a relative '/'-separated path.
|
||||
|
||||
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.
|
||||
All these functions use the same global instance of ``DistributionDirectories``to use the cache. Notice that the cache is never emptied explicitely.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
Let's use some of the new APIs with our `zlib` example::
|
||||
|
||||
>>> from pkgutil import get_egg_info, get_file_users
|
||||
>>> egg_info = get_egg_info('zlib')
|
||||
>>> egg_info.name
|
||||
>>> from pkgutil import get_distribution, get_file_users
|
||||
>>> dist = get_distribution('zlib')
|
||||
>>> dist.name
|
||||
'zlib'
|
||||
>>> egg_info.metadata.version
|
||||
>>> dist.metadata.version
|
||||
'2.5.2'
|
||||
|
||||
'/opt/local/lib/python2.6/site-packages/zlib-2.5.2.egg-info'
|
||||
>>> metadata = get_metadata('zlib')
|
||||
>>> metadata.version
|
||||
'2.5.2'
|
||||
|
||||
>>> for path, hash, size in egg_info.get_installed_files()::
|
||||
>>> for path, hash, size in dist.get_installed_files()::
|
||||
... print '%s %s %d %s' % (path, hash, size)
|
||||
...
|
||||
zlib/include/zconf.h b690274f621402dda63bf11ba5373bf2 9544
|
||||
|
|
@ -460,10 +449,10 @@ Let's use some of the new APIs with our `zlib` example::
|
|||
zlib-2.5.2.egg-info/PKG-INFO 6fe57de576d749536082d8e205b77748 195
|
||||
zlib-2.5.2.egg-info/RECORD None None
|
||||
|
||||
>>> egg_info.uses('zlib/include/zlib.h')
|
||||
>>> dist.uses('zlib/include/zlib.h')
|
||||
True
|
||||
|
||||
>>> egg_info.get_file('zlib/include/zlib.h')
|
||||
>>> dist.get_egginfo_file('PKG-INFO')
|
||||
<open file at ...>
|
||||
|
||||
PEP 262 replacement
|
||||
|
|
|
|||
Loading…
Reference in New Issue