gh-94214: Add venv context.lib_path and document the context (GH-94221)

Author: pfmoore

Doc/library/venv.rst

@@ -177,6 +177,45 @@ creation according to their needs, the :class:`EnvBuilder` class.
         ``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>`

Lib/venv/__init__.py

@@ -138,6 +138,7 @@ def create_if_needed(d):
 
         context.inc_path = incpath
         create_if_needed(incpath)
+        context.lib_path = libpath
         create_if_needed(libpath)
         # Issue 21197: create lib64 as a symlink to lib on 64-bit non-OS X POSIX
         if ((sys.maxsize > 2**32) and (os.name == 'posix') and

Misc/NEWS.d/next/Library/2022-06-24-14-25-26.gh-issue-94214.03pXR5.rst

@@ -0,0 +1 @@
+Document the ``context`` object used in the ``venv.EnvBuilder`` class, and add the new environment's library path to it.