Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit dbab58f

Browse files
birkenfeldbirkenfeld
committed
Refactor the venv API docs into a real API doc style.
1 parent 1f5d2a0 commit dbab58f

1 file changed

Lines changed: 123 additions & 113 deletions

File tree

‎Doc/library/venv.rst‎

Lines changed: 123 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -15,28 +15,26 @@
1515

1616
--------------
1717

18-
The :mod:`venv` module provides support for creating lightweight
19-
"virtual environments" with their own site directories, optionally
20-
isolated from system site directories. Each virtual environment has
21-
its own Python binary (allowing creation of environments with various
22-
Python versions) and can have its own independent set of installed
23-
Python packages in its site directories.
18+
The :mod:`venv` module provides support for creating lightweight "virtual
19+
environments" with their own site directories, optionally isolated from system
20+
site directories. Each virtual environment has its own Python binary (allowing
21+
creation of environments with various Python versions) and can have its own
22+
independent set of installed Python packages in its site directories.
23+
2424

2525
Creating virtual environments
2626
-----------------------------
2727

28-
Creation of virtual environments is simplest executing the ``pyvenv``
29-
script::
28+
Creation of virtual environments is simplest executing the ``pyvenv`` script::
3029

3130
pyvenv /path/to/new/virtual/environment
3231

3332
Running this command creates the target directory (creating any parent
34-
directories that don't exist already) and places a ``pyvenv.cfg`` file
35-
in it with a ``home`` key pointing to the Python installation the
36-
command was run from. It also creates a ``bin`` (or ``Scripts`` on
37-
Windows) subdirectory containing a copy of the ``python`` binary (or
38-
binaries, in the case of Windows).
39-
It also creates an (initially empty) ``lib/pythonX.Y/site-packages``
33+
directories that don't exist already) and places a ``pyvenv.cfg`` file in it
34+
with a ``home`` key pointing to the Python installation the command was run
35+
from. It also creates a ``bin`` (or ``Scripts`` on Windows) subdirectory
36+
containing a copy of the ``python`` binary (or binaries, in the case of
37+
Windows). It also creates an (initially empty) ``lib/pythonX.Y/site-packages``
4038
subdirectory (on Windows, this is ``Lib\site-packages``).
4139

4240
.. highlight:: none
@@ -71,119 +69,131 @@ The command, if run with ``-h``, will show the available options::
7169
--upgrade Upgrade the environment directory to use this version
7270
of Python, assuming Python has been upgraded in-place.
7371

74-
If the target directory already exists an error will be raised, unless
75-
the ``--clear`` or ``--upgrade`` option was provided.
72+
If the target directory already exists an error will be raised, unless the
73+
``--clear`` or ``--upgrade`` option was provided.
7674

7775
The created ``pyvenv.cfg`` file also includes the
78-
``include-system-site-packages`` key, set to ``true`` if ``venv`` is
79-
run with the ``--system-site-packages`` option, ``false`` otherwise.
76+
``include-system-site-packages`` key, set to ``true`` if ``venv`` is run with
77+
the ``--system-site-packages`` option, ``false`` otherwise.
8078

81-
Multiple paths can be given to ``pyvenv``, in which case an identical
82-
virtualenv will be created, according to the given options, at each
83-
provided path.
79+
Multiple paths can be given to ``pyvenv``, in which case an identical virtualenv
80+
will be created, according to the given options, at each provided path.
8481

8582

8683
API
8784
---
8885

86+
.. highlight:: python
87+
8988
The high-level method described above makes use of a simple API which provides
90-
mechanisms for third-party virtual environment creators to customize
91-
environment creation according to their needs.
89+
mechanisms for third-party virtual environment creators to customize environment
90+
creation according to their needs, the :class:`EnvBuilder` class.
9291

93-
The :class:`EnvBuilder` class accepts the following keyword arguments on
94-
instantiation:
92+
.. class:: EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False)
9593

