encukou
diff --git a/‎pep-0394.txt
Lines changed: 50 additions & 39 deletions b/‎pep-0394.txt
Lines changed: 50 additions & 39 deletions
@@ -23,14 +23,17 @@ Python interpreter (i.e. the version invoked by the ``python`` command).
 
 * ``python2`` will refer to some version of Python 2.x.
 * ``python3`` will refer to some version of Python 3.x.
-* for the time being, all distributions *should* ensure that ``python``,
-  if installed, refers to the same target as ``python2``, unless the user
-  deliberately overrides this or a virtual environment is active.
-* however, end users should be aware that ``python`` refers to ``python3``
+* ``python`` may be missing, but if it is installed, it *should* refer to the
+  same target as ``python2``, unless the user deliberately overrides this.
+* End users should be aware that ``python`` refers to ``python3``
   on at least Arch Linux (that change is what prompted the creation of this
-  PEP), so ``python`` should be used in the shebang line only for scripts
-  that are source compatible with both Python 2 and 3.
-* in preparation for an eventual change in the default version of Python,
+  PEP), and it may be missing entirely (for example, if Python 2 itself is
+  not installed).
+* For new scripts that are source compatible with both Python 2 and 3,
+  using ``python3`` in the shebang line is now preferred.
+  ``python`` may still be used for scripts that need to work with the
+  system-provided Python of older distributions.
+* In preparation for an eventual change in the default version of Python,
   Python 2 only scripts should either be updated to be source compatible
   with Python 3 or else to use ``python2`` in the shebang line.
 
@@ -51,33 +54,46 @@ Recommendation
   command; see the `Rationale`_ and `Migration Notes`_ below).
 * The Python 2.x ``idle``, ``pydoc``, and ``python-config`` commands should
   likewise be available as ``idle2``, ``pydoc2``, and ``python2-config``,
