better answer why/how relvenvs help; wrap some long lines

python · rickeylev · Jun 27, 2025 · Jun 28, 2025 · Jun 28, 2025 · Jun 28, 2025
commit 5cbc9f57b7d7717d7530d8363587b3af3aeed164
@@ -40,15 +40,20 @@ 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 virtual environments are appealing because virtual environments
-are a popular mechanism for running Python applications. This provides several
+compatible platforms. For example, by pointing to a parent directory, the
+virtual environment becomes independent of path prefix differences between
+hosts (e.g. ``/usr/local/`` in a container vs
+``/home/user/.pyenv/versions/3.12.0/bin`` in a user's dev environment).
+
+Portable virtual environments are appealing because virtual environments are a
+popular mechanism for running Python applications. This provides several
 benefits:
 
 * The closer the development environment is to the non-development environment,
-  the more reliable software can be achieved, and the easier it is to reproduce
-  issues
-* The simpler the process of re-creating the environment, the more reliable
-  software can be achieved, and the faster the process can be.
+  environment-specific issues are less likely, and the easier it is to
+  reproduce issues.
+* The simpler the process of re-creating the environment, environment-specific
+  issues are less likely, and the faster the process can be.
 
 Making it simpler to copy a virtual environment from one host to another
 mitigates these categories of problems. Additionally, the development tools to
@@ -157,10 +162,10 @@ accordingly.
 How to Teach This
 =================
 
-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 easy to understand for anyone that is already familiar
-with handling relative filesystem paths.
+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 easy to understand for
+anyone that is already familiar with handling relative filesystem paths.
 
 
 Reference Implementation
@@ -189,8 +194,9 @@ References
 * `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>`__
-* `venvstacks <https://pypi.org/project/venvstacks/>`__: a tool for creating reproducible distribution artifacts from virtual environments
-  A relocatable Python runtime.
+* `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>`__