96-
* ``system_site_packages`` - A Boolean value indicating that the
97-
system Python site-packages should be available to the
98-
environment (defaults to ``False``).
94+
The :class:`EnvBuilder` class accepts the following keyword arguments on
95+
instantiation:
9996

100-
* ``clear`` - A Boolean value which, if True, will delete any
101-
existing target directory instead of raising an exception
102-
(defaults to ``False``).
97+
* ``system_site_packages`` -- a Boolean value indicating that the system Python
98+
site-packages should be available to the environment (defaults to ``False``).
10399

104-
* ``symlinks`` - A Boolean value indicating whether to attempt
105-
to symlink the Python binary (and any necessary DLLs or other
106-
binaries, e.g. ``pythonw.exe``), rather than copying. Defaults to
107-
``True`` on Linux and Unix systems, but ``False`` on Windows and
108-
Mac OS X.
100+
* ``clear`` -- a Boolean value which, if True, will delete any existing target
101+
directory instead of raising an exception (defaults to ``False``).
109102

110-
The returned env-builder is an object which has a method, ``create``,
111-
which takes as required argument the path (absolute or relative to the current
112-
directory) of the target directory which is to contain the virtual environment.
113-
The ``create`` method will either create the environment in the specified
114-
directory, or raise an appropriate exception.
103+
* ``symlinks`` -- a Boolean value indicating whether to attempt to symlink the
104+
Python binary (and any necessary DLLs or other binaries,
105+
e.g. ``pythonw.exe``), rather than copying. Defaults to ``True`` on Linux and
106+
Unix systems, but ``False`` on Windows and Mac OS X.
115107

