renamed APIs
This commit is contained in:
Tarek Ziadé
parent
4f2b209e23
commit
33aa877ff5
169
pep-0376.txt
169
pep-0376.txt
|
|
@ -24,7 +24,7 @@ This PEP proposes various enhancements for Distutils:
|
|||
Definitions
|
||||
===========
|
||||
|
||||
A **project** is a distribution of one or several files, which can be Python
|
||||
A **project** is a distribution of one or several files, which can be Python
|
||||
modules, extensions or data. It is distributed using a `setup.py` script
|
||||
with Distutils and/or Setuptools. The `setup.py` script indicates where each
|
||||
elements should be installed.
|
||||
|
|
@ -130,7 +130,7 @@ the `Distribution` class in Distutils.
|
|||
Notice that this change is based on the standard proposed by `EggFormats`.
|
||||
Although, this standard proposes two ways to install files :
|
||||
|
||||
- a self-contained directory that can be zipped or left unzipped and that
|
||||
- a self-contained directory that can be zipped or left unzipped and that
|
||||
contains the project files *and* the `.egg-info` directory.
|
||||
|
||||
- a distinct `.egg-info` directory located in the site-packages directory.
|
||||
|
|
@ -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
|
||||
|
|
@ -183,7 +183,7 @@ time. The `RECORD` file will hold the list of installed files. These correspond
|
|||
to the files listed by the `record` option of the `install` command, and will
|
||||
be generated by default. This will allow uninstallation, as explained later in this
|
||||
PEP. The `install` command will also provide an option to prevent the `RECORD`
|
||||
file from being written and this option should be used when creating system
|
||||
file from being written and this option should be used when creating system
|
||||
packages.
|
||||
|
||||
Third-party installation tools also should not overwrite or delete files
|
||||
|
|
@ -253,14 +253,14 @@ Adding an INSTALLER file in the .egg-info directory
|
|||
|
||||
The `install` command will have a new option called `installer`. This option
|
||||
is the name of the tool used to invoke the installation. It's an normalized
|
||||
lower-case string matching `[a-z0-9_\-\.]`.
|
||||
lower-case string matching `[a-z0-9_\-\.]`.
|
||||
|
||||
$ python setup.py install --installer=pkg-system
|
||||
|
||||
It will default to `distutils` if not provided.
|
||||
|
||||
When a project is installed, the INSTALLER file is generated in the
|
||||
`.egg-info` directory with this value, to keep track of **who** installed the
|
||||
When a project is installed, the INSTALLER file is generated in the
|
||||
`.egg-info` directory with this value, to keep track of **who** installed the
|
||||
project. The file is a single-line text file.
|
||||
|
||||
New APIs in pkgutil
|
||||
|
|
@ -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,21 +303,21 @@ 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.
|
||||
|
||||
Returns a ``file`` instance for the file pointed by ``path``.
|
||||
|
||||
``path`` has to be a '/'-separated path relative to the `.egg-info`
|
||||
``path`` has to be a '/'-separated path relative to the `.egg-info`
|
||||
directory or an absolute path.
|
||||
|
||||
If ``path`` is an absolute path and doesn't start with the `.egg-info`
|
||||
If ``path`` is an absolute path and doesn't start with the `.egg-info`
|
||||
directory path, a ``DistutilsError`` is raised.
|
||||
|
||||
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
|
||||
|
|
@ -542,7 +531,7 @@ To avoid removing projects that where installed by another packaging system,
|
|||
the ``uninstall`` function takes an extra argument ``installer`` which default
|
||||
to ``distutils``.
|
||||
|
||||
When called, ``uninstall`` will control that the ``INSTALLER`` file matches
|
||||
When called, ``uninstall`` will control that the ``INSTALLER`` file matches
|
||||
this argument. If not, it will raise a ``DistutilsUninstallError``::
|
||||
|
||||
>>> uninstall('zlib')
|
||||
|
|
@ -552,7 +541,7 @@ this argument. If not, it will raise a ``DistutilsUninstallError``::
|
|||
|
||||
>>> uninstall('zlib', installer='cool-pkg-manager')
|
||||
|
||||
This allows a third-party application to use the ``uninstall`` function
|
||||
This allows a third-party application to use the ``uninstall`` function
|
||||
and make sure it's the only program that can remove a project it has
|
||||
previously installed. This is useful when a third-party program that relies
|
||||
on Distutils APIs does extra steps on the system at installation time,
|
||||
|
|
|
|||
Loading…
Reference in New Issue