[Python-checkins] bpo-39287: Doc: Add UTF-8 mode section in using/windows. (GH-17935)

[Miss Islington (bot)]

https://github.com/python/cpython/commit/5a49ccac443ae84b8e142473a659c73032e9fe53
commit: 5a49ccac443ae84b8e142473a659c73032e9fe53
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at 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 at gmail.com>
(cherry picked from commit 148610d88a2785751ed435a4e60f07a9f1bc50a6)

Co-authored-by: Inada Naoki <songofacandy at 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