Grammatical improvements for PEP 606 (#1227)
* Grammatical improvements for PEP 606 * Minor grammar fix * Fix underline
This commit is contained in:
Kyle Stanley
Victor Stinner
parent
e5fdfee5f8
commit
14e05f57a4
90
pep-0606.rst
90
pep-0606.rst
|
|
@ -15,11 +15,11 @@ Add ``sys.set_python_compat_version(version)`` to enable partial
|
|||
compatibility with requested Python version. Add
|
||||
``sys.get_python_compat_version()``.
|
||||
|
||||
Modify a few functions of the standard library to implement a partial
|
||||
Modify a few functions in the standard library to implement partial
|
||||
compatibility with Python 3.8.
|
||||
|
||||
Add ``sys.set_python_min_compat_version(version)`` to deny backward
|
||||
compatibility with Python older than *version*.
|
||||
compatibility with Python versions older than *version*.
|
||||
|
||||
Add ``-X compat_version=VERSION`` and ``-X min_compat_version=VERSION``
|
||||
command line options. Add ``PYTHONCOMPATVERSION`` and
|
||||
|
|
@ -32,19 +32,19 @@ Rationale
|
|||
The need to evolve frequently
|
||||
-----------------------------
|
||||
|
||||
To remain relevant and useful, Python has to evolve frequently. Some
|
||||
To remain relevant and useful, Python has to evolve frequently; some
|
||||
enhancements require incompatible changes. Any incompatible change can
|
||||
break an unknown number of Python projects. Developers can decide to
|
||||
not implement a feature because of that.
|
||||
|
||||
Users want to get the latest Python version to get new features and
|
||||
better performance. A few incompatible changes prevent them to use their
|
||||
Users want to get the latest Python version to obtain new features and
|
||||
better performance. A few incompatible changes can prevent them from using their
|
||||
applications on the latest Python version.
|
||||
|
||||
This PEP proposes to add a partial compatibility with old Python
|
||||
versions as a tradeoff to fit both use cases.
|
||||
|
||||
The main issue with the migration from Python 2 to Python 3 is not that
|
||||
The main issue with the migration from Python 2 to Python 3 is not that
|
||||
Python 3 is backward incompatible, but how incompatible changes were
|
||||
introduced.
|
||||
|
||||
|
|
@ -52,38 +52,38 @@ introduced.
|
|||
Partial compatibility to minimize the Python maintenance burden
|
||||
---------------------------------------------------------------
|
||||
|
||||
While technically it would be possible to provide a full compatibility
|
||||
While technically it would be possible to provide full compatibility
|
||||
with old Python versions, this PEP proposes to minimize the number of
|
||||
functions handling backward compatibility to reduce the maintenance
|
||||
burden of the Python project ("CPython").
|
||||
burden of the Python project (CPython).
|
||||
|
||||
Each change introducing backport compatibility to a function should be
|
||||
properly discussed to estimate the maintenance cost in the long-term.
|
||||
|
||||
Backward compatibility code will be dropped at each Python release, on a
|
||||
Backward compatibility code will be dropped on each Python release, on a
|
||||
case by case basis. Each compatibility function can be supported for a
|
||||
different number of Python releases depending on its maintenance cost
|
||||
and the estimated risk (number of broken projects) if it's removed.
|
||||
|
||||
The maintenance cost does not only come from the code implementing the
|
||||
backward compatibility, but come also from additional tests.
|
||||
backward compatibility, but also comes from the additional tests.
|
||||
|
||||
|
||||
Cases excluded from backward compatibility
|
||||
------------------------------------------
|
||||
|
||||
The performance overhead of a compatibility code must be low when
|
||||
The performance overhead of any compatibility code must be low when
|
||||
``sys.set_python_compat_version()`` is not called.
|
||||
|
||||
The C API is out of the scope of this PEP: ``Py_LIMITED_API`` macro and
|
||||
the stable ABI are solving this problem differently, see the `PEP 384:
|
||||
Defining a Stable ABI <https://www.python.org/dev/peps/pep-0384/>`_.
|
||||
|
||||
Security fixes which break the backward compatibility on purpose will
|
||||
not get a compatibility layer. Security matters more than compatibility.
|
||||
Security fixes which break backward compatibility on purpose will
|
||||
not get a compatibility layer; security matters more than compatibility.
|
||||
For example, ``http.client.HTTPSConnection`` was modified in Python
|
||||
3.4.3 to performs all the necessary certificate and hostname checks by
|
||||
default. It was a deliberate change motivated by the `PEP 476: Enabling
|
||||
default. It was a deliberate change motivated by `PEP 476: Enabling
|
||||
certificate verification by default for stdlib http clients
|
||||
<https://www.python.org/dev/peps/pep-0476/>`_ (`bpo-22417
|
||||
<https://bugs.python.org/issue22417>`_).
|
||||
|
|
@ -97,15 +97,15 @@ change is backward compatible up to Python 3.4. There is no need to use
|
|||
the Protocol 3 by default when compatibility with Python 3.8 is
|
||||
requested.
|
||||
|
||||
New ``DeprecationWarning`` and ``PendingDeprecatingWarning`` warnings
|
||||
of Python 3.9 will not be disabled in Python 3.8 compatibility mode.
|
||||
The new ``DeprecationWarning`` and ``PendingDeprecatingWarning`` warnings
|
||||
in Python 3.9 will not be disabled in Python 3.8 compatibility mode.
|
||||
If a project runs its test suite using ``-Werror`` (treat any warning as
|
||||
an error), these warnings must be fixed, or specific deprecation
|
||||
warnings must be ignored on a case by case basis.
|
||||
|
||||
|
||||
Upgrade a project to a newer Python
|
||||
-----------------------------------
|
||||
Upgrading a project to a newer Python
|
||||
-------------------------------------
|
||||
|
||||
Without backward compatibility, all incompatible changes must be fixed
|
||||
at once, which can be a blocker issue. It is even worse when a project
|
||||
|
|
@ -113,15 +113,15 @@ is upgraded to a newer Python which is separated by multiple releases
|
|||
from the old Python.
|
||||
|
||||
Postponing an upgrade only makes things worse: each skipped release adds
|
||||
more incompatible changes. The technical debt is only steadily
|
||||
increasing.
|
||||
more incompatible changes. The technical debt only steadily
|
||||
increases over time.
|
||||
|
||||
With backward compatibility, it becomes possible to upgrade Python
|
||||
increamentally in a project, without having to fix all issues at once.
|
||||
increamentally in a project, without having to fix all of the issues at once.
|
||||
|
||||
The "all-or-nothing" is a showstopper to port large Python 2 code bases
|
||||
to Python 3. The list of incompatible changes between Python 2 and
|
||||
Python 3 is long, and it's getting longer at each Python 3.x release.
|
||||
Python 3 is long, and it's getting longer with each Python 3.x release.
|
||||
|
||||
|
||||
Cleaning up Python and DeprecationWarning
|
||||
|
|
@ -133,23 +133,23 @@ One of the `Zen of Python (PEP 20)
|
|||
There should be one-- and preferably only one --obvious way to do
|
||||
it.
|
||||
|
||||
When Python evolves, new ways emerge inevitably. ``DeprecationWarning``
|
||||
are emitted to suggest to use the new way, but many developers ignore
|
||||
When Python evolves, new ways inevitably emerge. ``DeprecationWarning``s
|
||||
are emitted to suggest using the new way, but many developers ignore
|
||||
these warnings, which are silent by default (except in the ``__main__``
|
||||
module: see the `PEP 565 <https://www.python.org/dev/peps/pep-0565/>`_).
|
||||
Some developers simply ignore all warnings when there are too many
|
||||
warnings, and so only bother with exceptions when deprecated code is
|
||||
warnings, thus only bother with exceptions when the deprecated code is
|
||||
removed.
|
||||
|
||||
Sometimes, supporting both ways has a minor maintenance cost, but
|
||||
developers prefer to drop the old way to clean up the code. Such kind of
|
||||
change is backward incompatible.
|
||||
developers prefer to drop the old way to clean up their code. These kinds of
|
||||
changes are backward incompatible.
|
||||
|
||||
Some developers can take the end of the Python 2 support as an
|
||||
opportunity to push even more incompatible changes than usual.
|
||||
|
||||
Adding an opt-in backward compatibility prevents to break
|
||||
applications and allows developers to continue to do such cleanup.
|
||||
Adding an opt-in backward compatibility prevents the breaking of
|
||||
applications and allows developers to continue doing these cleanups.
|
||||
|
||||
|
||||
Redistribute the maintenance burden
|
||||
|
|
@ -173,19 +173,19 @@ In Python 3.6, aliases were created in ``collections/__init__.py`` by
|
|||
``from _collections_abc import *``.
|
||||
|
||||
In Python 3.7, a ``__getattr__()`` has been added to the ``collections``
|
||||
module to emit a DeprecationWarning at the first access to an
|
||||
module to emit a DeprecationWarning upon first access to an
|
||||
attribute::
|
||||
|
||||
def __getattr__(name):
|
||||
# For backwards compatibility, continue to make the collections ABCs
|
||||
# through Python 3.6 available through the collections module.
|
||||
# Note, no new collections ABCs were added in Python 3.7
|
||||
# Note: no new collections ABCs were added in Python 3.7
|
||||
if name in _collections_abc.__all__:
|
||||
obj = getattr(_collections_abc, name)
|
||||
import warnings
|
||||
warnings.warn("Using or importing the ABCs from 'collections' instead "
|
||||
"of from 'collections.abc' is deprecated since Python 3.3, "
|
||||
"and in 3.9 it will stop working",
|
||||
"and in 3.9 it will be removed.",
|
||||
DeprecationWarning, stacklevel=2)
|
||||
globals()[name] = obj
|
||||
return obj
|
||||
|
|
@ -206,7 +206,7 @@ Deprecated open() "U" mode
|
|||
--------------------------
|
||||
|
||||
The ``"U"`` mode of ``open()`` is deprecated since Python 3.4 and emits a
|
||||
``DeprecationWarning``. The `bpo-37330
|
||||
``DeprecationWarning``. `bpo-37330
|
||||
<https://bugs.python.org/issue37330>`_ proposes to drop this mode:
|
||||
``open(filename, "rU")`` would raise an exception.
|
||||
|
||||
|
|
@ -247,7 +247,7 @@ is equivalent to ``(major, minor, 0)``.
|
|||
By default, ``sys.get_python_compat_version()`` returns the current
|
||||
Python version.
|
||||
|
||||
Example to request compatibility with Python 3.8.0::
|
||||
For example, to request compatibility with Python 3.8.0::
|
||||
|
||||
import collections
|
||||
|
||||
|
|
@ -279,13 +279,13 @@ Add ``PYTHONCOMPATVERSIONVERSION=VERSION`` and
|
|||
``PYTHONCOMPATMINVERSION=VERSION=VERSION`` environment variables: call
|
||||
respectivelly ``sys.set_python_compat_version()`` and
|
||||
``sys.set_python_min_compat_version()``. ``VERSION`` is a version
|
||||
string with the same format that the command line options.
|
||||
string with the same format as the command line options.
|
||||
|
||||
|
||||
Backwards Compatibility
|
||||
=======================
|
||||
|
||||
Introducing ``sys.set_python_compat_version()`` function means that an
|
||||
Introducing the ``sys.set_python_compat_version()`` function means that an
|
||||
application will behave differently depending on the compatibility
|
||||
version. Moreover, since the version can be decreased multiple times,
|
||||
the application can behave differently depending on the import order.
|
||||
|
|
@ -346,10 +346,10 @@ file.
|
|||
|
||||
With this option, there is no need to change
|
||||
``sys.implementation.cache_tag`` to use a different ``.pyc`` filename,
|
||||
since the parser would always produce the same output for the same input
|
||||
(except of the optimization level).
|
||||
since the parser will always produce the same output for the same input
|
||||
(except for the optimization level).
|
||||
|
||||
Example::
|
||||
For example::
|
||||
|
||||
from __future__ import python35_syntax
|
||||
|
||||
|
|
@ -367,7 +367,7 @@ the version of the Python language.
|
|||
without the micro version as a suffix. For example, Python 3.9 uses
|
||||
``'cpython-39'`` by default, but
|
||||
``sys.set_python_compat_version((3, 7, 2))`` sets ``cache_tag`` to
|
||||
``'cpython-39-37'``. Changes of the Python language are now allowed
|
||||
``'cpython-39-37'``. Changes to the Python language are now allowed
|
||||
in micro releases.
|
||||
|
||||
One problem is that ``import asyncio`` is likely to fail if
|
||||
|
|
@ -393,11 +393,11 @@ means 6 ``.pyc`` files, instead of 3, to support Python 3.8 and Python
|
|||
Temporary moratorium on incompatible changes
|
||||
--------------------------------------------
|
||||
|
||||
In 2009, the PEP 3003 "Python Language Moratorium" proposed to a
|
||||
In 2009, PEP 3003 "Python Language Moratorium" proposed a
|
||||
temporary moratorium (suspension) of all changes to the Python language
|
||||
syntax, semantics, and built-ins for Python 3.1 and Python 3.2.
|
||||
|
||||
In May 2018, during PEP 572 discussions, it was also proposed to slow
|
||||
In May 2018, during the PEP 572 discussions, it was also proposed to slow
|
||||
down Python changes: see the python-dev thread `Slow down...
|
||||
<https://mail.python.org/archives/list/python-dev@python.org/thread/HHKRXOMRJQH75VNM3JMSQIOOU6MIUB24/#PHA35EAPNONZMTOYBINGFR6XXNMCDPFQ>`_
|
||||
|
||||
|
|
@ -428,7 +428,7 @@ PEP 497
|
|||
<https://www.python.org/dev/peps/pep-0497/>`_ proposes different
|
||||
solutions to provide backward compatibility.
|
||||
|
||||
Except of the ``__past__`` mechanism idea, the PEP 497 does not propose
|
||||
Except for the ``__past__`` mechanism idea, PEP 497 does not propose
|
||||
concrete solutions:
|
||||
|
||||
When an incompatible change to core language syntax or semantics is
|
||||
|
|
@ -534,7 +534,7 @@ Micro releases
|
|||
|
||||
Sometimes, incompatible changes are introduced in micro releases
|
||||
(``micro`` in ``major.minor.micro``) to fix bugs or security
|
||||
vulnerabilities. Examples:
|
||||
vulnerabilities. Examples include:
|
||||
|
||||
* Python 3.7.2, ``compileall`` and ``py_compile`` module: the
|
||||
*invalidation_mode* parameter's default value is updated to ``None``;
|
||||
|
|
@ -580,7 +580,7 @@ incompatible:
|
|||
* ``loop.create_future()`` was added to Python 3.5.2 in the ``asyncio``
|
||||
module.
|
||||
|
||||
No backward compatibility code is needed for such kind of changes.
|
||||
No backward compatibility code is needed for these kinds of changes.
|
||||
|
||||
|
||||
References
|
||||
|
|
|
|||
Loading…
Reference in New Issue