gh-136278: Document codecs.escape_encode() and codecs.escape_decode() #136314

Toshaksha · 2025-07-05T07:12:49Z

This PR adds documentation for the functions codecs.escape_encode() and codecs.escape_decode(), which provide a way to encode and decode byte sequences using escape sequences, similar to how repr(bytes) works.

These APIs are primarily used by the pickle module for handling escaped byte sequences safely.

The documentation includes function signatures, a usage example, and background information referencing the previous usage in Python 2's string_escape codec and considerations for reviving this as bytes_escape.

Closes: #136278

Issue: Write documentation for codecs.escape_encode() and codecs.escape_decode() #136278

📚 Documentation preview 📚: https://cpython-previews--136314.org.readthedocs.build/

Toshaksha · 2025-07-05T07:17:15Z

Hi @StanFromIreland,

Thanks for the feedback and guidance throughout this process!
I have updated the documentation for codecs.escape_encode() and codecs.escape_decode() following the devguide and integrated it into the binary transforms section as suggested.
Please let me know if there are any further changes needed or if I missed anything.

Looking forward to your review!

Best regards,
Toshaksha

StanFromIreland · 2025-07-05T07:20:53Z

Hello, in the future please reuse prs, it creates clutter otherwise. I will review later.

Toshaksha · 2025-07-05T07:26:05Z

Thanks, noted! I'll make sure to reuse PRs going forward.

StanFromIreland · 2025-07-05T10:41:42Z

Doc/library/codecs.rst

 | zlib_codec           | zip, zlib        | Compress the operand using   | :meth:`zlib.compress` /      |
 |                      |                  | gzip.                        | :meth:`zlib.decompress`      |
 +----------------------+------------------+------------------------------+------------------------------+

+.. function:: codecs.escape_encode(input, errors='strict')


Where is errors='strict' from?

cpython/Modules/_codecsmodule.c

Line 178 in 5de7e3f

errors: str(accept={str, NoneType}) = None

Thanks for catching that!
I've updated the function signature to use errors=None in accordance with the actual default in _codecsmodule.c.
Let me know if there's anything else you'd like me to adjust. Appreciate your time and feedback!

malemburg · 2025-07-07T13:45:44Z

Doc/library/codecs.rst

+|                      |                  | sequences using escape       | /                            |
+|                      |                  | sequences, similar to        | :func:`codecs.escape_decode` |
+|                      |                  | :func:`repr` of bytes.       |                              |
+----------------------+------------------+------------------------------+------------------------------+


I don't think this is correct. The codec itself (string_escape) was removed after the transition to Python 3. There is no escape_codec to be documented, only the functions which could be used to create a new bytes_escape codec, but that's probably for a separate issue to take care of.

malemburg · 2025-07-07T13:53:01Z

Doc/library/codecs.rst

 | zlib_codec           | zip, zlib        | Compress the operand using   | :meth:`zlib.compress` /      |
 |                      |                  | gzip.                        | :meth:`zlib.decompress`      |
 +----------------------+------------------+------------------------------+------------------------------+

+.. function:: codecs.escape_encode(input, errors=None)


Please move this section below the table and its notes.

It may be good to also be good to put these function definitions into a section "Standalone Codec Functions", or something like that, to make it clear that the functions exist without a codec (at the moment) and perhaps with an explanation why this is.

malemburg · 2025-07-07T13:56:50Z

Doc/library/codecs.rst

+   Encode *input* using escape sequences. Similar to how :func:`repr` on bytes
+   produces escaped byte values. Returns a tuple of the encoded bytes and
+   the length consumed.
+


We should document that input needs to be a bytes object.

malemburg · 2025-07-07T13:56:52Z

Doc/library/codecs.rst

+
+   Decode *input* from escape sequences back to the original bytes.
+   Returns a tuple of the decoded bytes and the length consumed.
+


We should document that input needs to be a bytes or buffer compatible object.

bedevere-app · 2025-07-07T13:57:19Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

Toshaksha · 2025-07-08T05:17:37Z

I have made the requested changes; please review again.

bedevere-app · 2025-07-08T05:17:41Z

Thanks for making the requested changes!

@malemburg: please review the changes made to this pull request.

…ture

Toshaksha · 2025-07-12T05:14:58Z

Hi @malemburg ,
I’ve addressed all requested changes and pushed updates. Please let me know if anything else is needed.
Thanks!

malemburg

LGTM.

miss-islington-app · 2025-07-27T16:37:56Z

Thanks @Toshaksha for the PR, and @malemburg for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

