diff --git a/pep-0376.txt b/pep-0376.txt index 75b7222a2..403471d96 100644 --- a/pep-0376.txt +++ b/pep-0376.txt @@ -24,8 +24,8 @@ This PEP proposes various enhancements for Distutils: 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 @@ What this PEP proposes 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 @@ hold the `PKG-INFO` file built by the `write_pkg_file` method of 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 @@ This RECORD file is inspired from PEP 262 FILES [#pep262]_. 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 @@ And following methods: 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 ----------------------