reflecting the last API discussions in the SIG

pep-0376.txt

@@ -233,18 +233,28 @@ 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)
 
@@ -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
   ``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 ...>