Update PEP 394 for latest round of python-dev discussions

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.
-