Implemented PEP 405 (Python virtual environments).
diff --git a/Doc/library/development.rst b/Doc/library/development.rst
index 06e7048..2368769 100644
--- a/Doc/library/development.rst
+++ b/Doc/library/development.rst
@@ -23,3 +23,4 @@
unittest.mock-examples.rst
2to3.rst
test.rst
+ venv.rst
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 96450c5..1ba9005 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -29,6 +29,26 @@
command line, see the :mod:`fileinput` module.
+.. data:: base_exec_prefix
+
+ Set during Python startup, before ``site.py`` is run, to the same value as
+ :data:`exec_prefix`. If not running in a virtual environment, the values
+ will stay the same; if ``site.py`` finds that a virtual environment is in
+ use, the values of :data:`prefix` and :data:`exec_prefix` will be changed to
+ point to the virtual environment, whereas :data:`base_prefix` and
+ :data:`base_exec_prefix` will remain pointing to the base Python
+ installation (the one which the virtual environment was created from).
+
+.. data:: base_prefix
+
+ Set during Python startup, before ``site.py`` is run, to the same value as
+ :data:`prefix`. If not running in a virtual environment, the values
+ will stay the same; if ``site.py`` finds that a virtual environment is in
+ use, the values of :data:`prefix` and :data:`exec_prefix` will be changed to
+ point to the virtual environment, whereas :data:`base_prefix` and
+ :data:`base_exec_prefix` will remain pointing to the base Python
+ installation (the one which the virtual environment was created from).
+
.. data:: byteorder
An indicator of the native byte order. This will have the value ``'big'`` on
@@ -199,6 +219,10 @@
installed in :file:`{exec_prefix}/lib/python{X.Y}/lib-dynload`, where *X.Y*
is the version number of Python, for example ``3.2``.
+ .. note:: If a virtual environment is in effect, this value will be changed
+ in ``site.py`` to point to the virtual environment. The value for the
+ Python installation will still be available, via :data:`base_exec_prefix`.
+
.. data:: executable
@@ -775,6 +799,10 @@
stored in :file:`{prefix}/include/python{X.Y}`, where *X.Y* is the version
number of Python, for example ``3.2``.
+ .. note:: If a virtual environment is in effect, this value will be changed
+ in ``site.py`` to point to the virtual environment. The value for the
+ Python installation will still be available, via :data:`base_prefix`.
+
.. data:: ps1
ps2
diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
new file mode 100644
index 0000000..b86f573
--- /dev/null
+++ b/Doc/library/venv.rst
@@ -0,0 +1,193 @@
+:mod:`venv` --- Creation of virtual environments
+================================================
+
+.. module:: venv
+ :synopsis: Creation of virtual environments.
+.. moduleauthor:: Vinay Sajip <vinay_sajip@yahoo.co.uk>
+.. sectionauthor:: Vinay Sajip <vinay_sajip@yahoo.co.uk>
+
+
+.. index:: pair: Environments; virtual
+
+.. versionadded:: 3.3
+
+**Source code:** :source:`Lib/venv.py`
+
+--------------
+
+The :mod:`venv` module provides support for creating lightweight
+"virtual environments" with their own site directories, optionally
+isolated from system site directories. Each virtual environment has
+its own Python binary (allowing creation of environments with various
+Python versions) and can have its own independent set of installed
+Python packages in its site directories.
+
+Creating virtual environments
+-----------------------------
+
+Creation of virtual environments is simplest executing the ``pyvenv``
+script::
+
+ pyvenv /path/to/new/virtual/environment
+
+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 of the ``python`` binary (or
+binaries, in the case of Windows) and the ``pysetup3`` script (to
+facilitate easy installation of packages from PyPI into the new virtualenv).
+It also creates an (initially empty) ``lib/pythonX.Y/site-packages``
+subdirectory (on Windows, this is ``Lib\site-packages``).
+
+.. highlight:: none
+
+On Windows, you may have to invoke the ``pyvenv`` script as follows, if you
+don't have the relevant PATH and PATHEXT settings::
+
+ c:\Temp>c:\Python33\python c:\Python33\Tools\Scripts\pyvenv.py myenv
+
+or equivalently::
+
+ c:\Temp>c:\Python33\python -m venv myenv
+
+The command, if run with ``-h``, will show the available options::
+
+ usage: pyvenv [-h] [--system-site-packages] [--symlink] [--clear]
+ ENV_DIR [ENV_DIR ...]
+
+ Creates virtual Python environments in one or more target directories.
+
+ positional arguments:
+ ENV_DIR A directory to create the environment in.
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --system-site-packages Give access to the global site-packages dir to the
+ virtual environment.
+ --symlink Attempt to symlink rather than copy.
+ --clear Delete the environment directory if it already exists.
+ If not specified and the directory exists, an error is
+ raised.
+
+
+If the target directory already exists an error will be raised, unless
+the ``--clear`` option was provided, in which case the target
+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
+run with the ``--system-site-packages`` option, ``false`` otherwise.
+
+Multiple paths can be given to ``pyvenv``, in which case an identical
+virtualenv will be created, according to the given options, at each
+provided path.
+
+
+API
+---
+
+The high-level method described above makes use of a simple API which provides
+mechanisms for third-party virtual environment creators to customize
+environment creation according to their needs.
+
+The :class:`EnvBuilder` class accepts the following keyword arguments on
+instantiation:
+
+ * ``system_site_packages`` - A Boolean value indicating that the
+ system Python site-packages should be available to the
+ environment (defaults to ``False``).
+
+ * ``clear`` - A Boolean value which, if True, will delete any
+ existing target directory instead of raising an exception
+ (defaults to ``False``).
+
+ * ``symlinks`` - A Boolean value indicating whether to attempt
+ to symlink the Python binary (and any necessary DLLs or other
+ binaries, e.g. ``pythonw.exe``), rather than copying. Defaults to
+ ``True`` on Linux and Unix systems, but ``False`` on Windows and
+ Mac OS X.
+
+The returned env-builder is an object which has a method, ``create``,
+which takes as required argument the path (absolute or relative to the current
+directory) of the target directory which is to contain the virtual environment.
+The ``create`` method will either create the environment in the specified
+directory, or raise an appropriate exception.
+
+Creators of third-party virtual environment tools will be free to use
+the provided ``EnvBuilder`` class as a base class.
+
+.. highlight:: python
+
+The ``venv`` module will also provide a module-level function as a
+convenience::
+
+ def create(env_dir,
+ system_site_packages=False, clear=False, symlinks=False):
+ builder = EnvBuilder(
+ system_site_packages=system_site_packages,
+ clear=clear,
+ symlinks=symlinks)
+ builder.create(env_dir)
+
+The ``create`` method of the ``EnvBuilder`` class illustrates the
+hooks available for subclass customization::
+
+ def create(self, env_dir):
+ """
+ Create a virtualized Python environment in a directory.
+
+ :param env_dir: The target directory to create an environment in.
+
+ """
+ env_dir = os.path.abspath(env_dir)
+ context = self.create_directories(env_dir)
+ self.create_configuration(context)
+ self.setup_python(context)
+ self.setup_scripts(context)
+ self.post_setup(context)
+
+Each of the methods ``create_directories``, ``create_configuration``,
+``setup_python``, ``setup_scripts`` and ``post_setup`` can be
+overridden. The functions of these methods are:
+
+ * ``create_directories`` - creates the environment directory and
+ all necessary directories, and returns a context object. This is
+ just a holder for attributes (such as paths), for use by the
+ other methods.
+
+ * ``create_configuration`` - creates the ``pyvenv.cfg``
+ configuration file in the environment.
+
+ * ``setup_python`` - creates a copy of the Python executable (and,
+ under Windows, DLLs) in the environment.
+
+ * ``setup_scripts`` - Installs activation scripts appropriate to the
+ platform into the virtual environment.
+
+ * ``post_setup`` - A placeholder method which can be overridden
+ in third party implementations to pre-install packages in the
+ virtual environment or perform other post-creation steps.
+
+In addition, ``EnvBuilder`` provides an ``install_scripts`` utility
+method that can be called from ``setup_scripts`` or ``post_setup`` in
+subclasses to assist in installing custom scripts into the virtual
+environment. The method accepts as arguments the context object (see
+above) and a path to a directory. The directory should contain
+subdirectories "common", "posix", "nt", each containing scripts
+destined for the bin directory in the environment. The contents of
+"common" and the directory corresponding to ``os.name`` are copied
+after some text replacement of placeholders:
+
+* ``__VENV_DIR__`` is replaced with the absolute path of the
+ environment directory.
+
+* ``__VENV_NAME__`` is replaced with the environment name (final path
+ segment of environment directory).
+
+* ``__VENV_BIN_NAME__`` is replaced with the name of the bin directory
+ (either ``bin`` or ``Scripts``).
+
+* ``__VENV_PYTHON__`` is replaced with the absolute path of the
+ environment's executable.