gh-93103: Update PyUnicode_DecodeFSDefault() doc

Doc/c-api/unicode.rst

@@ -645,8 +645,7 @@ system.
    cannot contain embedded null characters.
 
    Use :c:func:`PyUnicode_DecodeFSDefaultAndSize` to decode a string from
-   :c:data:`Py_FileSystemDefaultEncoding` (the locale encoding read at
-   Python startup).
+   the :term:`filesystem encoding and error handler`.
 
    This function ignores the :ref:`Python UTF-8 Mode <utf8-mode>`.
 
@@ -680,9 +679,8 @@ system.
    *errors* is ``NULL``. Return a :class:`bytes` object. *unicode* cannot
    contain embedded null characters.
 
-   Use :c:func:`PyUnicode_EncodeFSDefault` to encode a string to
-   :c:data:`Py_FileSystemDefaultEncoding` (the locale encoding read at
-   Python startup).
+   Use :c:func:`PyUnicode_EncodeFSDefault` to encode a string to the
+   :term:`filesystem encoding and error handler`.
 
    This function ignores the :ref:`Python UTF-8 Mode <utf8-mode>`.
 
@@ -703,12 +701,12 @@ system.
 File System Encoding
 """"""""""""""""""""
 
-To encode and decode file names and other environment strings,
-:c:data:`Py_FileSystemDefaultEncoding` should be used as the encoding, and
-:c:data:`Py_FileSystemDefaultEncodeErrors` should be used as the error handler
-(:pep:`383` and :pep:`529`). To encode file names to :class:`bytes` during
-argument parsing, the ``"O&"`` converter should be used, passing
-:c:func:`PyUnicode_FSConverter` as the conversion function:
+Functions encoding to and decoding from the :term:`filesystem encoding and
+error handler` (:pep:`383` and :pep:`529`).
+
+To encode file names to :class:`bytes` during argument parsing, the ``"O&"``
+converter should be used, passing :c:func:`PyUnicode_FSConverter` as the
+conversion function:
 
 .. c:function:: int PyUnicode_FSConverter(PyObject* obj, void* result)
 
@@ -745,49 +743,39 @@ conversion function:
 
    Decode a string from the :term:`filesystem encoding and error handler`.
 
-   If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to the
-   locale encoding.
-
-   :c:data:`Py_FileSystemDefaultEncoding` is initialized at startup from the
-   locale encoding and cannot be modified later. If you need to decode a string
-   from the current locale encoding, use
+   If you need to decode a string from the current locale encoding, use
    :c:func:`PyUnicode_DecodeLocaleAndSize`.
 
    .. seealso::
 
       The :c:func:`Py_DecodeLocale` function.
 
    .. versionchanged:: 3.6
-      Use :c:data:`Py_FileSystemDefaultEncodeErrors` error handler.
+      The :term:`filesystem error handler <filesystem encoding and error
+      handler>` is now used.
 
 
 .. c:function:: PyObject* PyUnicode_DecodeFSDefault(const char *s)
 
    Decode a null-terminated string from the :term:`filesystem encoding and
    error handler`.
 
-   If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to the
-   locale encoding.
-
-   Use :c:func:`PyUnicode_DecodeFSDefaultAndSize` if you know the string length.
+   If the string length is known, use
+   :c:func:`PyUnicode_DecodeFSDefaultAndSize`.
 
    .. versionchanged:: 3.6
-      Use :c:data:`Py_FileSystemDefaultEncodeErrors` error handler.
+      The :term:`filesystem error handler <filesystem encoding and error
+      handler>` is now used.
 
 
 .. c:function:: PyObject* PyUnicode_EncodeFSDefault(PyObject *unicode)
 
-   Encode a Unicode object to :c:data:`Py_FileSystemDefaultEncoding` with the
-   :c:data:`Py_FileSystemDefaultEncodeErrors` error handler, and return
-   :class:`bytes`. Note that the resulting :class:`bytes` object may contain
-   null bytes.
-
-   If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to the
-   locale encoding.
+   Encode a Unicode object to the :term:`filesystem encoding and error
+   handler`, and return :class:`bytes`. Note that the resulting :class:`bytes`
+   object can contain null bytes.
 
-   :c:data:`Py_FileSystemDefaultEncoding` is initialized at startup from the
-   locale encoding and cannot be modified later. If you need to encode a string
-   to the current locale encoding, use :c:func:`PyUnicode_EncodeLocale`.
+   If you need to encode a string to the current locale encoding, use
+   :c:func:`PyUnicode_EncodeLocale`.
 
    .. seealso::
 
@@ -796,7 +784,8 @@ conversion function:
    .. versionadded:: 3.2
 
    .. versionchanged:: 3.6
-      Use :c:data:`Py_FileSystemDefaultEncodeErrors` error handler.
+      The :term:`filesystem error handler <filesystem encoding and error
+      handler>` is now used.
 
 wchar_t Support
 """""""""""""""
@@ -861,10 +850,7 @@ constructor.
 Setting encoding to ``NULL`` causes the default encoding to be used
 which is UTF-8.  The file system calls should use
 :c:func:`PyUnicode_FSConverter` for encoding file names. This uses the
-variable :c:data:`Py_FileSystemDefaultEncoding` internally. This
-variable should be treated as read-only: on some systems, it will be a
-pointer to a static string, on others, it will change at run-time
-(such as when the application invokes setlocale).
+:term:`filesystem encoding and error handler` internally.
 
 Error handling is set by errors which may also be set to ``NULL`` meaning to use
 the default handling defined for the codec.  Default error handling for all

Include/unicodeobject.h

@@ -755,38 +755,22 @@ PyAPI_FUNC(int) PyUnicode_FSConverter(PyObject*, void*);
 
 PyAPI_FUNC(int) PyUnicode_FSDecoder(PyObject*, void*);
 
-/* Decode a null-terminated string using Py_FileSystemDefaultEncoding
-   and the "surrogateescape" error handler.
-
-   If Py_FileSystemDefaultEncoding is not set, fall back to the locale
-   encoding.
-
-   Use PyUnicode_DecodeFSDefaultAndSize() if the string length is known.
-*/
+/* Decode a null-terminated string from the Python filesystem encoding
+   and error handler.
 
+   If the string length is known, use PyUnicode_DecodeFSDefaultAndSize(). */
 PyAPI_FUNC(PyObject*) PyUnicode_DecodeFSDefault(
     const char *s               /* encoded string */
     );
 
-/* Decode a string using Py_FileSystemDefaultEncoding
-   and the "surrogateescape" error handler.
-
-   If Py_FileSystemDefaultEncoding is not set, fall back to the locale
-   encoding.
-*/
-
+/* Decode a string from the Python filesystem encoding and error handler. */
 PyAPI_FUNC(PyObject*) PyUnicode_DecodeFSDefaultAndSize(
     const char *s,               /* encoded string */
     Py_ssize_t size              /* size */
     );
 
-/* Encode a Unicode object to Py_FileSystemDefaultEncoding with the
-   "surrogateescape" error handler, and return bytes.
-
-   If Py_FileSystemDefaultEncoding is not set, fall back to the locale
-   encoding.
-*/
-
+/* Encode a Unicode object to the Python filesystem encoding and error handler.
+   Return bytes. */
 PyAPI_FUNC(PyObject*) PyUnicode_EncodeFSDefault(
     PyObject *unicode
     );