Update documentation

Signed-off-by: Filipe Laíns <[email protected]>

Author: FFY00

Doc/c-api/init_config.rst

@@ -1588,9 +1588,22 @@ If a ``._pth`` file is present:
 * Set :c:member:`~PyConfig.site_import` to ``0``.
 * Set :c:member:`~PyConfig.safe_path` to ``1``.
 
+If :c:member:`~PyConfig.home` is not set and a ``pyvenv.cfg`` file is present in
+the same directory as :c:member:`~PyConfig.executable`, or its parent,
+:c:member:`~PyConfig.prefix` and :c:member:`~PyConfig.exec_prefix` are set that
+location. When this happens, :c:member:`~PyConfig.base_prefix` and
+:c:member:`~PyConfig.base_exec_prefix` still keep their value, pointing to the
+base installation. See :ref:`sys-path-init-virtual-environments` for more
+information.
+
 The ``__PYVENV_LAUNCHER__`` environment variable is used to set
 :c:member:`PyConfig.base_executable`.
 
+.. versionchanged:: 3.14
+
+   :c:member:`~PyConfig.prefix`, and :c:member:`~PyConfig.exec_prefix` are now
+   set to the ``pyvenv.cfg`` directory. This was previously done by :mod:`site`,
+   therefore affected by :option:`-S`.
 
 PyInitConfig C API
 ==================

Doc/library/site.rst

@@ -49,14 +49,22 @@ added path for configuration files.
    identified by the "t" suffix in the version-specific directory name, such as
    :file:`lib/python3.13t/`.
 
-If a file named "pyvenv.cfg" exists one directory above sys.executable,
-sys.prefix and sys.exec_prefix are set to that directory and
-it is also checked for site-packages (sys.base_prefix and
-sys.base_exec_prefix will always be the "real" prefixes of the Python
-installation). If "pyvenv.cfg" (a bootstrap configuration file) contains
-the key "include-system-site-packages" set to anything other than "true"
-(case-insensitive), the system-level prefixes will not be
-searched for site-packages; otherwise they will.
+.. versionchanged:: 3.14
+
+   :mod:`site` is no longer responsible for updating :data:`sys.prefix` and
+   :data:`sys.exec_prefix` on :ref:`sys-path-init-virtual-environments`. This is
+   now done during the :ref:`path initialization <sys-path-init>`. As a result,
+   under :ref:`sys-path-init-virtual-environments`, :data:`sys.prefix` and
+   :data:`sys.exec_prefix` no longer depend on the :ref:`site` initialization,
+   and are therefore unaffected by :option:`-S`.
+
+.. _site-virtual-environments-configuration:
+
+When running under a :ref:`virtual environment <sys-path-init-virtual-environments>`,
+the ``pyvenv.cfg`` file in :data:`sys.prefix` is checked for site-specific
+configurations. If the ``include-system-site-packages`` key exists and is set to
+``true`` (case-insensitive), the system-level prefixes will be searched for
+site-packages, otherwise they won't.
 
 .. index::
    single: # (hash); comment

Doc/library/sys.rst

@@ -130,27 +130,26 @@ always available.
 
 .. data:: base_exec_prefix
 
-   Set during Python startup, before ``site.py`` is run, to the same value as
-   :data:`exec_prefix`. If not running in a
-   :ref:`virtual environment <venv-def>`, the values will stay the same; if
-   ``site.py`` finds that a virtual environment is in use, the values of
-   :data:`prefix` and :data:`exec_prefix` will be changed to point to the
-   virtual environment, whereas :data:`base_prefix` and
-   :data:`base_exec_prefix` will remain pointing to the base Python
-   installation (the one which the virtual environment was created from).
+   Equivalent to :data:`exec_prefix`, but refering to the base Python installation.
+
+   When running under :ref:`sys-path-init-virtual-environments`,
+   :data:`exec_prefix` gets overwritten to the virtual environment prefix.
+   :data:`base_exec_prefix`, conversely, does not change, and always points to
+   the base Python installation.
+   Refer to :ref:`sys-path-init-virtual-environments` for more information.
 
    .. versionadded:: 3.3
 
 
 .. data:: base_prefix
 
-   Set during Python startup, before ``site.py`` is run, to the same value as
-   :data:`prefix`. If not running in a :ref:`virtual environment <venv-def>`, the values
-   will stay the same; if ``site.py`` finds that a virtual environment is in
-   use, the values of :data:`prefix` and :data:`exec_prefix` will be changed to
-   point to the virtual environment, whereas :data:`base_prefix` and
-   :data:`base_exec_prefix` will remain pointing to the base Python
-   installation (the one which the virtual environment was created from).
+   Equivalent to :data:`prefix`, but refering to the base Python installation.
+
+   When running under :ref:`virtual environment <venv-def>`,
+   :data:`prefix` gets overwritten to the virtual environment prefix.
+   :data:`base_prefix`, conversely, does not change, and always points to
+   the base Python installation.
+   Refer to :ref:`sys-path-init-virtual-environments` for more information.
 
    .. versionadded:: 3.3
 
@@ -483,11 +482,19 @@ always available.
 
    .. note::
 
-      If a :ref:`virtual environment <venv-def>` is in effect, this
-      value will be changed in ``site.py`` to point to the virtual environment.
-      The value for the Python installation will still be available, via
-      :data:`base_exec_prefix`.
+      If a :ref:`virtual environment <venv-def>` is in effect, this :data:`exec_prefix`
+      will point to the virtual environment. The value for the Python installation
+      will still be available, via :data:`base_exec_prefix`.
+      Refer to :ref:`sys-path-init-virtual-environments` for more information.
 
