gh-76535: Make PyUnicode_ToLowerFull and friends public

Doc/c-api/unicode.rst

@@ -307,6 +307,55 @@ These APIs can be used for fast direct character conversions:
    possible.  This function does not raise exceptions.
 
 
+.. c:function:: Py_ssize_t PyUnicode_ToLower(Py_UCS4 ch, Py_UCS4 *buffer, int size)
+
+   Convert *ch* to lower case, store result in *buffer*, which should be
+   able to hold as many characters needed for *ch* to be lower cased
+   (e.g. a maximum of two character for Unicode 16.0), and
+   return the number of characters stored. Passing a ``NULL`` buffer returns
+   the buffer size needed. If at some point a buffer overflow is detected,
+   an :exc:`ValueError` is raised and ``-1`` is returned.
+
+   .. versionadded:: next
+
+
+.. c:function:: Py_ssize_t PyUnicode_ToUpper(Py_UCS4 ch, Py_UCS4 *buffer, int size)
+
+   Convert *ch* to upper case, store result in *buffer*, which should be
+   able to hold as many characters needed for *ch* to be upper cased
+   (e.g. a maximum of three character for Unicode 16.0), and
+   return the number of characters stored. Passing a ``NULL`` buffer returns
+   the buffer size needed. If at some point a buffer overflow is detected,
+   an :exc:`ValueError` is raised and ``-1`` is returned.
+
+   .. versionadded:: next
+
+
+.. c:function:: Py_ssize_t PyUnicode_ToTitle(Py_UCS4 ch, Py_UCS4 *buffer, int size)
+
+   Convert *ch* to title case, store result in *buffer*, which should be
+   able to hold as many characters needed for *ch* to be title cased
+   (e.g. a maximum of three character for Unicode 16.0), and
+   return the number of characters stored. Passing a ``NULL`` buffer returns
+   the buffer size needed. If at some point a buffer overflow is detected,
+   an :exc:`ValueError` is raised and ``-1`` is returned.
+
+   .. versionadded:: next
+
+
+.. c:function:: Py_ssize_t PyUnicode_ToFolded(Py_UCS4 ch, Py_UCS4 *buffer, int size)
+
+   Foldcase *ch*, store result in *buffer*, which should be
+   able to hold as many characters needed for *ch* to be foldcased
+   (e.g. a maximum of three character for Unicode 16.0), and
+   return the number of characters stored. Passing a ``NULL`` buffer returns
+   the buffer size needed. If at some point a buffer overflow is detected,
+   an :exc:`ValueError` is raised and ``-1`` is returned.
+
+   .. versionadded:: next
+
+
+
 These APIs can be used to work with surrogates:
 
 .. c:function:: int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)

Include/cpython/unicodeobject.h

@@ -733,6 +733,31 @@ PyAPI_FUNC(int) _PyUnicode_IsAlpha(
     Py_UCS4 ch       /* Unicode character */
     );
 
+PyAPI_FUNC(int) PyUnicode_ToLower(
+    Py_UCS4 ch,     /* Unicode character */
+    Py_UCS4 *res,   /* Output buffer */
+    int size        /* Buffer size */
+    );
+
+PyAPI_FUNC(int) PyUnicode_ToUpper(
+    Py_UCS4 ch,     /* Unicode character */
+    Py_UCS4 *res,   /* Output buffer */
+    int size        /* Buffer size */
+    );
+
+PyAPI_FUNC(int) PyUnicode_ToTitle(
+    Py_UCS4 ch,     /* Unicode character */
+    Py_UCS4 *res,   /* Output buffer */
+    int size        /* Buffer size */
+    );
+
+PyAPI_FUNC(int) PyUnicode_ToFolded(
+    Py_UCS4 ch,     /* Unicode character */
+    Py_UCS4 *res,   /* Output buffer */
+    int size        /* Buffer size */
+    );
+
+
 // Helper array used by Py_UNICODE_ISSPACE().
 PyAPI_DATA(const unsigned char) _Py_ascii_whitespace[];
 

