From dbab58fdeb5716d761481b56438ba1a2d9977b41 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 24 Jun 2012 16:37:59 +0200 Subject: Refactor the venv API docs into a real API doc style. --- Doc/library/venv.rst | 236 +++++++++++++++++++++++++++------------------------ 1 file changed, 123 insertions(+), 113 deletions(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 5c1e9ad..e5c91e4 100644 --- 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 @@ The command, if run with ``-h``, will show the available options:: --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 --- +.. highlight:: python + 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. +mechanisms for third-party virtual environment creators to customize environment +creation according to their needs, the :class:`EnvBuilder` class. -The :class:`EnvBuilder` class accepts the following keyword arguments on -instantiation: +.. class:: EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False) - * ``system_site_packages`` - A Boolean value indicating that the - system Python site-packages should be available to the - environment (defaults to ``False``). + The :class:`EnvBuilder` class accepts the following keyword arguments on + instantiation: - * ``clear`` - A Boolean value which, if True, will delete any - existing target directory instead of raising an exception - (defaults to ``False``). + * ``system_site_packages`` -- a Boolean value indicating that the system Python + site-packages should be available to the environment (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. + * ``clear`` -- a Boolean value which, if True, will delete any existing target + directory instead of raising an exception (defaults to ``False``). -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. + * ``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. -Creators of third-party virtual environment tools will be free to use -the provided ``EnvBuilder`` class as a base class. + .. XXX it also takes "upgrade"! -.. 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. - 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``, -``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. + Creators of third-party virtual environment tools will be free to use the + provided ``EnvBuilder`` class as a base class. + + The returned env-builder is an object which has a method, ``create``: + + .. method:: create(env_dir) + + 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. + + 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. + 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 :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. -- cgit v0.12