PEP 597: Minor edit (#1448)

pep-0597.rst

@@ -1,6 +1,6 @@
 PEP: 597
-Title: Soft deprecation of omitting encoding
+Title: Soft deprecation of default encoding
-Last-Modified: 14-Apr-2020
+Last-Modified: 23-Jun-2020
 Author: Inada Naoki <songofacandy@gmail.com>
 Discussions-To: https://discuss.python.org/t/3880
 Status: Draft
@@ -16,7 +16,7 @@ Abstract
 This PEP proposes:
 
 * ``TextIOWrapper`` raises a ``PendingDeprecationWarning`` when the
-  ``encoding`` option is not specified, and dev mode is enabled.
+  ``encoding`` option is not specified and dev mode is enabled.
 
 * Add ``encoding="locale"`` option to ``TextIOWrapper``. It behaves
   like ``encoding=None`` but don't raise a warning.
@@ -25,8 +25,8 @@ This PEP proposes:
 Motivation
 ==========
 
-Omitting encoding is common mistake
+Using the default encoding is a common mistake
-------------------------------------
+----------------------------------------------
 
 Developers using macOS or Linux may forget that the default encoding
 is not always UTF-8.
@@ -34,12 +34,13 @@ is not always UTF-8.
 For example, ``long_description = open("README.md").read()`` in
 ``setup.py`` is a common mistake. Many Windows users can not install
 the package if there is at least one non-ASCII character (e.g. emoji)
-in the ``README.md`` file.
+in the ``README.md`` file which is encoded in UTF-8.
 
 For example, 489 packages of the 4000 most downloaded packages from
 PyPI used non-ASCII characters in README. And 82 packages of them
 can not be installed from source package when locale encoding is
-ASCII. [1_] They used default encoding to read README or TOML file.
+ASCII. [1_] They used the default encoding to read README or TOML
+file.
 
 Another example is ``logging.basicConfig(filename="log.txt")``.
 Some users expect UTF-8 is used by default, but locale encoding is
@@ -74,30 +75,33 @@ Raising a PendingDeprecationWarning
 ---------------------------------------
 
 ``TextIOWrapper`` raises the ``PendingDeprecationWarning`` when the
-``encoding`` option is omitted, and dev mode is enabled.
+``encoding`` option is omitted and dev mode is enabled.
 
 
 ``encoding="locale"`` option
 ----------------------------
 
 When ``encoding="locale"`` is specified to the ``TextIOWrapper``, it
-behaves same to ``encoding=None``.  In detail, the encoding is
+behaves same to ``encoding=None`` except it doesn't raise warning.
-chosen by:
+In detail, the encoding is chosen by this order:
 
 1. ``os.device_encoding(buffer.fileno())``
 2. ``locale.getpreferredencoding(False)``
 
-This option can be used to suppress the ``PendingDeprecationWarning``.
+This option can be used to use the locale encoding explicitly and
+suppress the ``PendingDeprecationWarning``.
 
 
 ``io.text_encoding``
 --------------------
 
-``TextIOWrapper`` is used indirectly in most cases.  For example, ``open``, and ``pathlib.Path.read_text()`` use it.  Warning to these
+``TextIOWrapper`` is used indirectly in most cases. For example,
-functions doesn't make sense.  Callers of these functions should be warned instead.
+``open``, and ``pathlib.Path.read_text()`` use it. Warning to these
+functions doesn't make sense. Callers of these functions should be
+warned instead.
 
-``io.text_encoding(encoding, stacklevel=1)`` is a helper function for it.
+``io.text_encoding(encoding, stacklevel=1)`` is a helper function for
-Pure Python implementation will be like this::
+it. Pure Python implementation will be like this::
 
    def text_encoding(encoding, stacklevel=1):
        """
@@ -115,7 +119,7 @@ Pure Python implementation will be like this::
                import warnings
                warnings.warn(
                        "'encoding' option is not specified. The default encoding "
-                       "will be changed to 'utf-8' in the future",
+                       "might be changed to 'utf-8' in the future",
                        PendingDeprecationWarning, stacklevel + 2)
            encoding = "locale"
        return encoding
@@ -135,8 +139,8 @@ subprocess module doesn't warn
 ------------------------------
 
 While the subprocess module uses TextIOWrapper, it doesn't raise
-``PendingDeprecationWarning``.  It uses the "locale" encoding
+``PendingDeprecationWarning``.  It uses the "locale" encoding by
-by default.
+default.
 
 
 Rationale
@@ -156,8 +160,9 @@ the codec.
 Use a PendingDeprecationWarning
 -------------------------------
 
-This PEP doesn't make decision about changing default text encoding.
+This PEP doesn't cover changing the default encoding to UTF-8.
-So we use ``PendingDeprecationWarning`` instead of ``DeprecationWarning`` for now.
+So we use ``PendingDeprecationWarning`` instead of
+``DeprecationWarning`` for now.
 
 
 Raise warning only in dev mode
@@ -166,15 +171,17 @@ Raise warning only in dev mode
 This PEP will produce a huge amount of ``PendingDeprecationWarning``.
 It will be too noisy for most Python developers.
 
-We need to fix warnings in standard library, pip, and major dev tools
+We need to fix all warnings in the standard library. We need to wait
-like ``pytest`` before raise this warning by default.
+pip and major dev tools like ``pytest`` fix warnings before raising
+this warning by default.
 
 
 subprocess module doesn't warn
 ------------------------------
 
-The default encoding for PIPE is relating to the encoding of the stdio.
+The default encoding for PIPE is relating to the encoding of the
-It should be discussed later.
+stdio than the default encoding of ``TextIOWrapper``. So this PEP
+doesn't propose to raise warning from the subprocess module.
 
 
 Reference Implementation