From fc00667247c47285751d77de7645c11a5393d870 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Mon, 23 May 2022 14:56:59 +0200 Subject: 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. --- Doc/c-api/unicode.rst | 62 +++++++++++++++++++------------------------------ Include/unicodeobject.h | 28 +++++----------------- 2 files changed, 30 insertions(+), 60 deletions(-) diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 9dccbf1..abcf0cd 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -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 `. @@ -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 `. @@ -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 ` 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 ` 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. - - If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to the - locale encoding. + 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. - :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 ` 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 diff --git a/Include/unicodeobject.h b/Include/unicodeobject.h index ed3e8d2..27fde22 100644 --- a/Include/unicodeobject.h +++ b/Include/unicodeobject.h @@ -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 ); -- cgit v0.12