PEP 597: Minor edit (#1448)
This commit is contained in:
Inada Naoki
GitHub
parent
977f841a11
commit
c536c5f971
65
pep-0597.rst
65
pep-0597.rst
|
|
@ -1,7 +1,7 @@
|
|||
PEP: 597
|
||||
Title: Soft deprecation of omitting encoding
|
||||
Last-Modified: 14-Apr-2020
|
||||
Author: Inada Naoki <songofacandy@gmail.com>
|
||||
Title: Soft deprecation of default encoding
|
||||
Last-Modified: 23-Jun-2020
|
||||
Author: Inada Naoki <songofacandy@gmail.com>
|
||||
Discussions-To: https://discuss.python.org/t/3880
|
||||
Status: Draft
|
||||
Type: Standards Track
|
||||
|
|
@ -16,17 +16,17 @@ 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
|
||||
* Add ``encoding="locale"`` option to ``TextIOWrapper``. It behaves
|
||||
like ``encoding=None`` but don't raise a warning.
|
||||
|
||||
|
||||
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
|
||||
|
|
@ -56,12 +57,12 @@ Prepare to change the default encoding to UTF-8
|
|||
-----------------------------------------------
|
||||
|
||||
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.
|
||||
But this change will affect many applications and libraries.
|
||||
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
|
||||
the number of ``DeprecationWarning`` in the future.
|
||||
|
|
@ -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
|
||||
chosen by:
|
||||
behaves same to ``encoding=None`` except it doesn't raise warning.
|
||||
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
|
||||
functions doesn't make sense. Callers of these functions should be warned instead.
|
||||
``TextIOWrapper`` is used indirectly in most cases. For example,
|
||||
``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.
|
||||
Pure Python implementation will be like this::
|
||||
``io.text_encoding(encoding, stacklevel=1)`` is a helper function for
|
||||
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
|
||||
by default.
|
||||
``PendingDeprecationWarning``. It uses the "locale" encoding by
|
||||
default.
|
||||
|
||||
|
||||
Rationale
|
||||
|
|
@ -149,15 +153,16 @@ We don't add the "locale" to the codec alias because locale can be
|
|||
changed in runtime.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Use a PendingDeprecationWarning
|
||||
-------------------------------
|
||||
|
||||
This PEP doesn't make decision about changing default text encoding.
|
||||
So we use ``PendingDeprecationWarning`` instead of ``DeprecationWarning`` for now.
|
||||
This PEP doesn't cover changing the default encoding to UTF-8.
|
||||
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
|
||||
like ``pytest`` before raise this warning by default.
|
||||
We need to fix all warnings in the standard library. We need to wait
|
||||
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.
|
||||
It should be discussed later.
|
||||
The default encoding for PIPE is relating to the encoding of the
|
||||
stdio than the default encoding of ``TextIOWrapper``. So this PEP
|
||||
doesn't propose to raise warning from the subprocess module.
|
||||
|
||||
|
||||
Reference Implementation
|
||||
|
|
|
|||
Loading…
Reference in New Issue