From c5e746023d0b16d09e0e8e58f13f1be0abd7cbd6 Mon Sep 17 00:00:00 2001
From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Date: Fri, 9 May 2025 16:19:07 +0100
Subject: [PATCH] gh-46236: Document PyUnicode_BuildEncodingMap (GH-133270)
 (cherry picked from commit f34ec09ba51070b0693d7ced8e57e77d71beb48d)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
---
 Doc/c-api/unicode.rst  | 11 +++++++++++
 Doc/data/refcounts.dat |  3 +++
 2 files changed, 14 insertions(+)

diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 95987e872ce639..cdd90d05b70b36 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -645,6 +645,17 @@ APIs:
    difference being that it decrements the reference count of *right* by one.
 
 
+.. c:function:: PyObject* PyUnicode_BuildEncodingMap(PyObject* string)
+
+   Return a mapping suitable for decoding a custom single-byte encoding.
+   Given a Unicode string *string* of up to 256 characters representing an encoding
+   table, returns either a compact internal mapping object or a dictionary
+   mapping character ordinals to byte values. Raises a :exc:`TypeError` and
+   return ``NULL`` on invalid input.
+
+   .. versionadded:: 3.2
+
+
 .. c:function:: const char* PyUnicode_GetDefaultEncoding(void)
 
    Return the name of the default string encoding, ``"utf-8"``.
diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat
index ca99b9e6d37141..c97cd2b8d1e3cb 100644
--- a/Doc/data/refcounts.dat
+++ b/Doc/data/refcounts.dat
@@ -2781,6 +2781,9 @@ PyUnicode_AppendAndDel:void:::
 PyUnicode_AppendAndDel:PyObject**:p_left:0:
 PyUnicode_AppendAndDel:PyObject*:right:-1:
 
+PyUnicode_BuildEncodingMap:PyObject*::+1:
+PyUnicode_BuildEncodingMap:PyObject*:string:::
+
 PyUnicode_GetDefaultEncoding:const char*:::
 PyUnicode_GetDefaultEncoding::void::