gh-136278: Document codecs.escape_encode() and codecs.escape_decode() #136314
Conversation
|
Hi @StanFromIreland, Thanks for the feedback and guidance throughout this process! Looking forward to your review! Best regards, |
|
Hello, in the future please reuse prs, it creates clutter otherwise. I will review later. |
|
Thanks, noted! I'll make sure to reuse PRs going forward. |
Doc/library/codecs.rst
Outdated
| | zlib_codec | zip, zlib | Compress the operand using | :meth:`zlib.compress` / | | ||
| | | | gzip. | :meth:`zlib.decompress` | | ||
| +----------------------+------------------+------------------------------+------------------------------+ | ||
|
|
||
| .. function:: codecs.escape_encode(input, errors='strict') |
There was a problem hiding this comment.
Where is errors='strict' from?
cpython/Modules/_codecsmodule.c
Line 178 in 5de7e3f
There was a problem hiding this comment.
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!
Doc/library/codecs.rst
Outdated
| | | | sequences using escape | / | | ||
| | | | sequences, similar to | :func:`codecs.escape_decode` | | ||
| | | | :func:`repr` of bytes. | | | ||
| +----------------------+------------------+------------------------------+------------------------------+ |
There was a problem hiding this comment.
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.
Doc/library/codecs.rst
Outdated
| | zlib_codec | zip, zlib | Compress the operand using | :meth:`zlib.compress` / | | ||
| | | | gzip. | :meth:`zlib.decompress` | | ||
| +----------------------+------------------+------------------------------+------------------------------+ | ||
|
|
||
| .. function:: codecs.escape_encode(input, errors=None) |
There was a problem hiding this comment.
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.
Doc/library/codecs.rst
Outdated
| 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. | ||
|
|
There was a problem hiding this comment.
We should document that input needs to be a bytes object.
Doc/library/codecs.rst
Outdated
|
|
||
| Decode *input* from escape sequences back to the original bytes. | ||
| Returns a tuple of the decoded bytes and the length consumed. | ||
|
|
There was a problem hiding this comment.
We should document that input needs to be a bytes or buffer compatible object.
|
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. |
|
Thanks for making the requested changes! @malemburg: please review the changes made to this pull request. |
a7553c6 to
4b26d7d
Compare
|
Hi @malemburg , |
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
📚 Documentation preview 📚: https://cpython-previews--136314.org.readthedocs.build/