PEP: 394 Title: The "python" Command on Unix-Like Systems Version: $Revision$ Last-Modified: $Date$ Author: Kerrick Staley , Nick Coghlan Status: Draft Type: Informational Content-Type: text/x-rst Created: 02-Mar-2011 Post-History: 04-Mar-2011, 20-Jul-2011 Abstract ======== This PEP provides a convention to ensure that Python scripts can continue to be portable across ``*nix`` systems, regardless of the default version of the 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 * ``python`` *should* refer to the same target as ``python2`` but *may* refer to ``python3`` on some bleeding edge distributions Recommendation ============== * Unix-like software distributions (including systems like Mac OS X and Cygwin) should install the ``python2`` command into the default path whenever a version of the Python 2 interpreter is installed, and the same for ``python3`` and the Python 3 interpreter. * When invoked, ``python2`` should run some version of the Python 2 interpreter, and ``python3`` should run some version of the Python 3 interpreter. * Similarly, the more general ``python`` command should be installed whenever any version of Python is installed and should invoke the same version of Python as either ``python2`` or ``python3``. * For the time being, it is recommended that ``python`` should refer to ``python2`` (however, some distributions have already chosen otherwise; see 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. * 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 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 without affecting their portability. * When reinvoking the interpreter from a Python script, querying ``sys.executable`` to avoid hardcoded assumptions regarding the interpreter location remains the preferred approach. These recommendations are the outcome of the relevant python-dev discussion in March and July 2011 [1][2] (NOTE: More accurately, they will be such once the "Draft" status disappears from the PEP header, it has been moved into the "Other Informational PEP" section in PEP 0 and this note has been deleted) Rationale ========= This is needed as, even though the majority of distributions still alias the ``python`` command to Python 2, some now alias it to Python 3. Some of the former also do not provide a ``python2`` command; hence, there is currently no way for Python 2 code (or any code that invokes the Python 2 interpreter directly rather than via ``sys.executable``) to reliably run on all Unix-like systems without modification, as the ``python`` command will invoke the wrong interpreter version on some systems, and the ``python2`` command will fail completely on others. The recommendations in this PEP provide a very simple mechanism to restore cross-platform support, with minimal additional work required on the part of distribution maintainers. Notes ===== * Distributions that only include ``python3`` in their base install (i.e. they do not provide ``python2`` by default) along with those that are aggressively trying to reach that point (and are willing to break third party scripts while attempting to get there) are already beginning to alias the ``python`` command to ``python3`` * More conservative distributions that are less willing to tolerate breakage of third party scripts continue to alias it to ``python2``. Until the conventions described in this PEP are more widely adopted, having ``python`` invoke ``python2`` will remain the recommended option. * 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 utilities if they exist, since it will prevent code breakage if the default minor version of a given major version is changed. However, scripts intending to be cross-platform should not rely on the presence of these utilities, but rather should be tested on several recent minor versions of the target major version, compensating, if necessary, for the small differences that exist between minor versions. This prevents the need for sysadmins to install many very similar versions of the interpreter. * When the ``pythonX.X`` binaries are provided by a distribution, the ``python2`` and ``python3`` commands should refer to one of those files rather being provided as a separate binary file. * It is suggested that even distribution-specific packages follow the ``python2``/``python3`` convention, even in code that is not intended to operate on other distributions. This will prevent 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. Distributions can test whether they are fully following this convention by changing the ``python`` interpreter on a test box and checking to see if anything breaks. * If the above point is adhered to and sysadmins are permitted to change the ``python`` command, 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. * As an alternative to the recommendation presented above, some distributions may choose to leave the ``python`` command itself undefined, leaving sysadmins and users with the responsibility to choose their own preferred version to be made available as the ``python`` command. * 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 be the case that the ``python`` command is only executed in an interactive manner. Backwards Compatibility ========================= A potential problem can arise if a script adhering to the ``python2``/``python3`` convention is executed on a system not supporting these commands. This is mostly a non-issue, since the sysadmin can simply create these symbolic links and avoid further problems. It is a significantly more obvious breakage than the sometimes cryptic errors that can arise when attempting to execute a script containing Python 2 specific syntax with a Python 3 interpreter. Application to the CPython Reference Interpreter ================================================ While technically a new feature, the ``make install`` command in the 2.7 version of CPython will be adjusted to create the ``python2.7``, ``idle2.7``, ``pydoc2.7``, and ``python2.7-config`` binaries, with ``python2``, ``idle2``, ``pydoc2``, and ``python2-config`` as hard links to the respective binaries, and ``python``, ``idle``, ``pydoc``, and ``python-config`` as symbolic links to the respective hard links. This feature will first appear in CPython 2.7.3. The ``make install`` command in the CPython 3.x series will similarly install the ``python3.x``, ``idle3.x``, ``pydoc3.x``, and ``python3.x-config`` binaries (with appropriate ``x``), and ``python3``, ``idle3``, ``pydoc3``, and ``python3-config`` as hard links. This feature will first appear in CPython 3.3. Similar adjustments will be made to the Mac OS X binary installer. As implementation of these features in the default installers does not alter the recommendations in this PEP, the implementation progress is managed on the tracker as issue . Impact on PYTHON* Environment Variables ======================================= The choice of target for the ``python`` command implicitly affects a distribution's expected interpretation of the various Python related environment variables. The use of ``*.pth`` files in the relevant ``site-packages`` folder, the "per-user site packages" feature (see ``python -m site``) or more flexible tools such as ``virtualenv`` are all more tolerant of the presence of multiple versions of Python on a system than the direct use of ``PYTHONPATH``. Exclusion of MS Windows ======================= This PEP deliberately excludes any proposals relating to Microsoft Windows, as devising an equivalent solution for Windows was deemed too complex to handle here. PEP 397 and the related discussion on the python-dev mailing list address this issue. References ========== [1] Support the /usr/bin/python2 symlink upstream (with bonus grammar class!) (http://mail.python.org/pipermail/python-dev/2011-March/108491.html) [2] Rebooting PEP 394 (aka Support the /usr/bin/python2 symlink upstream) (http://mail.python.org/pipermail/python-dev/2011-July/112322.html) Copyright =========== This document has been placed in the public domain.