rst fixups

python · rickeylev · Jun 27, 2025 · Jun 28, 2025 · Jun 28, 2025 · Jun 28, 2025
commit a0c2529c371faa91154279fc37f7593cb702938f
@@ -20,7 +20,7 @@ This PEP describes how a Python virtual environment can be configured
 to allow copying it as-is to different hosts and still have a functioning
 virtual environment. Making this work consists of two main pieces:
 
-* Using a relative path for `home` in `pyvenv.cfg`, which Python canonicalizes
+* Using a relative path for ``home`` in ``pyvenv.cfg``, which Python canonicalizes
   at runtime.
 * Having package installers recognize a host-relocatable venv and generate
   appropriate outputs, e.g. script wrappers.
@@ -29,16 +29,16 @@ virtual environment. Making this work consists of two main pieces:
 Motivation
 ==========
 
-There are two main motivations for allowing relative paths in `pyvenv.cfg`
+There are two main motivations for allowing relative paths in ``pyvenv.cfg``
 and thus enabling host-relocatable virtual environments.
 
-First, it is currently proscribed that the `home` value in `pyvenv.cfg` be an
+First, it is currently proscribed that the ``home`` value in ``pyvenv.cfg`` be an
 absolute path. The behavior of relative paths is unspecified.
 While techniques exist to work around this for every other
 sub-part of a virtual environment, the one remaining part without a teneable
-solution is how the Python runtime itself finds `PYTHONHOME`. This is because,
-currently, the startup process requires absolute paths be used for the `home`
-key in `pyvenv.cfg`. If a relative path is used, behavior is unspecified
+solution is how the Python runtime itself finds ``PYTHONHOME``. This is because,
+currently, the startup process requires absolute paths be used for the ``home``
+key in ``pyvenv.cfg``. If a relative path is used, behavior is unspecified
 (currently, it is relative to the process's current working directory, making
 it untenable to use).
 
@@ -77,38 +77,38 @@ Python Runtime Changes
 
 The Python runtime itself *almost* already supports host-relocating virtual
 environment and the only change needed is to define how it resolves relative
-paths for `home` in `pyvenv.cfg`.
+paths for ``home`` in ``pyvenv.cfg``.
 
 Today, relative paths resolve relative to the process's current working
 directory. Because CWD isn't knowable in advance, it makes relative paths today
 effective impossible.
 
-Instead, the paths should be relative to the location of the `pyvenv.cfg` file.
+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 file
 also has to know where the Python runtime is, so can easily calculate the
-correct relative path. For tools that read the `pyvenv.cfg`, it is also easy
-to simple join the directory name of where `pyvenv.cfg` was found with the
+correct relative path. For tools that read the ``pyvenv.cfg``, it is also easy
+to simple join the directory name of where ``pyvenv.cfg`` was found with the
 path in the config file. When a person reads the config file, they can do
 similar, which is a lower cognitive burden and helps avoids the question of
 "relative to what?"
 
 This change is only a couple of lines in the start up code. Specifically, when
-parsing the `pyvenv.cfg` file and finding the `home` value, it just needs to
+parsing the ``pyvenv.cfg`` file and finding the ``home`` value, it just needs to
 be checked if it's already absolute. If not, then join to the directory name
-of the `pyvenv.cfg` file. The code alredy knows the directory and has helpers
+of the ``pyvenv.cfg`` file. The code alredy knows the directory and has 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>`__
 
 Virtual Environment Tool Changes
 ================================
 
 Virtual environment management tools should support a mechanism to generate
-a `pyvenv.cfg` file with a `home` key that is a relative path to the relevant
+a ``pyvenv.cfg`` file with a ``home`` key that is a relative path to the relevant
 Python installation.
 
-For the standard library's `venv` module, the flag `--relative` will be added
+For the standard library's ``venv`` module, the flag ``--relative`` will be added
 to trigger this behavior.
 
 Package Installer Changes
@@ -118,8 +118,8 @@ Package installers must be aware of when a relative virtual environment has
 been defined so they can avoid using absolute paths. The two main places
 absolute paths occur today are:
 
-1. `bin/` scripts, where shebangs are rewritten.
-2. `site-packages` symlinks.
+1. ``bin/`` scripts, where shebangs are rewritten.
+2. ``site-packages`` symlinks.
 
 Instead, they should create relative symlinks pointing to the actual
 installation directory for packages.
@@ -129,7 +129,7 @@ Relocating a Venv to Another Host
 =================================
 
 Copying the venv to another host is simple: copy the venv directory itself, the
-relative location `home` points to, and preserve the relative directory
+relative location ``home`` points to, and preserve the relative directory
 structures.
 
 In practice, this typically means copying a parent directory of the virtual
@@ -139,16 +139,16 @@ the group of virtual environments to relocate.
 Backwards Compatibility
 =======================
 
-Because relative paths for `home` aren't usable in practice, and their
+Because relative paths for ``home`` aren't usable in practice, and their
 behavior undocumented and unspecified, there shouldn't be any backward
 compatibility concerns.
 
 
 How to Teach This
 =================
 
-Teaching this should be simple: if you use a relative path in `pyvenv.cfg`,
-then it's relative to the directory containing the `pyvenv.cfg` file. This
+Teaching this should be simple: 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.
 
 
@@ -157,7 +157,7 @@ Reference Implementation
 
 A reference implementation is available by using the combination of:
 
-* Python runtime from [rickeylev/feat.relative.pyvenv.home](https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home)
+* Python runtime from `rickeylev/feat.relative.pyvenv.home <https://github.com/python/cpython/compare/main...rickeylev:cpython:feat.relative.pyvenv.home>`__
 * rules_python with (todo: alterations to use cpython build as in-build
   runtime)
 
@@ -169,14 +169,15 @@ todo: list any that are brought up and unresolved
 Footnotes
 =========
 
-* [rules_python](https://github.com/bazel-contrib/rules_python): implements
+* `rules_python <https://github.com/bazel-contrib/rules_python>`__: implements
   host-relocatable virtual environments.
-* [rules_py](https://github.com/aspect-build/rules_py): implements
+* `rules_py <https://github.com/aspect-build/rules_py>`__: implements
   host-relocatable virtual environments.
-* [`uv venv
-  relocatable`](https://docs.astral.sh/uv/reference/cli/#uv-venv--relocatable):
+* `uv venv
+  relocatable
+  <https://docs.astral.sh/uv/reference/cli/#uv-venv--relocatable>`__:
   implements same-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>`__:
   A relocatable Python runtime.
 
 
@@ -186,17 +187,17 @@ Rejected Ideas
 Relative to virtual env root
 ----------------------------
 
-Having the `home` value in `pyvenv.cfg` relative to the virtual environments
+Having the ``home`` value in ``pyvenv.cfg`` relative to the virtual environments
 root directory would work just as well, but this idea is rejected because it
 requires additional effort to compute the virtual env root.
 
-Unspecified `home` means to dynamically compute home
+Unspecified home means to dynamically compute home
 ----------------------------------------------------
 
-Today, if a `pyvenv.cfg` file doesn't set `home`, the runtime will try to
+Today, if a ``pyvenv.cfg`` file doesn't set ``home``, the runtime will try to
 dynamically compute it by checking if the current executable (which is typicall
-the venv's `bin/python3` symlink) is a symlink and, if so, use where that
-points as `PYTHONHOME`.
+the venv's ``bin/python3`` symlink) is a symlink and, if so, use where that
+points as ``PYTHONHOME``.
 
 This behavior is undesirable for a couple reasons: