Issue #8711: Document PyUnicode_DecodeFSDefault*() functions
* Add paragraph titles to c-api/unicode.rst.
* Fix PyUnicode_DecodeFSDefault*() comment: it now uses the "surrogateescape"
error handler (and not "replace")
* Remove "The function is intended to be used for paths and file names only
during bootstrapping process where the codecs are not set up." from
PyUnicode_FSConverter() comment: it is used after the bootstrapping and for
other purposes than file names
diff --git a/Include/unicodeobject.h b/Include/unicodeobject.h
index ff183f2..383187b 100644
--- a/Include/unicodeobject.h
+++ b/Include/unicodeobject.h
@@ -1240,25 +1240,29 @@
/* --- File system encoding ---------------------------------------------- */
/* ParseTuple converter which converts a Unicode object into the file
- system encoding as a bytes object, using the PEP 383 error handler; bytes
- objects are output as-is. */
+ system encoding as a bytes object, using the "surrogateescape" error
+ handler; bytes objects are output as-is. */
PyAPI_FUNC(int) PyUnicode_FSConverter(PyObject*, void*);
-/* Decode a null-terminated string using Py_FileSystemDefaultEncoding.
+/* Decode a null-terminated string using Py_FileSystemDefaultEncoding
+ and the "surrogateescape" error handler.
- If the encoding is supported by one of the built-in codecs (i.e., UTF-8,
- UTF-16, UTF-32, Latin-1 or MBCS), otherwise fallback to UTF-8 and replace
- invalid characters with '?'.
+ If Py_FileSystemDefaultEncoding is not set, fall back to UTF-8.
- The function is intended to be used for paths and file names only
- during bootstrapping process where the codecs are not set up.
+ Use PyUnicode_DecodeFSDefaultAndSize() if you have the string length.
*/
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 UTF-8.
+*/
+
PyAPI_FUNC(PyObject*) PyUnicode_DecodeFSDefaultAndSize(
const char *s, /* encoded string */
Py_ssize_t size /* size */