gh-73427: deprecate `_enablelegacywindowsfsencoding` (#107729)

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index aaf79205d44282b602bcadcb32a235e5b5b3b14d..2426c37ccb1e0f8310242acdfc3a94590c442639 100644 (file)
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -1744,9 +1744,17 @@ always available.
 
    .. availability:: Windows.
 
+   .. note::
+      Changing the filesystem encoding after Python startup is risky because
+      the old fsencoding or paths encoded by the old fsencoding may be cached
+      somewhere. Use :envvar:`PYTHONLEGACYWINDOWSFSENCODING` instead.
+
    .. versionadded:: 3.6
       See :pep:`529` for more details.
 
+   .. deprecated-removed:: 3.13 3.16
+      Use :envvar:`PYTHONLEGACYWINDOWSFSENCODING` instead.
+
 .. data:: stdin
           stdout
           stderr

diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index 4b02ecddd63b271b288edc3de875c756fb6349ae..888ebd0402d0e737a9fdf9ceb461ade759a10fd2 100644 (file)
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -474,6 +474,10 @@ Deprecated
   security and functionality bugs.  This includes removal of the ``--cgi``
   flag to the ``python -m http.server`` command line in 3.15.
 
+* :mod:`sys`: :func:`sys._enablelegacywindowsfsencoding` function.
+  Replace it with :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment variable.
+  (Contributed by Inada Naoki in :gh:`73427`.)
+
 * :mod:`traceback`:
 
   * The field *exc_type* of :class:`traceback.TracebackException` is

diff --git a/Misc/NEWS.d/next/Windows/2023-08-08-01-42-14.gh-issue-73427.WOpiNt.rst b/Misc/NEWS.d/next/Windows/2023-08-08-01-42-14.gh-issue-73427.WOpiNt.rst
new file mode 100644 (file)
index 0000000..830c4c5
--- /dev/null
+++ b/Misc/NEWS.d/next/Windows/2023-08-08-01-42-14.gh-issue-73427.WOpiNt.rst
@@ -0,0 +1,2 @@
+Deprecate :func:`sys._enablelegacywindowsfsencoding`. Use
+:envvar:`PYTHONLEGACYWINDOWSFSENCODING` instead. Patch by Inada Naoki.

diff --git a/Python/sysmodule.c b/Python/sysmodule.c
index 57dc4a1226ce7522c24888dda7b382e313cc8ac4..c2de4ecdc8ce0fee773c837f0ef033d447caf380 100644 (file)
--- a/Python/sysmodule.c
+++ b/Python/sysmodule.c
@@ -1715,6 +1715,13 @@ static PyObject *
 sys__enablelegacywindowsfsencoding_impl(PyObject *module)
 /*[clinic end generated code: output=f5c3855b45e24fe9 input=2bfa931a20704492]*/
 {
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+        "sys._enablelegacywindowsfsencoding() is deprecated and will be "
+        "removed in Python 3.16. Use PYTHONLEGACYWINDOWSFSENCODING "
+        "instead.", 1))
+    {
+        return NULL;
+    }
     if (_PyUnicode_EnableLegacyWindowsFSEncoding() < 0) {
         return NULL;
     }