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

Tue Jun 23 10:50:11 CEST 2009

Author: tarek.ziade
Date: Tue Jun 23 10:50:10 2009
New Revision: 73516

Log:
Fixes from python-dev feedbacks

Modified:
   peps/trunk/pep-0376.txt

Modified: peps/trunk/pep-0376.txt
==============================================================================

--- peps/trunk/pep-0376.txt	(original)
+++ peps/trunk/pep-0376.txt	Tue Jun 23 10:50:10 2009
@@ -24,15 +24,15 @@
 Definitions
 ===========
 
-A **distribution** is a collection of files, which can be Python modules, 
-extensions or data. A distribution is managed by a special module called 
+A **distribution** is a collection of files, which can be Python modules,
+extensions or data. A distribution is managed by a special module called
 `setup.py` which contains a call to the `distutils.core.setup` function.
-The arguments passed to that function describe the distribution, like 
+The arguments passed to that function describe the distribution, like
 its `name`, its `version`, and so on.
 
-Disutils provides among other things **commands** that can be called 
-through the shell using the `setup.py` script. A `sdist` command is provided 
-for instance, to create a source distribution archive. An `install` command 
+Disutils provides among other things **commands** that can be called
+through the shell using the `setup.py` script. A `sdist` command is provided
+for instance, to create a source distribution archive. An `install` command
 is also provided, to perform an installation of the distribution in the Python
 installation the script is invoked with::
 
@@ -42,7 +42,7 @@
 
 Once installed, the elements are located in various places in the system, like:
 
-- in Python's site-packages (Python modules, Python modules organized into 
+- in Python's site-packages (Python modules, Python modules organized into
   packages, Extensions, etc.)
 - in Python's `include` directory.
 - in Python's `bin` or `Script` directory.
@@ -51,7 +51,7 @@
 Rationale
 =========
 
-There are two problems right now in the way distributions are installed in 
+There are two problems right now in the way distributions are installed in
 Python:
 
 - There are too many ways to do it.
@@ -72,17 +72,18 @@
 The `install_egg_info` subcommand is called during this process, in order to
 create an `.egg-info` file in the `purelib` directory.
 
