[3.11] [doc] Refresh the venv introduction documentation, and correct the st… (GH-98465)
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: Phil Elson <pelson.pub@gmail.com>
diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst
index 3bed256..adc6cd3 100644
--- a/Doc/library/venv.rst
+++ b/Doc/library/venv.rst
@@ -15,14 +15,22 @@
--------------
-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 (which
-matches the version of the binary that was used to create this environment) and
-can have its own independent set of installed Python packages in its site
-directories.
+.. _venv-def:
+.. _venv-intro:
-See :pep:`405` for more information about Python virtual environments.
+The :mod:`!venv` module supports creating lightweight "virtual environments",
+each with their own independent set of Python packages installed in
+their :mod:`site` directories.
+A virtual environment is created on top of an existing
+Python installation, known as the virtual environment's "base" Python, and may
+optionally be isolated from the packages in the base environment,
+so only those explicitly installed in the virtual environment are available.
+
+When used from within a virtual environment, common installation tools such as
+`pip`_ will install Python packages into a virtual environment
+without needing to be told to do so explicitly.
+
+See :pep:`405` for more background on Python virtual environments.
.. seealso::
@@ -36,54 +44,72 @@
.. include:: /using/venv-create.inc
+.. _venv-explanation:
-.. _venv-def:
+How venvs work
+--------------
-.. note:: A virtual environment is a Python environment such that the Python
- interpreter, libraries and scripts installed into it are isolated from those
- installed in other virtual environments, and (by default) any libraries
- installed in a "system" Python, i.e., one which is installed as part of your
- operating system.
+When a Python interpreter is running from a virtual environment,
+:data:`sys.prefix` and :data:`sys.exec_prefix`
+point to the directories of the virtual environment,
+whereas :data:`sys.base_prefix` and :data:`sys.base_exec_prefix`
+point to those of the base Python used to create the environment.
+It is sufficient to check
+``sys.prefix == sys.base_prefix`` to determine if the current interpreter is
+running from a virtual environment.
- A virtual environment is a directory tree which contains Python executable
- files and other files which indicate that it is a virtual environment.
+A virtual environment may be "activated" using a script in its binary directory
+(``bin`` on POSIX; ``Scripts`` on Windows).
+This will prepend that directory to your :envvar:`!PATH`, so that running
+:program:`!python` will invoke the environment's Python interpreter
+and you can run installed scripts without having to use their full path.
+The invocation of the activation script is platform-specific
+(:samp:`{<venv>}` must be replaced by the path to the directory
+containing the virtual environment):
- Common installation tools such as setuptools_ and pip_ work as
- expected with virtual environments. In other words, when a virtual
- environment is active, they install Python packages into the virtual
- environment without needing to be told to do so explicitly.
++-------------+------------+--------------------------------------------------+
+| Platform | Shell | Command to activate virtual environment |
++=============+============+==================================================+
+| POSIX | bash/zsh | :samp:`$ source {<venv>}/bin/activate` |
+| +------------+--------------------------------------------------+
+| | fish | :samp:`$ source {<venv>}/bin/activate.fish` |
+| +------------+--------------------------------------------------+
+| | csh/tcsh | :samp:`$ source {<venv>}/bin/activate.csh` |
+| +------------+--------------------------------------------------+
+| | PowerShell | :samp:`$ {<venv>}/bin/Activate.ps1` |
++-------------+------------+--------------------------------------------------+
+| Windows | cmd.exe | :samp:`C:\\> {<venv>}\\Scripts\\activate.bat` |
+| +------------+--------------------------------------------------+
+| | PowerShell | :samp:`PS C:\\> {<venv>}\\Scripts\\Activate.ps1` |
++-------------+------------+--------------------------------------------------+
- When a virtual environment is active (i.e., the virtual environment's Python
- interpreter is running), the attributes :attr:`sys.prefix` and
- :attr:`sys.exec_prefix` point to the base directory of the virtual
- environment, whereas :attr:`sys.base_prefix` and
- :attr:`sys.base_exec_prefix` point to the non-virtual environment Python
- installation which was used to create the virtual environment. If a virtual
- environment is not active, then :attr:`sys.prefix` is the same as
- :attr:`sys.base_prefix` and :attr:`sys.exec_prefix` is the same as
- :attr:`sys.base_exec_prefix` (they all point to a non-virtual environment
- Python installation).
+.. versionadded:: 3.4
+ :program:`!fish` and :program:`!csh` activation scripts.
- When a virtual environment is active, any options that change the
- installation path will be ignored from all :mod:`distutils` configuration
- files to prevent projects being inadvertently installed outside of the
- virtual environment.
+.. versionadded:: 3.8
+ PowerShell activation scripts installed under POSIX for PowerShell Core
+ support.
- When working in a command shell, users can make a virtual environment active
- by running an ``activate`` script in the virtual environment's executables
- directory (the precise filename and command to use the file is
- shell-dependent), which prepends the virtual environment's directory for
- executables to the ``PATH`` environment variable for the running shell. There
- should be no need in other circumstances to activate a virtual
- environment; scripts installed into virtual environments have a "shebang"
- line which points to the virtual environment's Python interpreter. This means
- that the script will run with that interpreter regardless of the value of
- ``PATH``. On Windows, "shebang" line processing is supported if you have the
- Python Launcher for Windows installed (this was added to Python in 3.3 - see
- :pep:`397` for more details). Thus, double-clicking an installed script in a
- Windows Explorer window should run the script with the correct interpreter
- without there needing to be any reference to its virtual environment in
- ``PATH``.
+You don't specifically *need* to activate a virtual environment,
+as you can just specify the full path to that environment's
+Python interpreter when invoking Python.
+Furthermore, all scripts installed in the environment
+should be runnable without activating it.
+
+In order to achieve this, scripts installed into virtual environments have
+a "shebang" line which points to the environment's Python interpreter,
+i.e. :samp:`#!/{<path-to-venv>}/bin/python`.
+This means that the script will run with that interpreter regardless of the
+value of :envvar:`!PATH`. On Windows, "shebang" line processing is supported if
+you have the :ref:`launcher` installed. Thus, double-clicking an installed
+script in a Windows Explorer window should run it with the correct interpreter
+without the environment needing to be activated or on the :envvar:`!PATH`.
+
+When a virtual environment has been activated, the :envvar:`!VIRTUAL_ENV`
+environment variable is set to the path of the environment.
+Since explicitly activating a virtual environment is not required to use it,
+:envvar:`!VIRTUAL_ENV` cannot be relied upon to determine
+whether a virtual environment is being used.
.. warning:: Because scripts installed in environments should not expect the
environment to be activated, their shebang lines contain the absolute paths
@@ -99,6 +125,11 @@
environment in its new location. Otherwise, software installed into the
environment may not work as expected.
+You can deactivate a virtual environment by typing ``deactivate`` in your shell.
+The exact mechanism is platform-specific and is an internal implementation
+detail (typically, a script or shell function will be used).
+
+
.. _venv-api:
API
@@ -191,6 +222,45 @@
``clear=True``, contents of the environment directory will be cleared
and then all necessary subdirectories will be recreated.
+ The returned context object is a :class:`types.SimpleNamespace` with the
+ following attributes:
+
+ * ``env_dir`` - The location of the virtual environment. Used for
+ ``__VENV_DIR__`` in activation scripts (see :meth:`install_scripts`).
+
+ * ``env_name`` - The name of the virtual environment. Used for
+ ``__VENV_NAME__`` in activation scripts (see :meth:`install_scripts`).
+
+ * ``prompt`` - The prompt to be used by the activation scripts. Used for
+ ``__VENV_PROMPT__`` in activation scripts (see :meth:`install_scripts`).
+
+ * ``executable`` - The underlying Python executable used by the virtual
+ environment. This takes into account the case where a virtual environment
+ is created from another virtual environment.
+
+ * ``inc_path`` - The include path for the virtual environment.
+
+ * ``lib_path`` - The purelib path for the virtual environment.
+
+ * ``bin_path`` - The script path for the virtual environment.
+
+ * ``bin_name`` - The name of the script path relative to the virtual
+ environment location. Used for ``__VENV_BIN_NAME__`` in activation
+ scripts (see :meth:`install_scripts`).
+
+ * ``env_exe`` - The name of the Python interpreter in the virtual
+ environment. Used for ``__VENV_PYTHON__`` in activation scripts
+ (see :meth:`install_scripts`).
+
+ * ``env_exec_cmd`` - The name of the Python interpreter, taking into
+ account filesystem redirections. This can be used to run Python in
+ the virtual environment.
+
+
+ .. versionchanged:: 3.12
+ The attribute ``lib_path`` was added to the context, and the context
+ object was documented.
+
.. versionchanged:: 3.11
The *venv*
:ref:`sysconfig installation scheme <installation_paths>`
diff --git a/Doc/using/venv-create.inc b/Doc/using/venv-create.inc
index b978583..b929705 100644
--- a/Doc/using/venv-create.inc
+++ b/Doc/using/venv-create.inc
@@ -105,45 +105,3 @@
environment will be created, according to the given options, at each provided
path.
-Once a virtual environment has been created, it can be "activated" using a
-script in the virtual environment's binary directory. The invocation of the
-script is platform-specific (`<venv>` must be replaced by the path of the
-directory containing the virtual environment):
-
-+-------------+-----------------+-----------------------------------------+
-| Platform | Shell | Command to activate virtual environment |
-+=============+=================+=========================================+
-| POSIX | bash/zsh | $ source <venv>/bin/activate |
-+-------------+-----------------+-----------------------------------------+
-| | fish | $ source <venv>/bin/activate.fish |
-+-------------+-----------------+-----------------------------------------+
-| | csh/tcsh | $ source <venv>/bin/activate.csh |
-+-------------+-----------------+-----------------------------------------+
-| | PowerShell Core | $ <venv>/bin/Activate.ps1 |
-+-------------+-----------------+-----------------------------------------+
-| Windows | cmd.exe | C:\\> <venv>\\Scripts\\activate.bat |
-+-------------+-----------------+-----------------------------------------+
-| | PowerShell | PS C:\\> <venv>\\Scripts\\Activate.ps1 |
-+-------------+-----------------+-----------------------------------------+
-
-When a virtual environment is active, the :envvar:`VIRTUAL_ENV` environment
-variable is set to the path of the virtual environment. This can be used to
-check if one is running inside a virtual environment.
-
-You don't specifically *need* to activate an environment; activation just
-prepends the virtual environment's binary directory to your path, so that
-"python" invokes the virtual environment's Python interpreter and you can run
-installed scripts without having to use their full path. However, all scripts
-installed in a virtual environment should be runnable without activating it,
-and run with the virtual environment's Python automatically.
-
-You can deactivate a virtual environment by typing "deactivate" in your shell.
-The exact mechanism is platform-specific and is an internal implementation
-detail (typically a script or shell function will be used).
-
-.. versionadded:: 3.4
- ``fish`` and ``csh`` activation scripts.
-
-.. versionadded:: 3.8
- PowerShell activation scripts installed under POSIX for PowerShell Core
- support.