Include/internal/pycore_unicodeobject.h

@@ -15,10 +15,6 @@ extern "C" {
 
 extern int _PyUnicode_IsXidStart(Py_UCS4 ch);
 extern int _PyUnicode_IsXidContinue(Py_UCS4 ch);
-extern int _PyUnicode_ToLowerFull(Py_UCS4 ch, Py_UCS4 *res);
-extern int _PyUnicode_ToTitleFull(Py_UCS4 ch, Py_UCS4 *res);
-extern int _PyUnicode_ToUpperFull(Py_UCS4 ch, Py_UCS4 *res);
-extern int _PyUnicode_ToFoldedFull(Py_UCS4 ch, Py_UCS4 *res);
 extern int _PyUnicode_IsCaseIgnorable(Py_UCS4 ch);
 extern int _PyUnicode_IsCased(Py_UCS4 ch);
 

Lib/test/test_capi/test_unicode.py

@@ -1753,6 +1753,61 @@ def test_GET_CACHED_HASH(self):
         # impl detail: ASCII string hashes are equal to bytes ones
         self.assertEqual(unicode_GET_CACHED_HASH(obj), hash(content_bytes))
 
+    @support.cpython_only
+    @unittest.skipIf(_testcapi is None, 'need _testcapi module')
+    def test_tolower(self):
+        import string
+        from _testcapi import unicode_tolower
+
+        for i, c in enumerate(string.ascii_uppercase):
+            with self.subTest(c):
+                self.assertEqual(unicode_tolower(c), string.ascii_lowercase[i])
+
+        # Test unicode character
+        self.assertEqual(unicode_tolower("Č"), "č")
+        self.assertEqual(unicode_tolower("Σ"), "σ")
+
+    @support.cpython_only
+    @unittest.skipIf(_testcapi is None, 'need _testcapi module')
+    def test_toupper(self):
+        import string
+        from _testcapi import unicode_toupper
+
+        for i, c in enumerate(string.ascii_lowercase):
+            with self.subTest(c):
+                self.assertEqual(unicode_toupper(c), string.ascii_uppercase[i])
+
+        # Test unicode character
+        self.assertEqual(unicode_toupper("č"), "Č")
+        self.assertEqual(unicode_toupper("ß"), "SS")
+        self.assertEqual(unicode_toupper("ΐ"), "Ϊ́")
+
+    @support.cpython_only
+    @unittest.skipIf(_testcapi is None, 'need _testcapi module')
+    def test_totitle(self):
+        from _testcapi import unicode_totitle
+
+        self.assertEqual(unicode_totitle("t"), "T")
+
+        # Test unicode character
+        self.assertEqual(unicode_totitle("ł"), "Ł")
+        self.assertEqual(unicode_totitle("ß"), "Ss")
+        self.assertEqual(unicode_totitle("ΐ"), "Ϊ́")
+
+    @support.cpython_only
+    @unittest.skipIf(_testcapi is None, 'need _testcapi module')
+    def test_tofolded(self):
+        from _testcapi import unicode_tofolded
+
+        self.assertEqual(unicode_tofolded("T"), "t")
+
+        # Test unicode character
+        self.assertEqual(unicode_tofolded("Ł"), "ł")
+        self.assertEqual(unicode_tofolded("Σ"), "σ")
+
+        # Test case-ignorable character
+        self.assertEqual(unicode_tofolded("👍"), "👍")
+
 
 class PyUnicodeWriterTest(unittest.TestCase):
     def create_writer(self, size):

Misc/NEWS.d/next/C_API/2025-07-01-14-56-41.gh-issue-76535.9cwObj.rst

@@ -0,0 +1 @@
+Make :c:func:`PyUnicode_ToLower`, :c:func:`PyUnicode_ToUpper`, :c:func:`PyUnicode_ToTitle` and :c:func:`PyUnicode_ToFolded` public.

Modules/_testcapi/unicode.c

@@ -220,6 +220,64 @@ unicode_copycharacters(PyObject *self, PyObject *args)
     return Py_BuildValue("(Nn)", to_copy, copied);
 }
 