-For example, if the `zlib` distribution (which contains one package) is 
-installed, two elements will be installed in `site-packages`::
+For example, for the `docutils` distribution, which contains one package an
+extra module and executable scripts, three elements will be installed in
+`site-packages`::
+
+ - docutils : the docutils pakage
+ - roman.py : an extra module used by docutils
+ - docutils-0.5-py2.6.egg-info : a file containing the distribution metadata
+   as described in PEP 314 [#pep314]_. This file corresponds to the file
+   called `PKG-INFO`, built by the `sdist` command.
 
- - zlib
- - zlib-2.5.2-py2.4.egg-info
-
-Where `zlib` is a Python package, and `zlib-2.5.2-py2.4.egg-info` is
-a file containing the distribution metadata as described in PEP 314 [#pep314]_.
-
-This file corresponds to the file called `PKG-INFO`, built by
-the `sdist` command.
+Some executable scripts such as `rst2html.py` will also be added in the `bin`
+directory of the Python installation.
 
 The problem is that many people use `easy_install` (setuptools [#setuptools]_)
 or `pip` [#pip]_ to install their packages, and these third-party tools do not
@@ -90,7 +91,7 @@
 
 - `easy_install` creates an `EGG-INFO` directory inside an `.egg` directory,
   and adds a `PKG-INFO` file inside this directory. The `.egg` directory
-  contains in that case all the elements of the distribution that are supposed 
+  contains in that case all the elements of the distribution that are supposed
   to be installed in `site-packages`, and is placed in the `site-packages`
   directory.
 
@@ -105,11 +106,11 @@
 ---------------------
 
 Distutils doesn't provide any `uninstall` command. If you want to uninstall
-a distribution, you have to be a power user and remove the various elements 
+a distribution, you have to be a power user and remove the various elements
 that were installed. Then look over the `.pth` file to clean them if necessary.
 
 And the process differs, depending on the tools you have used to install the
-distribution, and if the distribution's `setup.py` uses Distutils or 
+distribution, and if the distribution's `setup.py` uses Distutils or
 Setuptools.
 
 Under some circumstances, you might not be able to know for sure that you
@@ -157,11 +158,12 @@
 the fact that they already work with a directory that contains a `PKG-INFO`
 file, the change will have no deep consequences.
 
-For example, if the `zlib` package is installed, the elements that
+For example, if the `docutils` package is installed, the elements that
 will be installed in `site-packages` will become::
 
-    - zlib
-    - zlib-2.5.2.egg-info/
+    - docutils
+    - roman.py
+    - docutils-0.5-py2.6.egg-info/
         PKG-INFO
 
 The syntax of the egg-info directory name is as follows::
@@ -179,8 +181,8 @@
 
 Examples::
 
-    >>> egginfo_dirname('zlib', '2.5.2')
-    'zlib-2.5.2.egg-info'
+    >>> egginfo_dirname('docutils', '0.5')
+    'docutils-0.5.egg-info'
 
     >>> egginfo_dirname('python-ldap', '2.5')
     'python_ldap-2.5.egg-info'
@@ -213,13 +215,13 @@
 
 - field delimiter : `,`
 - quoting char :  `"`.
-- line terminator : `\r\n`
+- line terminator : ``os.linesep`` (so `\r\n` or `\r`)
 
 Each record is composed of three elements.
 
 - the file's full **path**
 
- - if the installed file is located in the directory where the .egg-info
+ - if the installed file is located in the directory where the `.egg-info`
    directory of the package is located, it will be a '/'-separated relative
    path, no matter what is the target system. This makes this information
    cross-compatible and allows simple installation to be relocatable.
@@ -228,7 +230,10 @@
    '/'-separated absolute path is used.
 
 - the **MD5** hash of the file, encoded in hex. Notice that `pyc` and `pyo`
-  generated files will not have a hash.
+  generated files will not have a hash because they are automatically produced
+  from `py` files. So checking the hash of the corresponding `py` file is
+  enough to decide if the file and its associated `pyc` or `pyo` files have
+  changed.
 
 - the file's size in bytes
 
@@ -236,6 +241,11 @@
 so the field separator will be ",". Any "," characters found within a field
 will be escaped automatically by ``csv``.
 
+When the file is read, the `U` option will be used so the universal newline
+support (see PEP 278 [pep278]_) will be activated, avoiding any trouble
+reading a file produced on a platform that uses a different new line
+terminator.
+
 Example
 -------
 
@@ -282,8 +292,8 @@
 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 five classes that work with directories and Zip files 
-(so its works with files included in Zip files, see PEP 273 for more details 
+The API is organized in five classes that work with directories and Zip files
+(so its works with files included in Zip files, see PEP 273 for more details
 [pep273]_.
 
 - ``Distribution``: manages an `.egg-info` directory.
@@ -364,7 +374,7 @@
 
 It also provides two methods besides the ones from ``set``:
 
-- ``file_users(path)`` -> Iterator of ``Distribution``.
+- ``get_file_users(path)`` -> Iterator of ``Distribution``.
 
   Returns all ``Distribution`` which uses ``path``, by calling
   ``Distribution.uses(path)`` on all ``Distribution`` instances.
@@ -405,12 +415,7 @@
 ``DistributionDirectories`` also provides the following methods besides the ones
 from ``dict``::
 
-- ``append(path)``
-
-  Creates an ``DistributionDirectory`` (or ``ZippedDistributionDirectory``)
-  instance for ``path`` and adds it in the mapping.
-
-- ``load(paths)``
+- ``load(*paths)``
 
   Creates and adds ``DistributionDirectory`` (or
   ``ZippedDistributionDirectory``) instances corresponding to ``paths``.
@@ -466,7 +471,7 @@
   Iterates over all distributions to find out which distributions uses ``path``.
   ``path`` can be a local absolute path or a relative '/'-separated path.
 
-All these functions use the same global instance of ``DistributionDirectories`` 
+All these functions use the same global instance of ``DistributionDirectories``
 to use the cache. Notice that the cache is never emptied explicitely.
 
 Example
@@ -482,7 +487,7 @@
     '2.5.2'
 
     >>> for path, hash, size in dist.get_installed_files()::
-    ...     print '%s %s %d %s' % (path, hash, size)
+    ...     print '%s %s %d' % (path, hash, size)
     ...
     zlib/include/zconf.h b690274f621402dda63bf11ba5373bf2 9544
     zlib/include/zlib.h 9c4b84aff68aa55f2e9bf70481b94333 66188
@@ -520,12 +525,12 @@
 Adding an Uninstall function
 ============================
 
-Distutils already provides a very basic way to install a distribution, which 
-is running the `install` command over the `setup.py` script of the 
+Distutils already provides a very basic way to install a distribution, which
+is running the `install` command over the `setup.py` script of the
 distribution.
 
 Distutils will provide a very basic ``uninstall`` function, that will be added
-in ``distutils.util`` and will take the name of the distribution to uninstall 
+in ``distutils.util`` and will take the name of the distribution to uninstall
 as its argument. ``uninstall`` will use the APIs desribed earlier and remove all
 unique files, as long as their hash didn't change. Then it will remove
 empty directories left behind.
@@ -622,6 +627,10 @@
 .. [#pep273]
    http://www.python.org/dev/peps/pep-0273
 
+.. [#pep2738]
+   http://www.python.org/dev/peps/pep-0278
+
+
 .. [distutils]
    http://docs.python.org/distutils
 
