Update PEP 394 based on python-dev discussions

pep-0394.txt

@@ -19,10 +19,17 @@ 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
+* ``python2`` will refer to some version of Python 2.x.
-* ``python3`` will refer to some version of Python 3.x
+* ``python3`` will refer to some version of Python 3.x.
-* ``python`` *should* refer to the same target as ``python2`` but *may*
+* for the time being, all distributions *should* ensure that ``python``
-  refer to ``python3`` on some bleeding edge distributions
+  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 @@ 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.
+* The main barrier to a distribution switching the ``python`` command from
-  they do not provide ``python2`` by default) along with those that are
+  ``python2`` to ``python3`` isn't breakage within the distribution, but
-  aggressively trying to reach that point (and are willing to break third
+  instead breakage of private third party scripts developed by sysadmins
-  party scripts while attempting to get there) are already beginning to alias
+  and other users. Updating the ``python`` command to invoke ``python3``
-  the ``python`` command to ``python3``
+  by default indicates that a distribution is willing to break such scripts
-* More conservative distributions that are less willing to tolerate breakage
+  with errors that are potentially quite confusing for users that aren't
-  of third party scripts continue to alias it to ``python2``. Until the
+  yet familiar with the backwards incompatible changes in Python 3. For
-  conventions described in this PEP are more widely adopted, having ``python``
+  example, while the change of ``print`` from a statement to a builtin
-  invoke ``python2`` will remain the recommended option.
+  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 @@ making such a change.
   ``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 @@ 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.
+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