+static PyObject *
+unicode_case_operation(PyObject *str, int (*function)(Py_UCS4, Py_UCS4 *, int), const char *name)
+{
+    if (PyUnicode_GET_LENGTH(str) != 1) {
+        PyErr_Format(PyExc_ValueError, "%s only accepts 1-character strings", name);
+        return NULL;
+    }
+
+    Py_UCS4 c = PyUnicode_READ_CHAR(str, 0);
+
+    Py_UCS4 buf[3];
+    int chars = function(c, buf, Py_ARRAY_LENGTH(buf));
+    if (chars <= 0) {
+        PyErr_BadInternalCall();
+        return NULL;
+    }
+
+    PyUnicodeWriter *writer = PyUnicodeWriter_Create(1);
+    if (writer == NULL) {
+        return NULL;
+    }
+    if (PyUnicodeWriter_WriteUCS4(writer, buf, chars) < 0) {
+        PyUnicodeWriter_Discard(writer);
+        return NULL;
+    }
+    return PyUnicodeWriter_Finish(writer);
+}
+
+/* Test PyUnicode_ToLower() */
+static PyObject *
+unicode_tolower(PyObject *self, PyObject *arg)
+{
+    return unicode_case_operation(arg, PyUnicode_ToLower, "unicode_tolower");
+}
+
+/* Test PyUnicode_ToUpper() */
+static PyObject *
+unicode_toupper(PyObject *self, PyObject *arg)
+{
+    return unicode_case_operation(arg, PyUnicode_ToUpper, "unicode_toupper");
+}
+
+
+/* Test PyUnicode_ToLower() */
+static PyObject *
+unicode_totitle(PyObject *self, PyObject *arg)
+{
+    return unicode_case_operation(arg, PyUnicode_ToTitle, "unicode_totitle");
+}
+
+/* Test PyUnicode_ToLower() */
+static PyObject *
+unicode_tofolded(PyObject *self, PyObject *arg)
+{
+    return unicode_case_operation(arg, PyUnicode_ToFolded, "unicode_tofolded");
+}
+
+
 static PyObject*
 unicode_GET_CACHED_HASH(PyObject *self, PyObject *arg)
 {
@@ -577,6 +635,10 @@ static PyMethodDef TestMethods[] = {
     {"unicode_asutf8",           unicode_asutf8,                 METH_VARARGS},
     {"unicode_copycharacters",   unicode_copycharacters,         METH_VARARGS},
     {"unicode_GET_CACHED_HASH",  unicode_GET_CACHED_HASH,        METH_O},
+    {"unicode_tolower",          unicode_tolower,                METH_O},
+    {"unicode_toupper",          unicode_toupper,                METH_O},
+    {"unicode_totitle",          unicode_totitle,                METH_O},
+    {"unicode_tofolded",         unicode_tofolded,               METH_O},
     {NULL},
 };
 

Objects/unicodectype.c

@@ -198,67 +198,114 @@ Py_UCS4 _PyUnicode_ToLowercase(Py_UCS4 ch)
     return ch + ctype->lower;
 }
 
-int _PyUnicode_ToLowerFull(Py_UCS4 ch, Py_UCS4 *res)
+int PyUnicode_ToLower(Py_UCS4 ch, Py_UCS4 *res, int size)
 {
     const _PyUnicode_TypeRecord *ctype = gettyperecord(ch);
 
     if (ctype->flags & EXTENDED_CASE_MASK) {
         int index = ctype->lower & 0xFFFF;
         int n = ctype->lower >> 24;
         int i;
-        for (i = 0; i < n; i++)
-            res[i] = _PyUnicode_ExtendedCase[index + i];
+        for (i = 0; i < n; i++) {
+            if (res != NULL) {
+                if (i >= size) {
+                    PyErr_SetString(PyExc_ValueError, "output buffer is too small");
+                    return -1;
+                }
+                res[i] = _PyUnicode_ExtendedCase[index + i];
+            }
+        }
         return n;
     }
-    res[0] = ch + ctype->lower;
+
+    if (res != NULL) {
+        if (0 >= size) {
+            PyErr_SetString(PyExc_ValueError, "output buffer is too small");
+            return -1;
+        }
+        res[0] = ch + ctype->lower;
+    }
     return 1;
 }
 
