renamed APIs

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 
+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 
+`.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.
+- ``Distribution``: manages an `.egg-info` directory.
-- ``EggInfoDirectory``: manages a directory that contains some `.egg-info`
+- ``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`
+A new class called ``Distribution`` is created with a the path of the
-directory provided to the contructor. It reads the metadata contained in
+`.egg-info` directory provided to the contructor. It reads the metadata
-`PKG-INFO` when it is instanciated.
+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
+- ``metadata``: A ``DistributionMetadata`` instance loaded with the
-  PKG-INFO file
+  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
+A new class called ``DistributionDirectory`` is created with a path
-to a directory. For each `.egg-info` directory founded in `path`, the class
+corresponding to a directory. For each `.egg-info` directory founded in
-creates a corresponding ``EggInfo``.
+`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
+  Returns all ``Distribution`` which uses ``path``, by calling
-  ``EggInfo.uses(path)`` on all ``EggInfo`` instances.
+  ``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
+A new class called ``DistributionDirectories`` is created. It's a collection of
-``EggInfoDirectory`` instances. The constructor takes one optional
+``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
+``DistributionDirectories`` will use a global cache to reduce the numbers of
-accesses and speed up the lookups.
+I/O accesses and speed up the lookups.
 
-The cache is a global mapping containing ``EggInfoDirectory`` instances.
+The cache is a global mapping containing ``DistributionDirectory`` instances.
-When an ``EggInfoDirectories`` object is created, it will use the cache to
+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
+The class is a ``dict`` where the values are ``DistributionDirectory``
-``EggInfoDirectory`` instance it contains.
+instances and the keys are their path attributes.
 
-``EggInfoDirectories`` also provides the following container and helper
+``EggInfoDirectories`` also provides the following methods besides the ones
-methods:
+from ``dict``:
 
 - ``append(path)``
 
-  Creates an ``EggInfoDirectory`` instance. for ``path`` appends it.
+  Creates an ``DistributionDirectory`` instance for ``path`` and adds it
-
+  in the mapping.
-- ``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``.
+  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``
+  ``.egg-info``. Returns an ``Distribution`` corresponding to the ``.egg-info``
-  directory that contains a PKG-INFO that matches `project_name` for the `name`
+  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
+All these functions use the same global instance of ``DistributionDirectories``to use the cache. Notice that the cache is never emptied explicitely.
-use the cache. Notice that the cache is never emptied explicitely so it keeps
-on growing everytime it is used with new paths.
 
 Example
 -------
 
 Let's use some of the new APIs with our `zlib` example::
 
-    >>> from pkgutil import get_egg_info, get_file_users
+    >>> from pkgutil import get_distribution, get_file_users
-    >>> egg_info = get_egg_info('zlib')
+    >>> dist = get_distribution('zlib')
-    >>> egg_info.name
+    >>> 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'
+    >>> for path, hash, size in dist.get_installed_files()::
-    >>> metadata = get_metadata('zlib')
-    >>> metadata.version
-    '2.5.2'
-
-    >>> for path, hash, size in egg_info.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,