Issue #6012: Add cleanup support to O& argument parsing.
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index dcf7547..e968c8f 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -250,6 +250,14 @@
the conversion has failed. When the conversion fails, the *converter* function
should raise an exception and leave the content of *address* unmodified.
+ If the *converter* returns Py_CLEANUP_SUPPORTED, it may get called a second time
+ if the argument parsing eventually fails, giving the converter a chance to release
+ any memory that it had already allocated. In this second call, the *object* parameter
+ will be NULL; *address* will have the same value as in the original call.
+
+ .. versionchanged:: 3.1
+ Py_CLEANUP_SUPPORTED was added.
+
``S`` (string) [PyStringObject \*]
Like ``O`` but requires that the Python object is a string object. Raises
:exc:`TypeError` if the object is not a string object. The C variable may also
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index d6cedac..e348ee7 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -379,11 +379,13 @@
parameters encoding and errors have the same semantics as the ones of the
builtin unicode() Unicode object constructor.
-Setting encoding to *NULL* causes the default encoding to be used which is
-ASCII. The file system calls should use :cdata:`Py_FileSystemDefaultEncoding`
-as the encoding for file names. 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).
+Setting encoding to *NULL* causes the default encoding to be used
+which is ASCII. The file system calls should use
+:cfunc:`PyUnicode_FSConverter` for encoding file names. This uses the
+variable :cdata:`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).
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
@@ -782,6 +784,19 @@
object. Error handling is "strict". Return *NULL* if an exception was
raised by the codec.
+For decoding file names and other environment strings, :cdata:`Py_FileSystemEncoding`
+should be used as the encoding, and ``"surrogateescape"`` should be used as the error
+handler. For encoding file names during argument parsing, the ``O&`` converter should
+be used, passsing PyUnicode_FSConverter as the conversion function:
+
+.. cfunction:: int PyUnicode_FSConverter(PyObject* obj, void* result)
+
+ Convert *obj* into *result*, using the file system encoding, and the ``surrogateescape``
+ error handler. *result* must be a ``PyObject*``, yielding a bytes or bytearray object
+ which must be released if it is no longer used.
+
+ .. versionadded:: 3.1
+
.. % --- Methods & Slots ----------------------------------------------------