…code() (pythonGH-136314) Closes pythonGH-136278 (cherry picked from commit 6784ef7) Co-authored-by: Toshaksha <147024929+Toshaksha@users.noreply.github.com>

bedevere-app · 2025-07-27T16:38:07Z

GH-137149 is a backport of this pull request to the 3.14 branch.

bedevere-app · 2025-07-27T16:38:10Z

GH-137150 is a backport of this pull request to the 3.13 branch.

…ecode() (GH-136314) (#137150) gh-136278: Document codecs.escape_encode() and codecs.escape_decode() (GH-136314) Closes GH-136278 (cherry picked from commit 6784ef7) Co-authored-by: Toshaksha <147024929+Toshaksha@users.noreply.github.com>

malemburg · 2025-07-27T16:44:45Z

Thanks, @Toshaksha

Toshaksha · 2025-07-27T17:51:32Z

Thanks @malemburg and @StanFromIreland for the review and merge!
Glad to see this wrapped up.

Toshaksha

bedevere-app bot added awaiting review docs Documentation in the Doc dir skip news labels Jul 5, 2025

bedevere-app bot mentioned this pull request Jul 5, 2025

Write documentation for codecs.escape_encode() and codecs.escape_decode() #136278

Closed

github-project-automation bot added this to Docs PRs Jul 5, 2025

github-project-automation bot moved this to Todo in Docs PRs Jul 5, 2025

StanFromIreland mentioned this pull request Jul 5, 2025

gh-136278: Add documentation for codecs.escape_encode() and codecs.escape_decode() #136310

Closed

StanFromIreland requested review from malemburg and StanFromIreland July 5, 2025 07:20

hugovk added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Jul 5, 2025

StanFromIreland reviewed Jul 5, 2025

View reviewed changes

malemburg requested changes Jul 7, 2025

View reviewed changes

bedevere-app bot added awaiting changes and removed awaiting review labels Jul 7, 2025

bedevere-app bot added awaiting change review and removed awaiting changes labels Jul 8, 2025

bedevere-app bot requested a review from malemburg July 8, 2025 05:17

Toshaksha added 4 commits July 12, 2025 10:39

Add documentation for codecs.escape_encode() and codecs.escape_decode()

648042b

Fix default value of 'errors' to None in escape_decode function signa…

e0fcfea

…ture

Move escape_encode and escape_decode to standalone section

7613bcd

Move escape_encode and escape_decode to standalone section

4b26d7d

Toshaksha force-pushed the doc-escape-codec-update branch from a7553c6 to 4b26d7d Compare July 12, 2025 05:09

malemburg approved these changes Jul 27, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting change review labels Jul 27, 2025

Merge branch 'main' into doc-escape-codec-update

989d674

malemburg enabled auto-merge (squash) July 27, 2025 16:36

malemburg merged commit 6784ef7 into python:main Jul 27, 2025
25 checks passed

github-project-automation bot moved this from Todo to Done in Docs PRs Jul 27, 2025

bedevere-app bot removed the awaiting merge label Jul 27, 2025

bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Jul 27, 2025

bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Jul 27, 2025

Toshaksha deleted the doc-escape-codec-update branch July 27, 2025 17:51


		Decode input from escape sequences back to the original bytes.
		Returns a tuple of the decoded bytes and the length consumed.

Uh oh!

gh-136278: Document codecs.escape_encode() and codecs.escape_decode() #136314

gh-136278: Document codecs.escape_encode() and codecs.escape_decode() #136314

Conversation

Toshaksha commented Jul 5, 2025 • edited by hugovk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Toshaksha commented Jul 5, 2025

Uh oh!

StanFromIreland commented Jul 5, 2025

Uh oh!

Toshaksha commented Jul 5, 2025

Uh oh!

StanFromIreland Jul 5, 2025

Choose a reason for hiding this comment

Uh oh!

Toshaksha Jul 5, 2025

Choose a reason for hiding this comment

Uh oh!

malemburg Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

malemburg Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

malemburg Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

malemburg Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

bedevere-app bot commented Jul 7, 2025

Uh oh!

Toshaksha commented Jul 8, 2025

Uh oh!

bedevere-app bot commented Jul 8, 2025

Uh oh!

Toshaksha commented Jul 12, 2025

Uh oh!

malemburg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-app bot commented Jul 27, 2025

Uh oh!

bedevere-app bot commented Jul 27, 2025

Uh oh!

bedevere-app bot commented Jul 27, 2025

Uh oh!

malemburg commented Jul 27, 2025

Uh oh!

Toshaksha commented Jul 27, 2025

Uh oh!

Uh oh!

Toshaksha commented Jul 5, 2025 •

edited by hugovk

Loading