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

[tarek.ziade]

Author: tarek.ziade
Date: Mon Jun  8 11:54:02 2009
New Revision: 73292

Log:
fixes from Ronald feedbacks

Modified:
   peps/trunk/pep-0376.txt

Modified: peps/trunk/pep-0376.txt
==============================================================================
--- peps/trunk/pep-0376.txt	(original)
+++ peps/trunk/pep-0376.txt	Mon Jun  8 11:54:02 2009
@@ -24,8 +24,8 @@
 Definitions
 ===========
 
-A **project** is a Python application composed of one or several files, which can
-be Python modules, extensions or data. It is distributed using a `setup.py` script
+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.
 
@@ -112,8 +112,8 @@
 
 To address those issues, this PEP proposes a few changes:
 
-- a new `.egg-info` structure using a directory, based on the `EggFormats`
-  standard from `setuptools` [#eggformats]_.
+- a new `.egg-info` structure using a directory, based on one form of
+  the `EggFormats` standard from `setuptools` [#eggformats]_.
 - new APIs in `pkgutil` to be able to query the information of installed
   projects.
 - a de-facto replacement for PEP 262
@@ -128,7 +128,14 @@
 the `Distribution` class in Distutils.
 
 Notice that this change is based on the standard proposed by `EggFormats`.
-You may refer to its documentation for more information.
+Although, this standard proposes two ways to install files :
+
+- 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.
+
+You may refer to the `EggFormats` documentation for more details.
 
 This change will not impact Python itself, because `egg-info` files are not
 used anywhere yet in the standard library besides Distutils.
@@ -187,8 +194,15 @@
 The RECORD format
 -----------------
 
-The `RECORD` file is a CSV-like file, composed of records, one line per
-installed file. Each record is composed of three elements.
+The `RECORD` file is a CSV file, composed of records, one line per
+installed file. The ``csv`` module is used to read the file, with
+the `excel` dialect, which uses these options to read the file:
+
+- field delimiter : `,`
+- quoting char :  `"`.
+- line terminator : `\r\n`
+
+Each record is composed of three elements.
 
 - the file's full **path**
 
@@ -289,11 +303,29 @@
   Returns ``True`` if ``path`` is listed in `RECORD`. ``path``
   can be a local absolute path or a relative '/'-separated path.
 
-- ``get_file(path, binary=False)`` -> file object
+- ``get_egg_info(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` 
+   directory or an absolute path.
+
+   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
+
+  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
+  subdirectory.
+
+  If ``local`` is ``True``, each path is transformed into a
+  local absolute path. Otherwise the raw value from `RECORD` is returned.
 
-  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
 ----------------------