mirror of
https://github.com/python/cpython
synced 2024-09-16 01:13:03 +00:00
gh-93103: Update PyUnicode_DecodeFSDefault() doc (#93105)
Update documentation of PyUnicode_DecodeFSDefault(), PyUnicode_DecodeFSDefaultAndSize() and PyUnicode_EncodeFSDefault(): they now use the filesystem encoding and error handler of PyConfig, Py_FileSystemDefaultEncoding and Py_FileSystemDefaultEncodeErrors variables are no longer used.
This commit is contained in:
parent
764e83db85
commit
fc00667247
|
@ -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,12 +743,7 @@ 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::
|
||||
|
@ -758,7 +751,8 @@ conversion function:
|
|||
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)
|
||||
|
@ -766,28 +760,22 @@ conversion function:
|
|||
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.
|
||||
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.
|
||||
|
||||
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 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
|
||||
|
|
|
@ -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
|
||||
);
|
||||
|
|
Loading…
Reference in a new issue