PEP 394: Keep version agnostic shebang recommendation

This update reverts back to the version agnostic "python" invocation as the default recommendation for developers, and rewords the rest of the PEP accordingly. In particular, it makes it clear that publishers are free to adopt the attitude of "we assume you are using a virtual environment", while at the same time granting the distributors the freedom they need to make software with the expectation work correctly when run directly against a system Python installation.
python · warsaw · Jul 5, 2019 · Apr 12, 2019 · Apr 12, 2019 · Apr 15, 2019
commit 268e96d192ded6ef8431b58d2df69dbbea26cd18
diff --git a/pep-0394.txt b/pep-0394.txt
@@ -78,23 +78,42 @@ For distributors
 For developers
 --------------
 
-* In order to tolerate differences across platforms, new code that needs
-  to invoke the Python interpreter should not specify ``python``, but rather
-  should specify either ``python3`` or ``python2`` (or the more specific
-  ``python3.x`` and ``python2.x`` versions; see the `Migration Notes`_).
-  This distinction should be made in shebangs, when invoking from a shell
-  script, when invoking via the system() call, or when invoking in any other
-  context.
 * When reinvoking the interpreter from a Python script, querying
   ``sys.executable`` to avoid hardcoded assumptions regarding the
   interpreter location remains the preferred approach.
-* Scripts that are deliberately written to be source compatible with both
-  Python 3.x and 2.x should use ``python3`` on their shebang line
-  (see `Rationale`_ for details).
-* One exception to this is scripts that are deliberately written to be used
-  on an “*old system*” where ``python3`` (or even ``python2``) is not available
-  (such as the default Python installed on macOS or RHEL 6).
-  Such scripts may continue to use ``python`` on their shebang line.
+* While far from being universally available, ``python`` remains the
+  preferred spelling for explicitly invoking Python, as this is the
+  spelling that virtual environments make consistently available
+  across different platforms and Python installations.
+* In shebang lines, the preferred spelling is ``/usr/bin/env python``,
+  as this instructs the script to respect the active virtual environment.
+* For Python 3 only scripts that do not support being executed on Python
+  2 at all, it is recommended to instead use ``python3`` and
+  ``/usr/bin/env python3``, as these will never invoke Python 2, and are
+  expected to work for both Python 3 virtual environments and Python 3
+  system installations
+* For Python 2 only scripts that do not support being executed on Python
+  3 at all, it is recommended to instead use ``python2`` and
+  ``/usr/bin/env python2``, as these will never invoke Python 3, and are
+  expected to work for Python 2 virtual environments and at least some
+  Python 2 system installations.
+* In cases where the script is expected to be executed outside virtual
+  environments, developers will need to be aware of the following
+  discrepancies across platforms and installation methods:
+
+  * Older Linux distributions will provide a ``python`` command that
+    refers to Python 2. Most of these distros do *not* provide a
+    ``python2`` command.
+  * Some newer Linux distributions will provide a ``python`` command that
+    refers to Python 3
+  * Some Linux distributions will not provide a ``python`` command at
+    all by default, but will provide a ``python3`` command by default
+
+* When potentially targeting these environments, developers may either
+  use a Python package installation tool that rewrites shebang lines for
+  the installed environment, provide instructions on updating shebang lines
+  interactively, or else use more specific shebang lines that are
+  tailored to the target environment.
 * Scripts targeting both “*old systems*” and systems without the default
   ``python`` command need to make a compromise and document this situation.
   Avoiding shebangs (via the console_scripts Entry Points ([9]_) or similar
@@ -105,9 +124,9 @@ For developers
 
 These recommendations are the outcome of the relevant python-dev discussions
 in March and July 2011 ([1]_, [2]_), February 2012 ([4]_),
-September 2014 ([6]_), discussion on GitHub in April 2018 ([7]_)
-and on python-dev in February 2019 ([8]_).
-
+September 2014 ([6]_), discussion on GitHub in April 2018 ([7]_),
+on python-dev in February 2019 ([8]_), and during the PEP update review
+in May 2019 ([10]_).
 
 
 History of this PEP
@@ -137,35 +156,30 @@ However, these recommendations implicitly assumed that Python 2 would always be
 available. As Python 2 is nearing its end of life in 2020 (PEP 373, PEP 404),
 distributions are making Python 2 optional or removing it entirely.
 This means either removing the ``python`` command or switching it to invoke
-Python 3, invalidating respectively the first or second recommendation.
-Also, some distributors decided that their users are better served by
-ignoring the PEP's recommendations, making the PEP's nominally
-cross-platform recommendations on ``python`` and ``python2`` in shebangs
-increasingly unreliable.
+Python 3. Some distributors also decided that their users were better served by
+ignoring the PEP's recommendations, and provided system administrators with the
+freedom to configure their systems based on the needs of their particular
+environment.
 
 
 .. _rationale:
 
 Current Rationale
 =================
 
-As of 2019, nearly all new systems include Python 3 and the ``python3``
-command. This makes the ``python3`` command the best general choice for
-code that can run on either Python 3.x or 2.x, even though it is not
-available everywhere.
+As of 2019, activating a Python virtual environment (or its functional
+equivalent) is the best way to obtain a consistent cross-platform and
+cross-distribution experience.
 
-The recommendation is skewed toward current and future systems, leaving
-behind “*old systems*” (like RHEL 6 or default Python installed on macOS).
-On these systems, Python software is rarely updated and any recommendations
-this PEP makes would likely be ignored.
+Accordingly, it is entirely reasonable for publishers to expect the
+availability of such an environment to get their software working
+correctly, and push responsibility for handling other environments
+(such as system Python installations) onto consumers of the software.
 
-Also, since distributors often ignored recommendations the PEP gave
-regarding the ``python`` command (for what they saw as legitimate special
-needs), this PEP now gives them broad control over the command.
-Correspondingly, users are advised to not use the ``python`` command
-in cross-platform code.
-Instead, this PEP specifies the expected behavior of the ``python3`` and
-``python2`` commands, which is not controversial.
+As part of that however, it is also appropriate to give Python
+distributors the flexibility they need in order to make the
+behaviour of their systems as similar as possible to the behaviour
+of an activated virtual environment.
 
 
 Future Changes to this Recommendation
@@ -350,6 +364,9 @@ References
 .. [9] The console_scripts Entry Point
    (https://python-packaging.readthedocs.io/en/latest/command-line-scripts.html#the-console-scripts-entry-point)
 
+.. [10] May 2019 PEP update review
+   (https://github.com/python/peps/pull/989)
+
 
 Copyright
 ===========