[3.10] [doc] Refresh the venv introduction documentation, and correct… (GH-98466)

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: Phil Elson <pelson.pub@gmail.com>

Author: 3 people

Doc/library/venv.rst

@@ -15,74 +15,99 @@
 
 --------------
 
-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:
+
+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 information about Python virtual environments.
+See :pep:`405` for more background on Python virtual environments.
 
 .. seealso::
 
    `Python Packaging User Guide: Creating and using virtual environments
    <https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment>`__
 
-
 Creating virtual environments
 -----------------------------
 
 .. 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.
-
-   A virtual environment is a directory tree which contains Python executable
-   files and other files which indicate that it is a 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.
-
-   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).
-
-   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.
-
-   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``.
+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 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):
+
++-------------+------------+--------------------------------------------------+
+| 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` |
++-------------+------------+--------------------------------------------------+
+
+.. versionadded:: 3.4
+   :program:`!fish` and :program:`!csh` activation scripts.
+
+.. versionadded:: 3.8
+   PowerShell activation scripts installed under POSIX for PowerShell Core
+   support.
+
+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
@@ -98,6 +123,11 @@ Creating virtual environments
    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
@@ -183,11 +213,56 @@ creation according to their needs, the :class:`EnvBuilder` class.
 
     .. method:: ensure_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. The directories are allowed to
-        exist already, as long as either ``clear`` or ``upgrade`` were
-        specified to allow operating on an existing environment directory.
+        Creates the environment directory and all necessary subdirectories that
+        don't already exist, and returns a context object.  This context object
+        is just a holder for attributes (such as paths) for use by the other
+        methods.  If the :class:`EnvBuilder` is created with the arg
+        ``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>`
+           is used to construct the paths of the created directories.
 
     .. method:: create_configuration(context)
 

Doc/using/venv-create.inc

@@ -105,45 +105,3 @@ Multiple paths can be given to ``venv``, in which case an identical virtual
 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.