iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PEP 597: Minor edit (#1448)

This commit is contained in:
Inada Naoki 2020-06-23 10:35:56 +09:00 committed by GitHub
parent 977f841a11
commit c536c5f971
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 36 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
pep-0597.rst
View File

@ -1,7 +1,7 @@
PEP: 597 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> Author: Inada Naoki <songofacandy@gmail.com>
Discussions-To: https://discuss.python.org/t/3880 Discussions-To: https://discuss.python.org/t/3880
Status: Draft Status: Draft
Type: Standards Track Type: Standards Track
@ -16,17 +16,17 @@ Abstract
This PEP proposes: This PEP proposes:
* ``TextIOWrapper`` raises a ``PendingDeprecationWarning`` when the * ``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 * Add ``encoding="locale"`` option to ``TextIOWrapper``. It behaves
like ``encoding=None`` but don't raise a warning. like ``encoding=None`` but don't raise a warning.
Motivation 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 Developers using macOS or Linux may forget that the default encoding
is not always UTF-8. is not always UTF-8.
@ -34,12 +34,13 @@ is not always UTF-8.
For example, ``long_description = open("README.md").read()`` in For example, ``long_description = open("README.md").read()`` in
``setup.py`` is a common mistake. Many Windows users can not install ``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) 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 For example, 489 packages of the 4000 most downloaded packages from
PyPI used non-ASCII characters in README. And 82 packages of them PyPI used non-ASCII characters in README. And 82 packages of them
can not be installed from source package when locale encoding is 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")``. Another example is ``logging.basicConfig(filename="log.txt")``.
Some users expect UTF-8 is used by default, but locale encoding is Some users expect UTF-8 is used by default, but locale encoding is
@ -56,12 +57,12 @@ Prepare to change the default encoding to UTF-8
----------------------------------------------- -----------------------------------------------
We chose to use locale encoding for the default text encoding We chose to use locale encoding for the default text encoding
in Python 3.0. But UTF-8 has been adopted very widely since then. in Python 3.0. But UTF-8 has been adopted very widely since then.
We might change the default text encoding to UTF-8 in the future. We might change the default text encoding to UTF-8 in the future.
But this change will affect many applications and libraries. But this change will affect many applications and libraries.
Many ``DeprecationWarning`` will be raised if we start raising Many ``DeprecationWarning`` will be raised if we start raising
the warning by default. It will be too noisy. the warning by default. It will be too noisy.
While this PEP doesn't cover the change, this PEP will help to reduce While this PEP doesn't cover the change, this PEP will help to reduce
the number of ``DeprecationWarning`` in the future. the number of ``DeprecationWarning`` in the future.
@ -74,30 +75,33 @@ Raising a PendingDeprecationWarning
--------------------------------------- ---------------------------------------
``TextIOWrapper`` raises the ``PendingDeprecationWarning`` when the ``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 ``encoding="locale"`` option
---------------------------- ----------------------------
When ``encoding="locale"`` is specified to the ``TextIOWrapper``, it 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())`` 1. ``os.device_encoding(buffer.fileno())``
2. ``locale.getpreferredencoding(False)`` 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`` ``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): def text_encoding(encoding, stacklevel=1):
""" """
@ -115,7 +119,7 @@ Pure Python implementation will be like this::
import warnings import warnings
warnings.warn( warnings.warn(
"'encoding' option is not specified. The default encoding " "'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) PendingDeprecationWarning, stacklevel + 2)
encoding = "locale" encoding = "locale"
return encoding return encoding
@ -135,8 +139,8 @@ subprocess module doesn't warn
------------------------------ ------------------------------
While the subprocess module uses TextIOWrapper, it doesn't raise 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 Rationale
@ -149,15 +153,16 @@ We don't add the "locale" to the codec alias because locale can be
changed in runtime. changed in runtime.
Additionally, ``TextIOWrapper`` checks ``os.device_encoding()`` Additionally, ``TextIOWrapper`` checks ``os.device_encoding()``
when ``encoding=None``. This behavior can not be implemented in when ``encoding=None``. This behavior can not be implemented in
the codec. the codec.
Use a PendingDeprecationWarning 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 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``. This PEP will produce a huge amount of ``PendingDeprecationWarning``.
It will be too noisy for most Python developers. 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 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 Reference Implementation