[Python-checkins] r73494 - peps/trunk/pep-0376.txt

[tarek.ziade]

Author: tarek.ziade
Date: Sun Jun 21 17:48:04 2009
New Revision: 73494

Log:
added Zip support

Modified:
   peps/trunk/pep-0376.txt

Modified: peps/trunk/pep-0376.txt
==============================================================================
--- peps/trunk/pep-0376.txt	(original)
+++ peps/trunk/pep-0376.txt	Sun Jun 21 17:48:04 2009
@@ -18,7 +18,7 @@
 
 - A new format for the .egg-info structure.
 - Some APIs to read the meta-data of a project
-- Replace PEP 262
+- A replacement PEP 262
 - An uninstall feature
 
 Definitions
@@ -269,13 +269,19 @@
 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:
+The API is organized in five classes:
 
 - ``Distribution``: manages an `.egg-info` directory.
+- ``ZippedDistribution``: manages an `.egg-info` directory contained in a zip
+  file.
 - ``DistributionDirectory``: manages a directory that contains some `.egg-info`
   directories.
+- ``ZippedDistributionDirectory``: manages a zipped directory that contains
+  some `.egg.info` directory.
 - ``DistributionDirectories``: manages ``EggInfoDirectory`` instances.
 
+XXX mention PEP 273
+
 Distribution class
 ------------------
 
@@ -326,6 +332,12 @@
   If ``local`` is ``True``, each path is transformed into a
   local absolute path. Otherwise the raw value from `RECORD` is returned.
 
+ZippedDistribution class
+------------------------
+
+A ``ZippedDistribution`` class is provided. It overrides the ``Distribution``
+class so its methods work with an `.egg.info` directory located in a zip file.
+
 
 DistributionDirectory class
 ---------------------------
@@ -349,83 +361,100 @@
   If ``path`` is used by only one ``Distribution`` instance, returns it.
   Otherwise returns None.
 
+ZippedDistributionDirectory class
+---------------------------------
+
+A ``ZippedDistributionDirectory`` is provided. It overrides the
+``DistributionDirectory`` class so its methods work with a Zip file.
+
+
 DistributionDirectories class
 -----------------------------
 
 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``,
-``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 ``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.
+``DistributionDirectory`` and ``ZippedDistributionDirectory`` instances.
+The constructor takes one optional argument ``use_cache`` set to ``True`` by
+default. When ``True``, ``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 ``DistributionDirectory`` and
+``ZippedDistributionDirectory`` 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.
 
 The cache can also be emptied with the global ``purge_cache`` function.
 
 The class is a ``dict`` where the values are ``DistributionDirectory``
-instances and the keys are their path attributes.
+and ``ZippedDistributionDirectory`` instances and the keys are their path
+attributes.
 
 ``EggInfoDirectories`` also provides the following methods besides the ones
-from ``dict``:
+from ``dict``::
 
 - ``append(path)``
 
-  Creates an ``DistributionDirectory`` instance for ``path`` and adds it
-  in the mapping.
+  Creates an ``DistributionDirectory`` (or ``ZippedDistributionDirectory``)
+  instance for ``path`` and adds it in the mapping.
 
 - ``load(paths)``
 
-  Creates and adds ``DistributionDirectory`` instances corresponding to
-  ``paths``.
+  Creates and adds ``DistributionDirectory`` (or
+  ``ZippedDistributionDirectory``) instances corresponding to ``paths``.
 
 - ``reload()``
 
   Reloads existing entries.
 
-- ``get_distributions()`` -> Iterator of ``Distribution`` instances.
+- ``get_distributions()`` -> Iterator of ``Distribution`` (or
+  ``ZippedDistribution``) instances.
 
-  Iterates over all ``Distribution`` contained in ``DistributionDirectory``
-  instances.
+  Iterates over all ``Distribution`` and ``ZippedDistribution`` contained
+  in ``DistributionDirectory`` and ``ZippedDistributionDirectory`` instances.
 
-- ``get_distribution(project_name)`` -> ``Distribution`` or None.
+- ``get_distribution(project_name)`` -> ``Distribution`` (or
+  ``ZippedDistribution``) or None.
 
-  Returns a ``Distribution`` instance for the given project name.
-  If not found, returns None.
+  Returns a ``Distribution`` (or ``ZippedDistribution``) instance for the
+  given project name. If not found, returns None.
 
-- ``get_file_users(path)`` -> Iterator of ``Distribution`` instances.
+- ``get_file_users(path)`` -> Iterator of ``Distribution`` (or
+  ``ZippedDistribution``) instances.
 
   Iterates over all projects to find out which project uses the file.
-  Returns ``Distribution`` instances.
+  Returns ``Distribution`` (or ``ZippedDistribution``) instances.
 
 .egg-info functions
 -------------------
 
 The new functions added in the ``pkgutil`` are :
 
-- ``get_distributions()`` -> iterator of ``Distribution`` instance.
+- ``get_distributions()`` -> iterator of ``Distribution`` (or
+  ``ZippedDistribution``) instance.
 
   Provides an iterator that looks for ``.egg-info`` directories in ``sys.path``
-  and returns ``Distribution`` instances for each one of them.
+  and returns ``Distribution`` (or ``ZippedDistribution``) instances for
+  each one of them.
 
-- ``get_distribution(name)`` -> ``Distribution`` or None.
+- ``get_distribution(name)`` -> ``Distribution``  (or ``ZippedDistribution``)
+  or None.
 
   Scans all elements in ``sys.path`` and looks for all directories ending with
-  ``.egg-info``. Returns an ``Distribution`` corresponding to the ``.egg-info``
-  directory that contains a PKG-INFO that matches `name` for the `name`
-  metadata.
+  ``.egg-info``. Returns a ``Distribution``  (or ``ZippedDistribution``)
+  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)`` -> iterator of ``Distribution`` instances.
+- ``get_file_users(path)`` -> iterator of ``Distribution``  (or
+  ``ZippedDistribution``) 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 ``DistributionDirectories``to use the cache. Notice that the cache is never emptied explicitely.
+All these functions use the same global instance of ``DistributionDirectories`` 
+to use the cache. Notice that the cache is never emptied explicitely.
 
 Example
 -------