diff --git a/pep-0394.txt b/pep-0394.txt index e6e7b5828..a94393319 100644 --- a/pep-0394.txt +++ b/pep-0394.txt @@ -8,7 +8,7 @@ Status: Draft Type: Informational Content-Type: text/x-rst Created: 02-Mar-2011 -Post-History: 04-Mar-2011, 20-Jul-2011 +Post-History: 04-Mar-2011, 20-Jul-2011, 16-Feb-2012 Abstract @@ -39,7 +39,7 @@ Recommendation 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 `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 @@ -48,7 +48,7 @@ Recommendation * 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). + ``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. @@ -59,17 +59,15 @@ Recommendation ``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) +These recommendations are the outcome of the relevant python-dev discussions +in March and July 2011 ([1]_, [2]_) and February 2012 ([4]_). 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 +``python`` command to Python 2, some now alias it to Python 3 ([5]_). 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 @@ -80,8 +78,14 @@ provide a very simple mechanism to restore cross-platform support, with minimal additional work required on the part of distribution maintainers. -Notes -===== +Migration Notes +=============== + +This section does not contain any official recommendations from the core +CPython developers. It's merely a collection of notes regarding various +aspects of migrating to Python 3 as the default version of Python for a +system. They will hopefully be helpful to any distributions considering +making such a change. * Distributions that only include ``python3`` in their base install (i.e. they do not provide ``python2`` by default) along with those that are @@ -107,7 +111,7 @@ Notes 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 + 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 @@ -128,8 +132,10 @@ Notes 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. +* 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 + 2 and Python 3. Backwards Compatibility @@ -147,25 +153,38 @@ 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. +While technically a new feature, the ``make install`` and ``make bininstall`` +command in the 2.7 version of CPython will be adjusted to create the +following chains of symbolic links in the relevant ``bin`` directory (the +final item listed in the chain is the actual installed binary, preceding +items are relative symbolic links):: -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. + python -> python2 -> python2.7 + python-config -> python2-config -> python2.7-config 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 #12627 [3]. +This feature will first appear in the default installation process in +CPython 2.7.3. + +The installation commands in the CPython 3.x series already create the +appropriate symlinks. For example, CPython 3.2 creates:: + + python3 -> python3.2 + idle3 -> idle3.2 + pydoc3 -> pydoc3.2 + python3-config -> python3.2-config + +And CPython 3.3 will create:: + + python3 -> python3.3 + idle3 -> idle3.3 + pydoc3 -> pydoc3.3 + python3-config -> python3.3-config + pysetup3 -> pysetup3.3 + +The implementation progress of these features in the default installers is +managed on the tracker as issue #12627 ([3]_). Impact on PYTHON* Environment Variables @@ -192,16 +211,21 @@ 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) +.. [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) +.. [2] Rebooting \PEP 394 (aka Support the /usr/bin/python2 symlink upstream) + (http://mail.python.org/pipermail/python-dev/2011-July/112322.html) -[3] Implement PEP 394 in the CPython Makefile - (http://bugs.python.org/issue12627) +.. [3] Implement \PEP 394 in the CPython Makefile + (http://bugs.python.org/issue12627) + +.. [4] \PEP 394 request for pronouncement (python2 symlink in \*nix systems) + (http://mail.python.org/pipermail/python-dev/2012-February/116435.html) + +.. [5] Arch Linux announcement that their "python" link now refers Python 3 + (https://www.archlinux.org/news/python-is-now-python-3/) Copyright =========== This document has been placed in the public domain. -