[Python-checkins] peps: Update PEP 394 based on python-dev discussions

[nick.coghlan]

http://hg.python.org/peps/rev/4b379a690ae2
changeset:   5007:4b379a690ae2
user:        Nick Coghlan <ncoghlan at gmail.com>
date:        Thu Jul 25 22:21:27 2013 +1000
summary:
  Update PEP 394 based on python-dev discussions

files:
  pep-0394.txt |  55 +++++++++++++++++++++++++++++----------
  1 files changed, 40 insertions(+), 15 deletions(-)


diff --git a/pep-0394.txt b/pep-0394.txt
--- a/pep-0394.txt
+++ b/pep-0394.txt
@@ -19,10 +19,17 @@
 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
+* ``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``
+  refers to the same target as ``python2``.
+* however, 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,
+  Python 2 only scripts should either be updated to be source compatible
+  with Python 3 or else to use ``python2`` in the shebang line.
 
 
 Recommendation
@@ -103,15 +110,29 @@
 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
-  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 main barrier to a distribution switching the ``python`` command from
+  ``python2`` to ``python3`` isn't breakage within the distribution, but
+  instead breakage of private third party scripts developed by sysadmins
+  and other users. Updating the ``python`` command to invoke ``python3``
+  by default indicates that a distribution is willing to break such scripts
+  with errors that are potentially quite confusing for users that aren't
+  yet familiar with the backwards incompatible changes in Python 3. For
+  example, while the change of ``print`` from a statement to a builtin
+  function is relatively simple for automated converters to handle, the
+  SyntaxError from attempting to use the Python 2 notation in Python 3 is
+  thoroughly confusing if you aren't already aware of the change::
+
+      $ python3 -c 'print "Hello, world!"'
+        File "<string>", line 1
+          print "Hello, world!"
+                              ^
+      SyntaxError: invalid syntax
+
+* 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.
 * 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
@@ -148,10 +169,13 @@
   ``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.
+* one symbolic date being considered for a possible change to the official
+  recommendation in this PEP is the planned switch of Python 2.7 from full
+  maintenance to security update only status in 2015 (see PEP 373).
 
 
 Backwards Compatibility
-=========================
+=======================
 
 A potential problem can arise if a script adhering to the
 ``python2``/``python3`` convention is executed on a system not supporting
@@ -217,7 +241,8 @@
 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.
+address this issue (like this PEP, the PEP 397 launcher invokes Python 2 by
+default if versions of both Python 2 and 3 are installed on the system).
 
 
 References

-- 
Repository URL: http://hg.python.org/peps