-  with the original commands invoking these versions by default, but possibly
-  invoking the Python 3.x versions instead if configured to do so by the
-  system administrator.
+  with the unversioned commands either not available or invoking the
+  Python 2 versions by default.
+  If configured to do so by the system administrator, they may invoke the
+  Python 3.x versions instead.
 * In order to tolerate differences across platforms, all new code that needs
   to invoke the Python interpreter should not specify ``python``, but rather
   should specify either ``python2`` or ``python3`` (or the more specific
   ``python2.x`` and ``python3.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.
-* One exception to this is scripts that are deliberately written to be source
-  compatible with both Python 2.x and 3.x. Such scripts may continue to use
-  ``python`` on their shebang line.
+* Scripts that are deliberately written to be source compatible with both
+  Python 2.x and 3.x *should* now use ``python3`` on their shebang line,
+  unless they target the system-provided Python of distributions that do not
+  provide ``python3`` (e.g. macOS or RHEL/CentOS 7).
+  Alternatively, they may continue to use ``python``, with the caveat that
+  this will make them unusable on systems that do not have the
+  unversioned command (or even Python 2 itself) installed.
 * When packaging software that is source compatible with both versions,
-  distributions may change such ``python`` shebangs to ``python3``.
+  distributions may change unversioned ``python`` shebangs to ``python3``.
   This ensures software is used with the latest version of
   Python available, and it can remove a dependency on Python 2.
+  (However, note that there is no automatic way to determine whether a script
+  is compatible with both versions and uses ``python`` by conscious decision,
+  or if it's a Python 2-only one that was not yet updated.)
 * When reinvoking the interpreter from a Python script, querying
   ``sys.executable`` to avoid hardcoded assumptions regarding the
   interpreter location remains the preferred approach.
-* In controlled environments aimed at expert users, where being explicit
-  is valued over user experience (for example, in test environments and
-  package build systems), distributions may choose to not provide the
-  ``python`` command even if ``python2`` is available.
-  (All software in such a controlled environment must use ``python3`` or
-  ``python2`` rather than ``python``, which means scripts that deliberately
-  use ``python`` need to be modified for such environments.)
+* Distributions may choose to not provide the ``python`` command by default.
+  In this case, they should still make it possible for sysadmins to install
+  the command explicitly (if Python 2 is available).
+  All software intended for such a distribution must use ``python3`` (or
+  ``python2``) rather than ``python``.
+* Distributions *should not* empower sysadmins to easily switch the ``python``
+  command to invoke Python 3.
+  The message ``python: command not found`` (possibly augmented with
+  a suggestion to explicitly use ``python3`` or ``python2``) is much clearer
+  and more actionable than errors from accidentally running a script with the
+  wrong Python version -- especially for those relatively unfamiliar
+  with Python.
 * When a virtual environment (created by the PEP 405 ``venv`` package or a
   similar tool) is active, the ``python`` command should refer to the
   virtual environment's interpreter. In other words, activating a virtual
@@ -86,7 +102,8 @@ Recommendation
 
 These recommendations are the outcome of the relevant python-dev discussions
 in March and July 2011 ([1]_, [2]_), February 2012 ([4]_),
-September 2014 ([6]_), and discussion on GitHub in April 2018 ([7]_).
+September 2014 ([6]_), and discussion on GitHub in April 2018 ([7]_)
+and February 2019 ([8]_).
 
 
 Rationale
@@ -111,7 +128,7 @@ Future Changes to this Recommendation
 This recommendation will be periodically reviewed over the next few years,
 and updated when the core development team judges it appropriate. As a
 point of reference, regular maintenance releases for the Python 2.7 series
-will continue until at least 2020.
+will continue until January 2020.
 
 
 Migration Notes
@@ -144,11 +161,9 @@ making such a change.
 
   (In Python 3.4.2+, that generic error message has been replaced with the
   more explicit "SyntaxError: Missing parentheses in call to 'print'")
-* Avoiding breakage of such third party scripts is the key reason this
-  PEP recommends that ``python`` continue to refer to ``python2`` for the
-  time being. Until the conventions described in this PEP are more widely
-  adopted, having ``python`` invoke ``python2`` will remain the recommended
-  option.
+* Avoiding hard-to-debug breakage of such third party scripts is the key reason
+  this PEP recommends that ``python`` either continue to refer to ``python2``,
+  or be missing entirely.
 * The ``pythonX.X`` (e.g. ``python2.6``) commands exist on some systems, on
   which they invoke specific minor versions of the Python interpreter. It
   can be useful for distribution-specific packages to take advantage of these
@@ -164,21 +179,15 @@ making such a change.
   rather than being provided as a separate binary file.
 * It is strongly encouraged that distribution-specific packages use ``python2``
   or ``python3`` rather than ``python``, even in code that is not intended to
-  operate on other distributions. This will reduce problems if the
-  distribution later decides to change the version of the Python interpreter
-  that the ``python`` command invokes, or if a sysadmin installs a custom
-  ``python`` command with a different major version than the distribution
-  default.
-* If the above point is adhered to and sysadmins are permitted to change the
-  ``python`` command, then the ``python`` command should always be implemented
+  operate on other distributions. This will avoid problems if the ``python``
+  command is unavailable, or if a sysadmin installs a custom ``python``
+  command with a different major version.
+* If sysadmins are permitted to change the ``python`` command (which is *not*
+  recommended), then the ``python`` command should always be implemented
   as a link to the interpreter binary (or a link to a link) and not vice
   versa. That way, if a sysadmin does decide to replace the installed
   ``python`` file, they can do so without inadvertently deleting the
   previously installed binary.
-* If the Python 2 interpreter becomes uncommon, scripts should nevertheless
-  continue to use the ``python3`` convention rather that just ``python``. This
-  will ease transition in the event that yet another major version of Python
-  is released.
 * If these conventions are adhered to, it will become the case that the
   ``python`` command is only executed in an interactive manner as a user
   convenience, or to run scripts that are source compatible with both Python
@@ -281,6 +290,8 @@ References
    minor edits
    (https://github.com/python/peps/pull/630)
 
+.. [7] XXX: link to the discussion
+
 Copyright
 ===========
 This document has been placed in the public domain.