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

4 files changed, 21 insertions, 0 deletions

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index aaf7920..2426c37 100644
--- 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 4b02ecd..888ebd0 100644
--- 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
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 57dc4a1..c2de4ec 100644
--- 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;
     }