Merged updates by Carl following Nick's review.

pep-0405.txt

@@ -9,7 +9,7 @@ Type: Standards Track
 Content-Type: text/x-rst
 Created: 13-Jun-2011
 Python-Version: 3.3
-Post-History: 24-Oct-2011, 28-Oct-2011, 06-Mar-2012
+Post-History: 24-Oct-2011, 28-Oct-2011, 06-Mar-2012, 24-May-2012
 
 
 Abstract
@@ -78,12 +78,13 @@ that signifies the presence of the standard library, and if none is
 found, falling back to the build-time prefix hardcoded in the binary.
 
 This PEP proposes to add a new first step to this search.  If a
-``pyvenv.cfg`` file is found either adjacent to the Python executable,
-or one directory above it, this file is scanned for lines of the form
-``key = value``.  If a ``home`` key is found, this signifies that the
-Python binary belongs to a virtual environment, and the value of the
-``home`` key is the directory containing the Python executable used to
-create this virtual environment.
+``pyvenv.cfg`` file is found either adjacent to the Python executable or
+one directory above it (if the executable is a symlink, it is not
+dereferenced), this file is scanned for lines of the form ``key =
+value``.  If a ``home`` key is found, this signifies that the Python
+binary belongs to a virtual environment, and the value of the ``home``
+key is the directory containing the Python executable used to create
+this virtual environment.
 
 In this case, prefix-finding continues as normal using the value of
 the ``home`` key as the effective Python binary location, which finds
@@ -95,14 +96,16 @@ this value, while ``sys.prefix`` is set to the directory containing
 prefix-finding continues normally, and ``sys.prefix`` will be equal to
 ``sys.base_prefix``.)
 
+Also, ``sys.base_exec_prefix`` is added, and handled similarly with
+regard to ``sys.exec_prefix``. (``sys.exec_prefix`` is the equivalent of
+``sys.prefix``, but for platform-specific files; by default it has the
+same value as ``sys.prefix``.)
+
 The ``site`` and ``sysconfig`` standard-library modules are modified
 such that the standard library and header files are are found relative
-to ``sys.base_prefix``, while site-package directories ("purelib" and
-"platlib", in ``sysconfig`` terms) are still found relative to
-``sys.prefix``.
-
-(Also, ``sys.base_exec_prefix`` is added, and handled similarly with
-regard to ``sys.exec_prefix``.)
+to ``sys.base_prefix`` / ``sys.base_exec_prefix``, while site-package
+directories ("purelib" and "platlib", in ``sysconfig`` terms) are still
+found relative to ``sys.prefix`` / ``sys.exec_prefix``.
 
 Thus, a Python virtual environment in its simplest form would consist
 of nothing more than a copy or symlink of the Python binary
@@ -147,12 +150,12 @@ Running this command creates the target directory (creating any parent
 directories that don't exist already) and places a ``pyvenv.cfg`` file
 in it with a ``home`` key pointing to the Python installation the
 command was run from.  It also creates a ``bin/`` (or ``Scripts`` on
-Windows) subdirectory containing a copy (or symlink) of the
-``python3`` executable, and the ``pysetup3`` script from the
-``packaging`` standard library module (to facilitate easy installation
-of packages from PyPI into the new virtualenv).  And it creates an
-(initially empty) ``lib/pythonX.Y/site-packages`` (or
-``Lib\site-packages`` on Windows) subdirectory.
+Windows) subdirectory containing a copy (or symlink) of the ``python3``
+executable, and the ``pysetup3`` script from the ``packaging`` standard
+library module (to facilitate easy installation of packages from PyPI
+into the new venv).  And it creates an (initially empty)
+``lib/pythonX.Y/site-packages`` (or ``Lib\site-packages`` on Windows)
+subdirectory.
 
 If the target directory already exists an error will be raised, unless
 the ``--clear`` option was provided, in which case the target
@@ -160,27 +163,29 @@ directory will be deleted and virtual environment creation will
 proceed as usual.
 
 The created ``pyvenv.cfg`` file also includes the
-``include-system-site-packages`` key, set to ``true`` if ``venv`` is
+``include-system-site-packages`` key, set to ``true`` if ``pyvenv`` is
 run with the ``--system-site-packages`` option, ``false`` by default.
 
 Multiple paths can be given to ``pyvenv``, in which case an identical
-virtualenv will be created, according to the given options, at each
+venv will be created, according to the given options, at each
 provided path.
 
-The ``venv`` module also provides "shell activation scripts" for POSIX
-and Windows systems which simply add the virtual environment's ``bin``
-(or ``Scripts``) directory to the front of the user's shell PATH.
-This is not strictly necessary for use of a virtual environment (as an
-explicit path to the venv's python binary or scripts can just as well
-be used), but it is convenient.
+The ``venv`` module also places "shell activation scripts" for POSIX and
+Windows systems in the ``bin`` or ``Scripts`` directory of the
+venv. These scripts simply add the virtual environment's ``bin`` (or
+``Scripts``) directory to the front of the user's shell PATH.  This is
+not strictly necessary for use of a virtual environment (as an explicit
+path to the venv's python binary or scripts can just as well be used),
+but it is convenient.
 
 In order to allow ``pysetup`` and other Python package managers to
 install packages into the virtual environment the same way they would
 install into a normal Python installation, and avoid special-casing
-virtual environments in ``sysconfig`` beyond using ``sys.site_prefix``
-in place of ``sys.prefix``, the internal virtual environment layout
-mimics the layout of the Python installation itself on each platform.
-So a typical virtual environment layout on a POSIX system would be::
+virtual environments in ``sysconfig`` beyond using ``sys.base_prefix``
+in place of ``sys.prefix`` where appropriate, the internal virtual
+environment layout mimics the layout of the Python installation itself
+on each platform.  So a typical virtual environment layout on a POSIX
+system would be::
 
     pyvenv.cfg
     bin/python3
@@ -299,19 +304,17 @@ standard abstraction for a site-specific include directory.
 
 This PEP proposes a slightly different approach, though one with
 essentially the same effect and the same set of advantages and
-disadvantages. Rather than symlinking or copying include files into
-the venv, we simply modify the sysconfig schemes so that header files
-are always looked for relative to ``base_prefix`` rather than
-``prefix``. (We also create an ``include/`` directory within the venv
+disadvantages. Rather than symlinking or copying include files into the
+venv, we simply modify the sysconfig schemes so that header files are
+always sought relative to ``base_prefix`` rather than ``prefix``. (We
+also create an ``include/`` directory within the venv, so installers
+have somewhere to put include files installed within the env).
 
 Better handling of include files in distutils/packaging and, by
 extension, pyvenv, is an area that may deserve its own future PEP. For
 now, we propose that the behavior of virtualenv has thus far proved
 itself to be at least "good enough" in practice.
 
-[Open question: should pyvenv instead simply copy the behavior of
-virtualenv entirely, to avoid introducing unexpected new issues here?]
-
 
 API
 ---
@@ -508,10 +511,8 @@ Reference Implementation
 ========================
 
 The reference implementation is found in `a clone of the CPython
-Mercurial repository`_.  To test it, build and install it (the virtual
-environment tool currently does not run from a source tree).  From the
-installed Python, run ``bin/pyvenv /path/to/new/virtualenv`` to create
-a virtual environment.
+Mercurial repository`_.  To test it, build and run ``bin/pyvenv
+/path/to/new/venv`` to create a virtual environment.
 
 .. _a clone of the CPython Mercurial repository: http://hg.python.org/sandbox/vsajip#venv