Merge branch 'relative.venvs' of https://github.com/rickeylev/peps into relative.venvs

Author: rickeylev

peps/pep-0796.rst

@@ -8,8 +8,6 @@ Type: Standards Track
 Created: 26-Jun-2025
 Python-Version: 3.15
 
-.. highlight:: rst
-
 
 Abstract
 ========
@@ -42,7 +40,7 @@ requirement should be relaxed and relative path behavior allowed and defined.
 
 Second, such relative paths are a building block to enable portable virtual
 environments, i.e. copying a virtual environment as-is between hosts of
-compatible platforms. Portable venvs are appealing because virtual environments
+compatible platforms. Portable virtual environments are appealing because virtual environments
 are a popular mechanism for running Python applications. This provides several
 benefits:
 
@@ -60,7 +58,7 @@ host that intends to run the program.
 When the virtual environment doesn't require modifications to be usable, it
 also allows more advanced deployment mechanisms, e.g. remote mounting and
 caching of artifacts. While this PEP on its own isn't sufficient to enable
-that, it allows tools like ``bazel`` or ``venvstacks`` to more easily prepare
+that, it allows tools like Bazel or venvstacks to more easily prepare
 constrained environments that allow for such use cases.
 
 Rationale
@@ -75,10 +73,10 @@ so other hook points (e.g. ``site`` initialization) never trigger.
 
 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
+(Bazel, omitting the ``home`` key entirely to trigger an implementation
 dependent fallback to resolving via a symlinked interpreter binary on
 non-Windows systems) or by requiring a post-installation script to be executed
-after the environment is placed in its target location (``venvstacks``).
+after the environment is placed in its target location (venvstacks).
 
 Specification
 =============
@@ -87,10 +85,10 @@ The ``home`` value in ``pyvenv.cfg`` is permitted to use a relative path value.
 These may contain up-references outside of the virtual environment root
 directory.  Examples:
 
-* ``subdir/whatever/bin`` (a directory within the virtual environment).
+* ``subdir/whatever/bin`` (a directory within the virtual environment)
 * ``./subdir/whatever/bin`` (same as above)
 * ``../../../../../elsewhere/runtime/bin`` (a directory outside the virtual
-  environment).
+  environment)
 
 Relative paths are relative to the directory containing ``pyvenv.cfg``. During
 interpreter startup (i.e. ``getpath.py``), the relative path is joined to the
@@ -134,14 +132,14 @@ helpers already present for checking if a path is absolute and joining two
 paths.
 
 A proof-of-concept of this is implemented in
-`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
 =======================
 
 
-Tools that work around the absolute ``home`` key limitation the way ``bazel``
-and ``venvstacks`` currently do (omitting the ``home`` key, or editing it after
+Tools that work around the absolute ``home`` key limitation the way Bazel
+and venvstacks currently do (omitting the ``home`` key, or editing it after
 moving the environment) will be unaffected.
 
 While the PEP author and sponsor aren't aware of any projects that work around
@@ -159,9 +157,10 @@ accordingly.
 How to Teach This
 =================
 
-Teaching this should be simple: if you use a relative path in ``pyvenv.cfg``,
+Teaching this should be straightforward: if you use a relative path in ``pyvenv.cfg``,
 then it's relative to the directory containing the ``pyvenv.cfg`` file. This
-is simple to explain and understand.
+is simple to explain and easy to understand for anyone that is already familiar
+with handling relative filesystem paths.
 
 
 Reference Implementation
@@ -189,12 +188,12 @@ References
   host-relocatable virtual environments.
 * `rules_py <https://github.com/aspect-build/rules_py>`__: implements
   host-relocatable virtual environments.
-* `python-build-standalone <https://github.com/astral-sh/python-build-standalone>`__:
+* `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 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>`__
+* `gh-136051: relative pyvenv.cfg home <https://github.com/python/cpython/issues/136051>`__
 
 Rejected Ideas
 =====================