summaryrefslogtreecommitdiffstats
path: root/Doc/using/cmdline.rst
diff options
context:
space:
mode:
authorNick Coghlan <ncoghlan@gmail.com>2017-06-11 03:16:15 (GMT)
committerGitHub <noreply@github.com>2017-06-11 03:16:15 (GMT)
commit6ea4186de32d65b1f1dc1533b6312b798d300466 (patch)
treebac8387f2da20d5b6d5f74bb09fb5708d1fbd61e /Doc/using/cmdline.rst
parent0afbabe245e2eb6f7cef3b70531d69f2a7ad8295 (diff)
downloadcpython-6ea4186de32d65b1f1dc1533b6312b798d300466.zip
cpython-6ea4186de32d65b1f1dc1533b6312b798d300466.tar.gz
cpython-6ea4186de32d65b1f1dc1533b6312b798d300466.tar.bz2
bpo-28180: Implementation for PEP 538 (#659)
- new PYTHONCOERCECLOCALE config setting - coerces legacy C locale to C.UTF-8, C.utf8 or UTF-8 by default - always uses C.UTF-8 on Android - uses `surrogateescape` on stdin and stdout in the coercion target locales - configure option to disable locale coercion at build time - configure option to disable C locale warning at build time
Diffstat (limited to 'Doc/using/cmdline.rst')
-rw-r--r--Doc/using/cmdline.rst36
1 files changed, 36 insertions, 0 deletions
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 40a06b9..920d5c0 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -713,6 +713,42 @@ conflict.
.. versionadded:: 3.6
+
+.. envvar:: PYTHONCOERCECLOCALE
+
+ If set to the value ``0``, causes the main Python command line application
+ to skip coercing the legacy ASCII-based C locale to a more capable UTF-8
+ based alternative. Note that this setting is checked even when the
+ :option:`-E` or :option:`-I` options are used, as it is handled prior to
+ the processing of command line options.
+
+ If this variable is *not* set, or is set to a value other than ``0``, and
+ the current locale reported for the ``LC_CTYPE`` category is the default
+ ``C`` locale, then the Python CLI will attempt to configure the following
+ locales for the ``LC_CTYPE`` category in the order listed before loading the
+ interpreter runtime:
+
+ * ``C.UTF-8``
+ * ``C.utf8``
+ * ``UTF-8``
+
+ If setting one of these locale categories succeeds, then the ``LC_CTYPE``
+ environment variable will also be set accordingly in the current process
+ environment before the Python runtime is initialized. This ensures the
+ updated setting is seen in subprocesses, as well as in operations that
+ query the environment rather than the current C locale (such as Python's
+ own :func:`locale.getdefaultlocale`).
+
+ Configuring one of these locales (either explicitly or via the above
+ implicit locale coercion) will automatically set the error handler for
+ :data:`sys.stdin` and :data:`sys.stdout` to ``surrogateescape``. This
+ behavior can be overridden using :envvar:`PYTHONIOENCODING` as usual.
+
+ Availability: \*nix
+
+ .. versionadded:: 3.7
+ See :pep:`538` for more details.
+
Debug-mode variables
~~~~~~~~~~~~~~~~~~~~