diff options
Diffstat (limited to 'Doc/library/venv.rst')
| -rw-r--r-- | Doc/library/venv.rst | 193 |
1 files changed, 193 insertions, 0 deletions
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. |