From 9c796cb923ef39ab79f38a2a5d4796bab0753b76 Mon Sep 17 00:00:00 2001
From: Toshaksha <147024929+Toshaksha@users.noreply.github.com>
Date: Sun, 27 Jul 2025 22:07:52 +0530
Subject: [PATCH] gh-136278: Document codecs.escape_encode() and
 codecs.escape_decode() (GH-136314)

Closes GH-136278
(cherry picked from commit 6784ef7da7cbf1a944fd0685630ced54e4a0066c)

Co-authored-by: Toshaksha <147024929+Toshaksha@users.noreply.github.com>
---
 Doc/library/codecs.rst | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 1cb0e225bca043..f96f2f8281f450 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -1483,6 +1483,36 @@ to :class:`bytes` mappings. They are not supported by :meth:`bytes.decode`
    Restoration of the aliases for the binary transforms.
 
 
+.. _standalone-codec-functions:
+
+Standalone Codec Functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following functions provide encoding and decoding functionality similar to codecs,
+but are not available as named codecs through :func:`codecs.encode` or :func:`codecs.decode`.
+They are used internally (for example, by :mod:`pickle`) and behave similarly to the
+``string_escape`` codec that was removed in Python 3.
+
+.. function:: codecs.escape_encode(input, errors=None)
+
+   Encode *input* using escape sequences. Similar to how :func:`repr` on bytes
+   produces escaped byte values.
+
+   *input* must be a :class:`bytes` object.
+
+   Returns a tuple ``(output, length)`` where *output* is a :class:`bytes`
+   object and *length* is the number of bytes consumed.
+
+.. function:: codecs.escape_decode(input, errors=None)
+
+   Decode *input* from escape sequences back to the original bytes.
+
+   *input* must be a :term:`bytes-like object`.
+
+   Returns a tuple ``(output, length)`` where *output* is a :class:`bytes`
+   object and *length* is the number of bytes consumed.
+
+
 .. _text-transforms:
 
 Text Transforms