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

55
pep-0597.rst
View File

@ -1,6 +1,6 @@
PEP: 597
Title: Soft deprecation of omitting encoding
Last-Modified: 14-Apr-2020
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
@ -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
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
@ -156,8 +160,9 @@ 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