-int _PyUnicode_ToTitleFull(Py_UCS4 ch, Py_UCS4 *res)
+int PyUnicode_ToTitle(Py_UCS4 ch, Py_UCS4 *res, int size)
 {
     const _PyUnicode_TypeRecord *ctype = gettyperecord(ch);
 
     if (ctype->flags & EXTENDED_CASE_MASK) {
         int index = ctype->title & 0xFFFF;
         int n = ctype->title >> 24;
         int i;
-        for (i = 0; i < n; i++)
-            res[i] = _PyUnicode_ExtendedCase[index + i];
+        for (i = 0; i < n; i++) {
+            if (res != NULL) {
+                if (i >= size) {
+                    PyErr_SetString(PyExc_ValueError, "output buffer is too small");
+                    return -1;
+                }
+                res[i] = _PyUnicode_ExtendedCase[index + i];
+            }
+        }
         return n;
     }
-    res[0] = ch + ctype->title;
+    if (res != NULL) {
+        if (0 >= size) {
+            PyErr_SetString(PyExc_ValueError, "output buffer is too small");
+            return -1;
+        }
+        res[0] = ch + ctype->title;
+    }
     return 1;
 }
 
-int _PyUnicode_ToUpperFull(Py_UCS4 ch, Py_UCS4 *res)
+int PyUnicode_ToUpper(Py_UCS4 ch, Py_UCS4 *res, int size)
 {
     const _PyUnicode_TypeRecord *ctype = gettyperecord(ch);
 
     if (ctype->flags & EXTENDED_CASE_MASK) {
         int index = ctype->upper & 0xFFFF;
         int n = ctype->upper >> 24;
         int i;
-        for (i = 0; i < n; i++)
-            res[i] = _PyUnicode_ExtendedCase[index + i];
+        for (i = 0; i < n; i++) {
+            if (res != NULL) {
+                if (i >= size) {
+                    PyErr_SetString(PyExc_ValueError, "output buffer is too small");
+                    return -1;
+                }
+                res[i] = _PyUnicode_ExtendedCase[index + i];
+            }
+        }
         return n;
     }
-    res[0] = ch + ctype->upper;
+    if (res != NULL) {
+        if (0 >= size) {
+            PyErr_SetString(PyExc_ValueError, "output buffer is too small");
+            return -1;
+        }
+        res[0] = ch + ctype->upper;
+    }
     return 1;
 }
 
-int _PyUnicode_ToFoldedFull(Py_UCS4 ch, Py_UCS4 *res)
+int PyUnicode_ToFolded(Py_UCS4 ch, Py_UCS4 *res, int size)
 {
     const _PyUnicode_TypeRecord *ctype = gettyperecord(ch);
 
     if (ctype->flags & EXTENDED_CASE_MASK && (ctype->lower >> 20) & 7) {
         int index = (ctype->lower & 0xFFFF) + (ctype->lower >> 24);
         int n = (ctype->lower >> 20) & 7;
         int i;
-        for (i = 0; i < n; i++)
-            res[i] = _PyUnicode_ExtendedCase[index + i];
+        for (i = 0; i < n; i++) {
+            if (res != NULL) {
+                if (i >= size) {
+                    PyErr_SetString(PyExc_ValueError, "output buffer is too small");
+                    return -1;
+                }
+                res[i] = _PyUnicode_ExtendedCase[index + i];
+            }
+        }
         return n;
     }
-    return _PyUnicode_ToLowerFull(ch, res);
+    return PyUnicode_ToLower(ch, res, size);
 }
 
 int _PyUnicode_IsCased(Py_UCS4 ch)