[3.7] bpo-34589: Add -X coerce_c_locale option; C locale coercion off by default (GH-9379)

* bpo-34589: Make _PyCoreConfig.coerce_c_locale private (GH-9371)

_PyCoreConfig:

* Rename coerce_c_locale to _coerce_c_locale
* Rename coerce_c_locale_warn to _coerce_c_locale_warn

These fields are now private (name prefixed by "_").

(cherry picked from commit 188ebfa475a6f6aa2d0ea14ca8e1fbe7865b6d27)

* bpo-34589: C locale coercion off by default (GH-9073)

Py_Initialize() and Py_Main() cannot enable the C locale coercion
(PEP 538) anymore: it is always disabled. It can now only be enabled
by the Python program ("python3).

test_embed: get_filesystem_encoding() doesn't have to set PYTHONUTF8
nor PYTHONCOERCECLOCALE, these variables are already set in the
parent.

(cherry picked from commit 7a0791b6992d420dc52536257f2f093851ed7215)

* bpo-34589: Add -X coerce_c_locale command line option (GH-9378)

Add a new -X coerce_c_locale command line option to control C locale
coercion (PEP 538).

(cherry picked from commit dbdee0073cf0b88fe541980ace1f650900f455cc)

1 files changed, 15 insertions, 1 deletions

diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 70e8d1afb4..29de155f2d 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -438,10 +438,19 @@ Miscellaneous options
      * Set the :attr:`~sys.flags.dev_mode` attribute of :attr:`sys.flags` to
        ``True``
 
-   * ``-X utf8`` enables UTF-8 mode for operating system interfaces, overriding
+   * ``-X utf8`` enables UTF-8 mode (:pep:`540`) for operating system interfaces, overriding
      the default locale-aware mode. ``-X utf8=0`` explicitly disables UTF-8
      mode (even when it would otherwise activate automatically).
      See :envvar:`PYTHONUTF8` for more details.
+   * ``-X coerce_c_locale`` or ``-X coerce_c_locale=1`` tries to coerce the C
+     locale (:pep:`538`).
+     ``-X coerce_c_locale=0`` skips coercing the legacy ASCII-based C and POSIX
+     locales to a more capable UTF-8 based alternative.
+     ``-X coerce_c_locale=warn`` will cause Python to emit warning messages on
+     ``stderr`` if either the locale coercion activates, or else if a locale
+     that *would* have triggered coercion is still active when the Python
+     runtime is initialized.
+     See :envvar:`PYTHONCOERCECLOCALE` for more details.
 
    It also allows passing arbitrary values and retrieving them through the
    :data:`sys._xoptions` dictionary.
@@ -461,6 +470,9 @@ Miscellaneous options
    .. versionadded:: 3.7
       The ``-X importtime``, ``-X dev`` and ``-X utf8`` options.
 
+   .. versionadded:: 3.7.1
+      The ``-X coerce_c_locale`` option.
+
 
 Options you shouldn't use
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -834,6 +846,8 @@ conflict.
    order to force the interpreter to use ``ASCII`` instead of ``UTF-8`` for
    system interfaces.
 
+   Also available as the :option:`-X` ``coerce_c_locale`` option.
+
    Availability: \*nix
 
    .. versionadded:: 3.7