[Python-checkins] r73386 - peps/trunk/pep-0376.txt
tarek.ziade
python-checkins at python.org
Fri Jun 12 12:00:17 CEST 2009
Author: tarek.ziade
Date: Fri Jun 12 12:00:17 2009
New Revision: 73386
Log:
renamed APIs
Modified:
peps/trunk/pep-0376.txt
Modified: peps/trunk/pep-0376.txt
==============================================================================
--- peps/trunk/pep-0376.txt (original)
+++ peps/trunk/pep-0376.txt Fri Jun 12 12:00:17 2009
@@ -24,7 +24,7 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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
- '2.5.2'
-
- '/opt/local/lib/python2.6/site-packages/zlib-2.5.2.egg-info'
- >>> metadata = get_metadata('zlib')
- >>> metadata.version
+ >>> dist.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 @@
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 @@
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 @@
>>> 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,
More information about the Python-checkins
mailing list