Apply markup and simple grammar fixes from code review

Co-authored-by: Hugo van Kemenade <[email protected]>
python · rickeylev · Jun 27, 2025 · Jun 28, 2025 · Jun 28, 2025 · Jun 28, 2025
commit ae5a67f971c43ccc4e1aa26b96ea11f1b444702a
@@ -27,19 +27,18 @@ Motivation
 The ``home`` field in :file:`pyvenv.cfg` is used on interpreter startup to
 determine the actual Python interpreter installation that is used to execute
 code in that virtual environment. Currently, this path is required to be
-absolute for correct virtual environment operation because the original
-`PEP 405 <https://peps.python.org/pep-0405/>`__
+absolute for consistent virtual environment operation (the original :pep:`405`
 specifying virtual environments didn't cover any specific way of processing
-relative paths, their behaviour is implementation dependent. CPython releases
+relative paths, so their behaviour is implementation dependent). CPython releases
 up to and including CPython 3.14 resolve them relative to the current process
 working directory, making them too unreliable to use in practice.
 
 The reason to support a relative path is to support portable virtual
 environments, which rely on using a host-agnostic relative path to point to
-``PYTHONHOME``.
+:envvar:`PYTHONHOME`.
 A portable virtual environment is one that can be moved between
 platform-compatible hosts, which is an important feature for some projects (see
-"Why portable environments matter").
+`Why portable virtual environments matter`_).
 
 The reason support for a relative ``home`` path needs to be
 in the interpreter itself is because locating ``PYTHONHOME`` happens
@@ -52,10 +51,9 @@ Tools that currently look to enable virtual environment portability across
 machines do so either by relying on undocumented interpreter behaviour
 (Bazel, omitting the ``home`` key entirely to trigger an implementation
 dependent fallback to resolving via a symlinked interpreter binary on
-non-Windows systems, see `gh-135773`) or by requiring a post-installation script to be executed
-after the environment is placed in its target location (
-`venvstacks <https://lmstudio.ai/blog/venvstacks#publishing-environment-layer-archives>`__
-).
+non-Windows systems, see :cpython-issue:`135773`) or by requiring a post-installation script to be executed
+after the environment is placed in its target location (`venvstacks
+<https://lmstudio.ai/blog/venvstacks#publishing-environment-layer-archives>`__).
 
 While this PEP on its own isn't sufficient to enable portable virtual
 environments, it allows tools like Bazel or venvstacks to more easily prepare
@@ -67,7 +65,7 @@ Why portable virtual environments matter
 Portable virtual environments are important for the efficiency and
 reproducibility benefits they bring from being created once and reused multiple
 times later in different locations. For example, a build farm can build a
-virtual environment once, cache it, and then re-use it as-is to CI jobs.
+virtual environment once, cache it, and then re-use it as-is to run CI jobs.
 
 
 Rationale
@@ -105,12 +103,12 @@ a path of their choosing. Given a known anchor point, it's easy to transform a
 relative path to an absolute path and still retain predictable and reliable
 behavior that produces correct values.
 
-Fullying designing portable virtual environments
-------------------------------------------------
+Deferring the design of fully portable virtual environments
+-----------------------------------------------------------
 
 This PEP purposely only focuses on the interpreter startup behavior to limit
 its scope. There are multiple implementations and many design questions for how
-to implement portable virtual environments work (e.g. what installers should
+to fully implement portable virtual environments (e.g. what installers should
 do), but they are separate from the Python runtime initialization phase.
 
 
@@ -151,7 +149,7 @@ relative paths for ``home`` in ``pyvenv.cfg``.
 
 Currently, relative paths resolve relative to the process's current working
 directory. Because the current working directory isn't knowable in advance, it
-makes relative paths today effectively impossible.
+makes using relative paths today effectively impossible.
 
 Instead, the paths should be relative to the location of the ``pyvenv.cfg``
 file. This file is chosen as the anchor point because the tool that creates the
@@ -170,7 +168,8 @@ helpers already exist for checking if a path is absolute and joining two
 paths.
 
 A proof-of-concept of this is implemented in the author's branch,
-`rickeylev/feat.relative.pyvenv.home <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__.
+`rickeylev/feat.relative.pyvenv.home
+<https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__.
 
 Backwards Compatibility
 =======================
@@ -198,7 +197,7 @@ location of the virtual environment. This *could* point to a surprising,
 potentially malicious, location.
 
 However, this risk already exists today because a relative path isn't
-_rejected_, but resolved relative to the current working directory. This PEP
+*rejected*, but resolved relative to the current working directory. This PEP
 just changes the anchor point to ``pyvenv.cfg`` itself.
 
 Similarly, the same concern exists for absolute paths. The two are
@@ -248,11 +247,9 @@ portable virtual environment
   host-relocatable virtual environments.
 * `python-build-standalone <https://github.com/astral-sh/python-build-standalone>`__
 * `venvstacks <https://pypi.org/project/venvstacks/>`__: a tool for creating
-  reproducible distribution artifacts from virtual environments A relocatable
+  reproducible distribution artifacts from virtual environments. A relocatable
   Python runtime.
-* `PoC for relative home in Python startup <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__
 * `Python Ideas "Making venvs relocatable friendly" discussion <https://discuss.python.org/t/making-venvs-relocatable-friendly/96177>`__
-* `gh-136051: relative pyvenv.cfg home <https://github.com/python/cpython/issues/136051>`__
 
 Rejected Ideas
 ==============