traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Refactor the venv API docs into a real API doc style.

This commit is contained in:
Georg Brandl 2012-06-24 16:37:59 +02:00
parent 1f5d2a087c
commit dbab58fdeb
1 changed files with 116 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

222
Doc/library/venv.rst
View File

@ -15,28 +15,26 @@
-------------- --------------
The :mod:`venv` module provides support for creating lightweight The :mod:`venv` module provides support for creating lightweight "virtual
"virtual environments" with their own site directories, optionally environments" with their own site directories, optionally isolated from system
isolated from system site directories. Each virtual environment has site directories. Each virtual environment has its own Python binary (allowing
its own Python binary (allowing creation of environments with various creation of environments with various Python versions) and can have its own
Python versions) and can have its own independent set of installed independent set of installed Python packages in its site directories.
Python packages in its site directories.
Creating virtual environments Creating virtual environments
----------------------------- -----------------------------
Creation of virtual environments is simplest executing the ``pyvenv`` Creation of virtual environments is simplest executing the ``pyvenv`` script::
script::
pyvenv /path/to/new/virtual/environment pyvenv /path/to/new/virtual/environment
Running this command creates the target directory (creating any parent Running this command creates the target directory (creating any parent
directories that don't exist already) and places a ``pyvenv.cfg`` file directories that don't exist already) and places a ``pyvenv.cfg`` file in it
in it with a ``home`` key pointing to the Python installation the with a ``home`` key pointing to the Python installation the command was run
command was run from. It also creates a ``bin`` (or ``Scripts`` on from. It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory
Windows) subdirectory containing a copy of the ``python`` binary (or containing a copy of the ``python`` binary (or binaries, in the case of
binaries, in the case of Windows). Windows). It also creates an (initially empty) ``lib/pythonX.Y/site-packages``
It also creates an (initially empty) ``lib/pythonX.Y/site-packages``
subdirectory (on Windows, this is ``Lib\site-packages``). subdirectory (on Windows, this is ``Lib\site-packages``).
.. highlight:: none .. highlight:: none
@ -71,119 +69,131 @@ The command, if run with ``-h``, will show the available options::
--upgrade Upgrade the environment directory to use this version --upgrade Upgrade the environment directory to use this version
of Python, assuming Python has been upgraded in-place. of Python, assuming Python has been upgraded in-place.
If the target directory already exists an error will be raised, unless If the target directory already exists an error will be raised, unless the
the ``--clear`` or ``--upgrade`` option was provided. ``--clear`` or ``--upgrade`` option was provided.
The created ``pyvenv.cfg`` file also includes the 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 ``venv`` is run with
run with the ``--system-site-packages`` option, ``false`` otherwise. the ``--system-site-packages`` option, ``false`` otherwise.
Multiple paths can be given to ``pyvenv``, in which case an identical Multiple paths can be given to ``pyvenv``, in which case an identical virtualenv
virtualenv will be created, according to the given options, at each will be created, according to the given options, at each provided path.
provided path.
API 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 .. highlight:: python
The ``venv`` module will also provide a module-level function as a The high-level method described above makes use of a simple API which provides
convenience:: mechanisms for third-party virtual environment creators to customize environment
creation according to their needs, the :class:`EnvBuilder` class.
def create(env_dir, .. class:: EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False)
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 The :class:`EnvBuilder` class accepts the following keyword arguments on
hooks available for subclass customization:: instantiation:
def create(self, env_dir): * ``system_site_packages`` -- a Boolean value indicating that the system Python
""" site-packages should be available to the environment (defaults to ``False``).
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)
Each of the methods ``create_directories``, ``create_configuration``, * ``clear`` -- a Boolean value which, if True, will delete any existing target
``setup_python``, ``setup_scripts`` and ``post_setup`` can be directory instead of raising an exception (defaults to ``False``).
overridden. The functions of these methods are:
* ``create_directories`` - creates the environment directory and * ``symlinks`` -- a Boolean value indicating whether to attempt to symlink the
all necessary directories, and returns a context object. This is Python binary (and any necessary DLLs or other binaries,
just a holder for attributes (such as paths), for use by the e.g. ``pythonw.exe``), rather than copying. Defaults to ``True`` on Linux and
other methods. Unix systems, but ``False`` on Windows and Mac OS X.
* ``create_configuration`` - creates the ``pyvenv.cfg`` .. XXX it also takes "upgrade"!
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 Creators of third-party virtual environment tools will be free to use the
platform into the virtual environment. provided ``EnvBuilder`` class as a base class.
* ``post_setup`` - A placeholder method which can be overridden The returned env-builder is an object which has a method, ``create``:
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:: create(env_dir)
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 This method takes as required argument the path (absolute or relative to
environment directory. 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 The ``create`` method of the ``EnvBuilder`` class illustrates the hooks
segment of environment directory). available for subclass customization::
* ``__VENV_BIN_NAME__`` is replaced with the name of the bin directory def create(self, env_dir):
(either ``bin`` or ``Scripts``). """
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 Each of the methods :meth:`create_directories`,
environment's executable. :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.