https://github.com/python/cpython/commit/5a49ccac443ae84b8e142473a659c73032e... commit: 5a49ccac443ae84b8e142473a659c73032e9fe53 branch: 3.7 author: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> committer: GitHub <noreply@github.com> date: 2020-01-28T02:17:20-08:00 summary: bpo-39287: Doc: Add UTF-8 mode section in using/windows. (GH-17935) Co-Authored-By: Kyle Stanley <aeros167@gmail.com> (cherry picked from commit 148610d88a2785751ed435a4e60f07a9f1bc50a6) Co-authored-by: Inada Naoki <songofacandy@gmail.com> files: M Doc/using/cmdline.rst M Doc/using/windows.rst diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index 2c34ac29b68f2..6a1d7aa00d082 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -908,8 +908,6 @@ conflict. Also available as the :option:`-X` ``utf8`` option. - .. availability:: \*nix. - .. versionadded:: 3.7 See :pep:`540` for more details. diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst index bcc618ca143b3..f5dddb5a37af8 100644 --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -605,6 +605,50 @@ existed):: C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Python 3.7 +.. _win-utf8-mode: + +UTF-8 mode +========== + +.. versionadded:: 3.7 + +Windows still uses legacy encodings for the system encoding (the ANSI Code +Page). Python uses it for the default encoding of text files (e.g. +:func:`locale.getpreferredencoding`). + +This may cause issues because UTF-8 is widely used on the internet +and most Unix systems, including WSL (Windows Subsystem for Linux). + +You can use UTF-8 mode to change the default text encoding to UTF-8. +You can enable UTF-8 mode via the ``-X utf8`` command line option, or +the ``PYTHONUTF8=1`` environment variable. See :envvar:`PYTHONUTF8` for +enabling UTF-8 mode, and :ref:`setting-envvars` for how to modify +environment variables. + +When UTF-8 mode is enabled: + +* :func:`locale.getpreferredencoding` returns ``'UTF-8'`` instead of + the system encoding. This function is used for the default text + encoding in many places, including :func:`open`, :class:`Popen`, + :meth:`Path.read_text`, etc. +* :data:`sys.stdin`, :data:`sys.stdout`, and :data:`sys.stderr` + all use UTF-8 as their text encoding. +* You can still use the system encoding via the "mbcs" codec. + +Note that adding ``PYTHONUTF8=1`` to the default environment variables +will affect all Python 3.7+ applications on your system. +If you have any Python 3.7+ applications which rely on the legacy +system encoding, it is recommended to set the environment variable +temporarily or use the ``-X utf8`` command line option. + +.. note:: + Even when UTF-8 mode is disabled, Python uses UTF-8 by default + on Windows for: + + * Console I/O including standard I/O (see :pep:`528` for details). + * The filesystem encoding (see :pep:`529` for details). + + .. _launcher: Python Launcher for Windows