Skip to content

gh-99991: improve docs on str.encode and bytes.decode #100198

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Dec 21, 2022
Merged

gh-99991: improve docs on str.encode and bytes.decode #100198

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
317860f
improve str.encode and byte.decode
bizzyvinci Dec 12, 2022
86c44a4
remove trailing whitespace (to pass workflow)
bizzyvinci Dec 12, 2022
06aaf7b
Apply suggestions from code review: make docs for str.encode and byte…
bizzyvinci Dec 17, 2022
4330d08
Add back stripped newline seperating args in encode/decode
CAM-Gerlach Dec 17, 2022
dab7ee1
Clarify and refine wording of errors encode/decode arg desc
CAM-Gerlach Dec 17, 2022
17e9503
Refine text of notes and versionchanged for encode & decode
CAM-Gerlach Dec 17, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 17 additions & 13 deletions Doc/library/stdtypes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1625,13 +1625,15 @@ 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`.
is ``'utf-8'``. And for a list of possible encodings, see section
:ref:`standard-encodings`.

*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`.

By default, the *errors* argument is not checked for best performances, but
only used at the first encoding error. Enable the :ref:`Python Development
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was not able to actually make this as suggestion, but this implements the revision from the issue, while still including the key details from the previous version.

   For performance reasons, the value of *errors* is not checked for validity
   unless an encoding error actually occurs,
   :ref:`Python Development Mode <devmode>` is enabled
   or a :ref:`debug build <debug-build>` is used.

Expand Down Expand Up @@ -2760,12 +2762,14 @@ arbitrary binary data.
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`.
``'utf-8'``. And for a list of possible encodings, see section
:ref:`standard-encodings`.

*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`.

By default, the *errors* argument is not checked for best performances, but
only used at the first decoding error. Enable the :ref:`Python Development
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was not able to actually make this as suggestion, but this implements the revision from the issue, while still including the key details from the previous version.

   For performance reasons, the value of *errors* is not checked for validity
   unless a decoding error actually occurs,
   :ref:`Python Development Mode <devmode>` is enabled
   or a :ref:`debug build <debug-build>` is used.

Expand Down