Issue #9542: Create PyUnicode_FSDecoder() function
It's a ParseTuple converter: decode bytes objects to unicode using
PyUnicode_DecodeFSDefaultAndSize(); str objects are output as-is.
* Don't specify surrogateescape error handler in the comments nor the
documentation, but PyUnicode_DecodeFSDefaultAndSize() and
PyUnicode_EncodeFSDefault() because these functions use strict error handler
for the mbcs encoding (on Windows).
* Remove PyUnicode_FSConverter() comment in unicodeobject.c to avoid
inconsistency with unicodeobject.h.
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index fa460a8..913fd69 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -380,13 +380,25 @@
.. cfunction:: int PyUnicode_FSConverter(PyObject* obj, void* result)
- Convert *obj* into *result*, using :cdata:`Py_FileSystemDefaultEncoding`,
- and the ``"surrogateescape"`` error handler. *result* must be a
- ``PyObject*``, return a :func:`bytes` object which must be released if it
- is no longer used.
+ ParseTuple converter: encode :class:`str` objects to :class:`bytes` using
+ :cfunc:`PyUnicode_EncodeFSDefault`; :class:`bytes` objects are output as-is.
+ *result* must be a :ctype:`PyBytesObject*` which must be released when it is
+ no longer used.
.. versionadded:: 3.1
+To decode file names during argument parsing, the ``"O&"`` converter should be
+used, passsing :func:`PyUnicode_FSDecoder` as the conversion function:
+
+.. cfunction:: int PyUnicode_FSDecoder(PyObject* obj, void* result)
+
+ ParseTuple converter: decode :class:`bytes` objects to :class:`str` using
+ :cfunc:`PyUnicode_DecodeFSDefaultAndSize`; :class:`str` objects are output
+ as-is. *result* must be a :ctype:`PyUnicodeObject*` which must be released
+ when it is no longer used.
+
+ .. versionadded:: 3.2
+
.. cfunction:: PyObject* PyUnicode_DecodeFSDefaultAndSize(const char *s, Py_ssize_t size)
Decode a null-terminated string using :cdata:`Py_FileSystemDefaultEncoding`