mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-25 01:43:11 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 14

gh-90241: Clarify documentation for PyUnicode_FSConverter and PyUnicode_FSDecoder (GH-128451)

Browse source 
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
This commit is contained in:
Serhiy Storchaka 2025-01-06 14:28:50 +02:00 • committed by GitHub
parent 1ef6bf4e29
commit 657d7b77e5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 36 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

35
Doc/c-api/unicode.rst
View file

@ -786,16 +786,25 @@ 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
converter should be used, passing :c:func:`!PyUnicode_FSConverter` as the
conversion function:
.. c:function:: int PyUnicode_FSConverter(PyObject* obj, void* result)
ParseTuple converter: encode :class:`str` objects -- obtained directly or
:ref:`PyArg_Parse\* converter <arg-parsing>`: encode :class:`str` objects -- obtained directly or
through the :class:`os.PathLike` interface -- to :class:`bytes` using
:c:func:`PyUnicode_EncodeFSDefault`; :class:`bytes` objects are output as-is.
*result* must be a :c:expr:`PyBytesObject*` which must be released when it is
no longer used.
*result* must be an address of a C variable of type :c:expr:`PyObject*`
(or :c:expr:`PyBytesObject*`).
On success, set the variable to a new :term:`strong reference` to
a :ref:`bytes object <bytesobjects>` which must be released
when it is no longer used and return a non-zero value
(:c:macro:`Py_CLEANUP_SUPPORTED`).
Embedded null bytes are not allowed in the result.
On failure, return ``0`` with an exception set.
If *obj* is ``NULL``, the function releases a strong reference
stored in the variable referred by *result* and returns ``1``.
.. versionadded:: 3.1
@ -803,16 +812,26 @@ conversion function:
Accepts a :term:`path-like object`.
To decode file names to :class:`str` during argument parsing, the ``"O&"``
converter should be used, passing :c:func:`PyUnicode_FSDecoder` as the
converter should be used, passing :c:func:`!PyUnicode_FSDecoder` as the
conversion function:
.. c:function:: int PyUnicode_FSDecoder(PyObject* obj, void* result)
ParseTuple converter: decode :class:`bytes` objects -- obtained either
:ref:`PyArg_Parse\* converter <arg-parsing>`: decode :class:`bytes` objects -- obtained either
directly or indirectly through the :class:`os.PathLike` interface -- to
:class:`str` using :c:func:`PyUnicode_DecodeFSDefaultAndSize`; :class:`str`
objects are output as-is. *result* must be a :c:expr:`PyUnicodeObject*` which
must be released when it is no longer used.
objects are output as-is.
*result* must be an address of a C variable of type :c:expr:`PyObject*`
(or :c:expr:`PyUnicodeObject*`).
On success, set the variable to a new :term:`strong reference` to
a :ref:`Unicode object <unicodeobjects>` which must be released
when it is no longer used and return a non-zero value
(:c:macro:`Py_CLEANUP_SUPPORTED`).
Embedded null characters are not allowed in the result.
On failure, return ``0`` with an exception set.
If *obj* is ``NULL``, release the strong reference
to the object referred to by *result* and return ``1``.
.. versionadded:: 3.2