Skip to content

Commit fc00667

Browse files
authored
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.
1 parent 764e83d commit fc00667

File tree

2 files changed

+30
-60
lines changed

2 files changed

+30
-60
lines changed

Doc/c-api/unicode.rst

+24-38
Original file line numberDiff line numberDiff line change
@@ -645,8 +645,7 @@ system.
645645
cannot contain embedded null characters.
646646
647647
Use :c:func:`PyUnicode_DecodeFSDefaultAndSize` to decode a string from
648-
:c:data:`Py_FileSystemDefaultEncoding` (the locale encoding read at
649-
Python startup).
648+
the :term:`filesystem encoding and error handler`.
650649
651650
This function ignores the :ref:`Python UTF-8 Mode <utf8-mode>`.
652651
@@ -680,9 +679,8 @@ system.
680679
*errors* is ``NULL``. Return a :class:`bytes` object. *unicode* cannot
681680
contain embedded null characters.
682681
683-
Use :c:func:`PyUnicode_EncodeFSDefault` to encode a string to
684-
:c:data:`Py_FileSystemDefaultEncoding` (the locale encoding read at
685-
Python startup).
682+
Use :c:func:`PyUnicode_EncodeFSDefault` to encode a string to the
683+
:term:`filesystem encoding and error handler`.
686684
687685
This function ignores the :ref:`Python UTF-8 Mode <utf8-mode>`.
688686
@@ -703,12 +701,12 @@ system.
703701
File System Encoding
704702
""""""""""""""""""""
705703
706-
To encode and decode file names and other environment strings,
707-
:c:data:`Py_FileSystemDefaultEncoding` should be used as the encoding, and
708-
:c:data:`Py_FileSystemDefaultEncodeErrors` should be used as the error handler
709-
(:pep:`383` and :pep:`529`). To encode file names to :class:`bytes` during
710-
argument parsing, the ``"O&"`` converter should be used, passing
711-
:c:func:`PyUnicode_FSConverter` as the conversion function:
704+
Functions encoding to and decoding from the :term:`filesystem encoding and
705+
error handler` (:pep:`383` and :pep:`529`).
706+
707+
To encode file names to :class:`bytes` during argument parsing, the ``"O&"``
708+
converter should be used, passing :c:func:`PyUnicode_FSConverter` as the
709+
conversion function:
712710
713711
.. c:function:: int PyUnicode_FSConverter(PyObject* obj, void* result)
714712
@@ -745,49 +743,39 @@ conversion function:
745743
746744
Decode a string from the :term:`filesystem encoding and error handler`.
747745
748-
If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to the
749-
locale encoding.
750-
751-
:c:data:`Py_FileSystemDefaultEncoding` is initialized at startup from the
752-
locale encoding and cannot be modified later. If you need to decode a string
753-
from the current locale encoding, use
746+
If you need to decode a string from the current locale encoding, use
754747
:c:func:`PyUnicode_DecodeLocaleAndSize`.
755748
756749
.. seealso::
757750
758751
The :c:func:`Py_DecodeLocale` function.
759752
760753
.. versionchanged:: 3.6
761-
Use :c:data:`Py_FileSystemDefaultEncodeErrors` error handler.
754+
The :term:`filesystem error handler <filesystem encoding and error
755+
handler>` is now used.
762756
763757
764758
.. c:function:: PyObject* PyUnicode_DecodeFSDefault(const char *s)
765759
766760
Decode a null-terminated string from the :term:`filesystem encoding and
767761
error handler`.
768762
769-
If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to the
770-
locale encoding.
771-
772-
Use :c:func:`PyUnicode_DecodeFSDefaultAndSize` if you know the string length.
763+
If the string length is known, use
764+
:c:func:`PyUnicode_DecodeFSDefaultAndSize`.
773765
774766
.. versionchanged:: 3.6
775-
Use :c:data:`Py_FileSystemDefaultEncodeErrors` error handler.
767+
The :term:`filesystem error handler <filesystem encoding and error
768+
handler>` is now used.
776769
777770
778771
.. c:function:: PyObject* PyUnicode_EncodeFSDefault(PyObject *unicode)
779772
780-
Encode a Unicode object to :c:data:`Py_FileSystemDefaultEncoding` with the
781-
:c:data:`Py_FileSystemDefaultEncodeErrors` error handler, and return
782-
:class:`bytes`. Note that the resulting :class:`bytes` object may contain
783-
null bytes.
784-
785-
If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to the
786-
locale encoding.
773+
Encode a Unicode object to the :term:`filesystem encoding and error
774+
handler`, and return :class:`bytes`. Note that the resulting :class:`bytes`
775+
object can contain null bytes.
787776
788-
:c:data:`Py_FileSystemDefaultEncoding` is initialized at startup from the
789-
locale encoding and cannot be modified later. If you need to encode a string
790-
to the current locale encoding, use :c:func:`PyUnicode_EncodeLocale`.
777+
If you need to encode a string to the current locale encoding, use
778+
:c:func:`PyUnicode_EncodeLocale`.
791779
792780
.. seealso::
793781
@@ -796,7 +784,8 @@ conversion function:
796784
.. versionadded:: 3.2
797785
798786
.. versionchanged:: 3.6
799-
Use :c:data:`Py_FileSystemDefaultEncodeErrors` error handler.
787+
The :term:`filesystem error handler <filesystem encoding and error
788+
handler>` is now used.
800789
801790
wchar_t Support
802791
"""""""""""""""
@@ -861,10 +850,7 @@ constructor.
861850
Setting encoding to ``NULL`` causes the default encoding to be used
862851
which is UTF-8. The file system calls should use
863852
:c:func:`PyUnicode_FSConverter` for encoding file names. This uses the
864-
variable :c:data:`Py_FileSystemDefaultEncoding` internally. This
865-
variable should be treated as read-only: on some systems, it will be a
866-
pointer to a static string, on others, it will change at run-time
867-
(such as when the application invokes setlocale).
853+
:term:`filesystem encoding and error handler` internally.
868854
869855
Error handling is set by errors which may also be set to ``NULL`` meaning to use
870856
the default handling defined for the codec. Default error handling for all

Include/unicodeobject.h

+6-22
Original file line numberDiff line numberDiff line change
@@ -755,38 +755,22 @@ PyAPI_FUNC(int) PyUnicode_FSConverter(PyObject*, void*);
755755

756756
PyAPI_FUNC(int) PyUnicode_FSDecoder(PyObject*, void*);
757757

758-
/* Decode a null-terminated string using Py_FileSystemDefaultEncoding
759-
and the "surrogateescape" error handler.
760-
761-
If Py_FileSystemDefaultEncoding is not set, fall back to the locale
762-
encoding.
763-
764-
Use PyUnicode_DecodeFSDefaultAndSize() if the string length is known.
765-
*/
758+
/* Decode a null-terminated string from the Python filesystem encoding
759+
and error handler.
766760
761+
If the string length is known, use PyUnicode_DecodeFSDefaultAndSize(). */
767762
PyAPI_FUNC(PyObject*) PyUnicode_DecodeFSDefault(
768763
const char *s /* encoded string */
769764
);
770765

771-
/* Decode a string using Py_FileSystemDefaultEncoding
772-
and the "surrogateescape" error handler.
773-
774-
If Py_FileSystemDefaultEncoding is not set, fall back to the locale
775-
encoding.
776-
*/
777-
766+
/* Decode a string from the Python filesystem encoding and error handler. */
778767
PyAPI_FUNC(PyObject*) PyUnicode_DecodeFSDefaultAndSize(
779768
const char *s, /* encoded string */
780769
Py_ssize_t size /* size */
781770
);
782771

783-
/* Encode a Unicode object to Py_FileSystemDefaultEncoding with the
784-
"surrogateescape" error handler, and return bytes.
785-
786-
If Py_FileSystemDefaultEncoding is not set, fall back to the locale
787-
encoding.
788-
*/
789-
772+
/* Encode a Unicode object to the Python filesystem encoding and error handler.
773+
Return bytes. */
790774
PyAPI_FUNC(PyObject*) PyUnicode_EncodeFSDefault(
791775
PyObject *unicode
792776
);

0 commit comments

Comments
 (0)