From 14e05f57a48483f5786833408aab42b4c8aec8be Mon Sep 17 00:00:00 2001 From: Kyle Stanley Date: Fri, 8 Nov 2019 03:12:44 -0500 Subject: [PATCH] Grammatical improvements for PEP 606 (#1227) * Grammatical improvements for PEP 606 * Minor grammar fix * Fix underline --- pep-0606.rst | 90 ++++++++++++++++++++++++++-------------------------- 1 file changed, 45 insertions(+), 45 deletions(-) diff --git a/pep-0606.rst b/pep-0606.rst index d50f1b136..76f5cf5e3 100644 --- a/pep-0606.rst +++ b/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 `_. -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 `_ (`bpo-22417 `_). @@ -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 `_). 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 `_ 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... `_ @@ -428,7 +428,7 @@ PEP 497 `_ 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