diff --git a/pep-0394.txt b/pep-0394.txt index 8da9fb58f53..091c9ac99ef 100644 --- a/pep-0394.txt +++ b/pep-0394.txt @@ -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,9 +54,10 @@ 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 @@ -61,23 +65,35 @@ Recommendation 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,9 @@ References minor edits (https://github.com/python/peps/pull/630) +.. [8] PEP 394: Allow not installing unversioned "python" command + (https://github.com/python/peps/pull/893) + Copyright =========== This document has been placed in the public domain.