+   .. versionchanged:: 3.14
+
+      When running under a :ref:`virtual environment <venv-def>`,
+      :data:`prefix` and :data:`exec_prefix` are now set to the virtual
+      environment prefix by the :ref:`path initialization <sys-path-init>`,
+      instead of :mod:`site`. This means that :data:`prefix` and
+      :data:`exec_prefix` always point to the virtual environment, even when
+      :mod:`site` is disabled (:option:`-S`).
 
 .. data:: executable
 
@@ -1483,10 +1490,21 @@ always available.
    argument to the :program:`configure` script.  See
    :ref:`installation_paths` for derived paths.
 
-   .. note:: If a :ref:`virtual environment <venv-def>` is in effect, this
-      value will be changed in ``site.py`` to point to the virtual
-      environment. The value for the Python installation will still be
-      available, via :data:`base_prefix`.
+   .. note::
+
+      If a :ref:`virtual environment <venv-def>` is in effect, this :data:`prefix`
+      will point to the virtual environment. The value for the Python installation
+      will still be available, via :data:`base_prefix`.
+      Refer to :ref:`sys-path-init-virtual-environments` for more information.
+
+   .. versionchanged:: 3.14
+
+      When running under a :ref:`virtual environment <venv-def>`,
+      :data:`prefix` and :data:`exec_prefix` are now set to the virtual
+      environment prefix by the :ref:`path initialization <sys-path-init>`,
+      instead of :mod:`site`. This means that :data:`prefix` and
+      :data:`exec_prefix` always point to the virtual environment, even when
+      :mod:`site` is disabled (:option:`-S`).
 
 
 .. data:: ps1

Doc/library/sys_path_init.rst

@@ -47,8 +47,15 @@ however on other platforms :file:`lib/python{majorversion}.{minorversion}/lib-dy
 ``exec_prefix``. On some platforms :file:`lib` may be :file:`lib64` or another value,
 see :data:`sys.platlibdir` and :envvar:`PYTHONPLATLIBDIR`.
 
-Once found, ``prefix`` and ``exec_prefix`` are available at :data:`sys.prefix` and
-:data:`sys.exec_prefix` respectively.
+Once found, ``prefix`` and ``exec_prefix`` are available at
+:data:`sys.base_prefix` and :data:`sys.base_exec_prefix` respectively.
+
+If :envvar:`PYTHONHOME` is not set, and a ``pyvenv.cfg`` file is found alongside
+the main executable, or in its parent directory, :data:`sys.prefix` and
+:data:`sys.exec_prefix` get set to the directory containing ``pyvenv.cfg``,
+otherwise they are set to the same value as :data:`sys.base_prefix` and
+:data:`sys.base_exec_prefix`, respectively.
+This is used by :ref:`sys-path-init-virtual-environments`.
 
 Finally, the :mod:`site` module is processed and :file:`site-packages` directories
 are added to the module search path. A common way to customize the search path is
@@ -60,18 +67,40 @@ the :mod:`site` module documentation.
    Certain command line options may further affect path calculations.
    See :option:`-E`, :option:`-I`, :option:`-s` and :option:`-S` for further details.
 
-Virtual environments
+.. versionchanged:: 3.14
+
+   :data:`sys.prefix` and :data:`sys.exec_prefix` are now set to the
+   ``pyvenv.cfg`` directory during the path initialization. This was previously
+   done by :mod:`site`, therefore affected by :option:`-S`.
+
+.. _sys-path-init-virtual-environments:
+
+Virtual Environments
 --------------------
 
-If Python is run in a virtual environment (as described at :ref:`tut-venv`)
-then ``prefix`` and ``exec_prefix`` are specific to the virtual environment.
+Virtual environments place a ``pyvenv.cfg`` file in their prefix, which causes
+:data:`sys.prefix` and :data:`sys.exec_prefix` to point to them, instead of the
+base installation.
+
+The ``prefix`` and ``exec_prefix`` values of the base installation are available
+at :data:`sys.base_prefix` and :data:`sys.base_exec_prefix`.
 
-If a ``pyvenv.cfg`` file is found alongside the main executable, or in the
-directory one level above the executable, the following variations apply:
+As well as being used as a marker to identify virtual environments,
+``pyvenv.cfg`` may also be used to configure the :mod:`site` initialization.
+Please refer to :mod:`site`'s
+:ref:`virtual environments documentation <site-virtual-environments-configuration>`.
+
+.. note::
+
+   :envvar:`PYTHONHOME` overrides the ``pyvenv.cfg`` detection.
+
+.. note::
 
-* If ``home`` is an absolute path and :envvar:`PYTHONHOME` is not set, this
-  path is used instead of the path to the main executable when deducing ``prefix``
-  and ``exec_prefix``.
+   There are other ways how "virtual environments" could be implemented, this
+   documentation referes implementations based on the ``pyvenv.cfg`` mechanism,
+   such as :mod:`venv`. Most virtual environment implementations follow the
+   model set by :mod:`venv`, but there may be exotic implementations that
+   diverge from it.
 
 _pth files
 ----------

Doc/library/venv.rst

@@ -25,6 +25,9 @@ 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.
+See :ref:`sys-path-init-virtual-environments` and :mod:`site`'s
+:ref:`virtual environments documentation <site-virtual-environments-configuration>`
+for more information.
 
 When used from within a virtual environment, common installation tools such as
 :pypi:`pip` will install Python packages into a virtual environment