[Python-checkins] cpython: Refactor the venv API docs into a real API doc style.
georg.brandl
python-checkins at python.org
Sun Jun 24 16:38:24 CEST 2012
http://hg.python.org/cpython/rev/c28153c96494
changeset: 77720:c28153c96494
user: Georg Brandl <georg at python.org>
date: Sun Jun 24 16:37:59 2012 +0200
summary:
Refactor the venv API docs into a real API doc style.
files:
Doc/library/venv.rst | 222 ++++++++++++++++--------------
1 files changed, 116 insertions(+), 106 deletions(-)
diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
--- a/Doc/library/venv.rst
+++ b/Doc/library/venv.rst
@@ -15,28 +15,26 @@
--------------
-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.
+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::
+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).
-It also creates an (initially empty) ``lib/pythonX.Y/site-packages``
+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). It also creates an (initially empty) ``lib/pythonX.Y/site-packages``
subdirectory (on Windows, this is ``Lib\site-packages``).
.. highlight:: none
@@ -71,119 +69,131 @@
--upgrade Upgrade the environment directory to use this version
of Python, assuming Python has been upgraded in-place.
-If the target directory already exists an error will be raised, unless
-the ``--clear`` or ``--upgrade`` option was provided.
+If the target directory already exists an error will be raised, unless the
+``--clear`` or ``--upgrade`` option was provided.
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.
+``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.
+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::
+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.
- 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)
+.. class:: EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False)
-The ``create`` method of the ``EnvBuilder`` class illustrates the
-hooks available for subclass customization::
+ The :class:`EnvBuilder` class accepts the following keyword arguments on
+ instantiation:
- def create(self, env_dir):
- """
- Create a virtualized Python environment in a directory.
- env_dir is 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)
+ * ``system_site_packages`` -- a Boolean value indicating that the system Python
+ site-packages should be available to the environment (defaults to ``False``).
-Each of the methods ``create_directories``, ``create_configuration``,
-``setup_python``, ``setup_scripts`` and ``post_setup`` can be
-overridden. The functions of these methods are:
+ * ``clear`` -- a Boolean value which, if True, will delete any existing target
+ directory instead of raising an exception (defaults to ``False``).
- * ``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.
+ * ``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.
- * ``create_configuration`` - creates the ``pyvenv.cfg``
- configuration file in the environment.
+ .. XXX it also takes "upgrade"!
- * ``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.
+ Creators of third-party virtual environment tools will be free to use the
+ provided ``EnvBuilder`` class as a base class.
- * ``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.
+ The returned env-builder is an object which has a method, ``create``:
-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:
+ .. method:: create(env_dir)
-* ``__VENV_DIR__`` is replaced with the absolute path of the
- environment directory.
+ This method 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.
-* ``__VENV_NAME__`` is replaced with the environment name (final path
- segment of environment directory).
+ The ``create`` method of the ``EnvBuilder`` class illustrates the hooks
+ available for subclass customization::
-* ``__VENV_BIN_NAME__`` is replaced with the name of the bin directory
- (either ``bin`` or ``Scripts``).
+ def create(self, env_dir):
+ """
+ Create a virtualized Python environment in a directory.
+ env_dir is 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)
-* ``__VENV_PYTHON__`` is replaced with the absolute path of the
- environment's executable.
+ Each of the methods :meth:`create_directories`,
+ :meth:`create_configuration`, :meth:`setup_python`,
+ :meth:`setup_scripts` and :meth:`post_setup` can be overridden.
+
+ .. method:: create_directories(env_dir)
+
+ 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.
+
+ .. method:: create_configuration(context)
+
+ Creates the ``pyvenv.cfg`` configuration file in the environment.
+
+ .. method:: setup_python(context)
+
+ Creates a copy of the Python executable (and, under Windows, DLLs) in
+ the environment.
+
+ .. method:: setup_scripts(context)
+
+ Installs activation scripts appropriate to the platform into the virtual
+ environment.
+
+ .. method:: post_setup(context)
+
+ 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, :class:`EnvBuilder` provides this utility method that can be
+ called from :meth:`setup_scripts` or :meth:`post_setup` in subclasses to
+ assist in installing custom scripts into the virtual environment.
+
+ .. method:: install_scripts(context, path)
+
+ *path* is the path to a directory that 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 :data:`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.
+
+
+There is also a module-level convenience function:
+
+.. function:: create(env_dir, system_site_packages=False, clear=False, symlinks=False)
+
+ Create an :class:`EnvBuilder` with the given keyword arguments, and call its
+ :meth:`~EnvBuilder.create` method with the *env_dir* argument.
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list