[Python-checkins] gh-99991: improve docs on str.encode and bytes.decode (GH-100198)
miss-islington
webhook-mailer at python.org
Tue Dec 20 21:12:59 EST 2022
https://github.com/python/cpython/commit/23fa1667b364a73ed29074f257d2bcf41bd35019
commit: 23fa1667b364a73ed29074f257d2bcf41bd35019
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-12-20T18:12:53-08:00
summary:
gh-99991: improve docs on str.encode and bytes.decode (GH-100198)
(cherry picked from commit a2bb3b7f9d8d15c81b724726454d68357fb31d1c)
Co-authored-by: Bisola Olasehinde <horlasehinde at gmail.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach at Gerlach.CAM>
files:
M Doc/library/stdtypes.rst
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 426eec620566..a1514f611d4f 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1623,25 +1623,28 @@ expression support in the :mod:`re` module).
.. method:: str.encode(encoding="utf-8", errors="strict")
- Return an encoded version of the string as a bytes object. Default encoding
- is ``'utf-8'``. *errors* may be given to set a different error handling scheme.
- The default for *errors* is ``'strict'``, meaning that encoding errors raise
- a :exc:`UnicodeError`. Other possible
- values are ``'ignore'``, ``'replace'``, ``'xmlcharrefreplace'``,
- ``'backslashreplace'`` and any other name registered via
- :func:`codecs.register_error`, see section :ref:`error-handlers`. For a
- list of possible encodings, see section :ref:`standard-encodings`.
-
- By default, the *errors* argument is not checked for best performances, but
- only used at the first encoding error. Enable the :ref:`Python Development
- Mode <devmode>`, or use a :ref:`debug build <debug-build>` to check
- *errors*.
+ Return the string encoded to :class:`bytes`.
+
+ *encoding* defaults to ``'utf-8'``;
+ see :ref:`standard-encodings` for possible values.
+
+ *errors* controls how encoding errors are handled.
+ If ``'strict'`` (the default), a :exc:`UnicodeError` exception is raised.
+ Other possible values are ``'ignore'``,
+ ``'replace'``, ``'xmlcharrefreplace'``, ``'backslashreplace'`` and any
+ other name registered via :func:`codecs.register_error`.
+ See :ref:`error-handlers` for details.
+
+ For performance reasons, the value of *errors* is not checked for validity
+ unless an encoding error actually occurs,
+ :ref:`devmode` is enabled
+ or a :ref:`debug build <debug-build>` is used.
.. versionchanged:: 3.1
- Support for keyword arguments added.
+ Added support for keyword arguments.
.. versionchanged:: 3.9
- The *errors* is now checked in development mode and
+ The value of the *errors* argument is now checked in :ref:`devmode` and
in :ref:`debug mode <debug-build>`.
@@ -2755,29 +2758,32 @@ arbitrary binary data.
.. method:: bytes.decode(encoding="utf-8", errors="strict")
bytearray.decode(encoding="utf-8", errors="strict")
- Return a string decoded from the given bytes. Default encoding is
- ``'utf-8'``. *errors* may be given to set a different
- error handling scheme. The default for *errors* is ``'strict'``, meaning
- that encoding errors raise a :exc:`UnicodeError`. Other possible values are
- ``'ignore'``, ``'replace'`` and any other name registered via
- :func:`codecs.register_error`, see section :ref:`error-handlers`. For a
- list of possible encodings, see section :ref:`standard-encodings`.
+ Return the bytes decoded to a :class:`str`.
+
+ *encoding* defaults to ``'utf-8'``;
+ see :ref:`standard-encodings` for possible values.
+
+ *errors* controls how decoding errors are handled.
+ If ``'strict'`` (the default), a :exc:`UnicodeError` exception is raised.
+ Other possible values are ``'ignore'``, ``'replace'``,
+ and any other name registered via :func:`codecs.register_error`.
+ See :ref:`error-handlers` for details.
- By default, the *errors* argument is not checked for best performances, but
- only used at the first decoding error. Enable the :ref:`Python Development
- Mode <devmode>`, or use a :ref:`debug build <debug-build>` to check *errors*.
+ For performance reasons, the value of *errors* is not checked for validity
+ unless a decoding error actually occurs,
+ :ref:`devmode` is enabled or a :ref:`debug build <debug-build>` is used.
.. note::
Passing the *encoding* argument to :class:`str` allows decoding any
:term:`bytes-like object` directly, without needing to make a temporary
- bytes or bytearray object.
+ :class:`!bytes` or :class:`!bytearray` object.
.. versionchanged:: 3.1
Added support for keyword arguments.
.. versionchanged:: 3.9
- The *errors* is now checked in development mode and
+ The value of the *errors* argument is now checked in :ref:`devmode` and
in :ref:`debug mode <debug-build>`.
More information about the Python-checkins
mailing list