116-
Creators of third-party virtual environment tools will be free to use
117-
the provided ``EnvBuilder`` class as a base class.
108+
.. XXX it also takes "upgrade"!
118109
119-
.. highlight:: python
120110
121-
The ``venv`` module will also provide a module-level function as a
122-
convenience::
123-
124-
def create(env_dir,
125-
system_site_packages=False, clear=False, symlinks=False):
126-
builder = EnvBuilder(
127-
system_site_packages=system_site_packages,
128-
clear=clear,
129-
symlinks=symlinks)
130-
builder.create(env_dir)
131-
132-
The ``create`` method of the ``EnvBuilder`` class illustrates the
133-
hooks available for subclass customization::
134-
135-
def create(self, env_dir):
136-
"""
137-
Create a virtualized Python environment in a directory.
138-
env_dir is the target directory to create an environment in.
139-
"""
140-
env_dir = os.path.abspath(env_dir)
141-
context = self.create_directories(env_dir)
142-
self.create_configuration(context)
143-
self.setup_python(context)
144-
self.setup_scripts(context)
145-
self.post_setup(context)
146-
147-
Each of the methods ``create_directories``, ``create_configuration``,
148-
``setup_python``, ``setup_scripts`` and ``post_setup`` can be
149-
overridden. The functions of these methods are:
150-
151-
* ``create_directories`` - creates the environment directory and
152-
all necessary directories, and returns a context object. This is
153-
just a holder for attributes (such as paths), for use by the
154-
other methods.
155-
156-
* ``create_configuration`` - creates the ``pyvenv.cfg``
157-
configuration file in the environment.
158-
159-
* ``setup_python`` - creates a copy of the Python executable (and,
160-
under Windows, DLLs) in the environment.
161-
162-
* ``setup_scripts`` - Installs activation scripts appropriate to the
163-
platform into the virtual environment.
164-
165-
* ``post_setup`` - A placeholder method which can be overridden
166-
in third party implementations to pre-install packages in the
167-
virtual environment or perform other post-creation steps.
168-
169-
In addition, ``EnvBuilder`` provides an ``install_scripts`` utility
170-
method that can be called from ``setup_scripts`` or ``post_setup`` in
171-
subclasses to assist in installing custom scripts into the virtual
172-
environment. The method accepts as arguments the context object (see
173-
above) and a path to a directory. The directory should contain
174-
subdirectories "common", "posix", "nt", each containing scripts
175-
destined for the bin directory in the environment. The contents of
176-
"common" and the directory corresponding to ``os.name`` are copied
177-
after some text replacement of placeholders:
178-
179-
* ``__VENV_DIR__`` is replaced with the absolute path of the
180-
environment directory.
181-
182-
* ``__VENV_NAME__`` is replaced with the environment name (final path
183-
segment of environment directory).
184-
185-
* ``__VENV_BIN_NAME__`` is replaced with the name of the bin directory
186-
(either ``bin`` or ``Scripts``).
187-
188-
* ``__VENV_PYTHON__`` is replaced with the absolute path of the
189-
environment's executable.
111+
Creators of third-party virtual environment tools will be free to use the
112+
provided ``EnvBuilder`` class as a base class.
113+
114+
The returned env-builder is an object which has a method, ``create``:
115+
116+
.. method:: create(env_dir)
117+
118+
This method takes as required argument the path (absolute or relative to
119+
the current directory) of the target directory which is to contain the
120+
virtual environment. The ``create`` method will either create the
121+
environment in the specified directory, or raise an appropriate
122+
exception.
123+
124+
The ``create`` method of the ``EnvBuilder`` class illustrates the hooks
125+
available for subclass customization::
126+
127+
def create(self, env_dir):
128+
"""
129+
Create a virtualized Python environment in a directory.
130+
env_dir is the target directory to create an environment in.
131+
"""
132+
env_dir = os.path.abspath(env_dir)
133+
context = self.create_directories(env_dir)
134+
self.create_configuration(context)
135+
self.setup_python(context)
136+
self.setup_scripts(context)
137+
self.post_setup(context)
138+
139+
Each of the methods :meth:`create_directories`,
140+
:meth:`create_configuration`, :meth:`setup_python`,
141+
:meth:`setup_scripts` and :meth:`post_setup` can be overridden.
142+
143+
.. method:: create_directories(env_dir)
144+
145+
Creates the environment directory and all necessary directories, and
146+
returns a context object. This is just a holder for attributes (such as
147+
paths), for use by the other methods.
148+
149+
.. method:: create_configuration(context)
150+
151+
Creates the ``pyvenv.cfg`` configuration file in the environment.
152+
153+
.. method:: setup_python(context)
154+
155+
Creates a copy of the Python executable (and, under Windows, DLLs) in
156+
the environment.
157+
158+
.. method:: setup_scripts(context)
159+
160+
Installs activation scripts appropriate to the platform into the virtual
161+
environment.
162+
163+
.. method:: post_setup(context)
164+
165+
A placeholder method which can be overridden in third party
166+
implementations to pre-install packages in the virtual environment or
167+
perform other post-creation steps.
168+
169+
In addition, :class:`EnvBuilder` provides this utility method that can be
170+
called from :meth:`setup_scripts` or :meth:`post_setup` in subclasses to
171+
assist in installing custom scripts into the virtual environment.
172+
173+
.. method:: install_scripts(context, path)
174+
175+
*path* is the path to a directory that should contain subdirectories
176+
"common", "posix", "nt", each containing scripts destined for the bin
177+
directory in the environment. The contents of "common" and the
178+
directory corresponding to :data:`os.name` are copied after some text
179+
replacement of placeholders:
180+
181+
* ``__VENV_DIR__`` is replaced with the absolute path of the environment
182+
directory.
183+
184+
* ``__VENV_NAME__`` is replaced with the environment name (final path
185+
segment of environment directory).
186+
187+
* ``__VENV_BIN_NAME__`` is replaced with the name of the bin directory
188+
(either ``bin`` or ``Scripts``).
189+
190+
* ``__VENV_PYTHON__`` is replaced with the absolute path of the
191+
environment's executable.
192+
193+
194+
There is also a module-level convenience function:
195+
196+
.. function:: create(env_dir, system_site_packages=False, clear=False, symlinks=False)
197+
198+
Create an :class:`EnvBuilder` with the given keyword arguments, and call its
199+
:meth:`~EnvBuilder.create` method with the *env_dir* argument.

0 commit comments

Comments
 (0)