bpo-41692: Deprecate PyUnicode_InternImmortal() (GH-22486)

The PyUnicode_InternImmortal() function is now deprecated and will be
removed in Python 3.12: use PyUnicode_InternInPlace() instead.

Author: vstinner

Doc/whatsnew/3.10.rst

@@ -299,6 +299,14 @@ Porting to Python 3.10
   Unicode object without initial data.
   (Contributed by Inada Naoki in :issue:`36346`.)
 
+Deprecated
+----------
+
+* The ``PyUnicode_InternImmortal()`` function is now deprecated
+  and will be removed in Python 3.12: use :c:func:`PyUnicode_InternInPlace`
+  instead.
+  (Contributed by Victor Stinner in :issue:`41692`.)
+
 Removed
 -------
 

Include/unicodeobject.h

@@ -261,11 +261,14 @@ PyAPI_FUNC(PyObject *) PyUnicode_FromFormat(
     );
 
 PyAPI_FUNC(void) PyUnicode_InternInPlace(PyObject **);
-PyAPI_FUNC(void) PyUnicode_InternImmortal(PyObject **);
 PyAPI_FUNC(PyObject *) PyUnicode_InternFromString(
     const char *u              /* UTF-8 encoded string */
     );
 
+// PyUnicode_InternImmortal() is deprecated since Python 3.10
+// and will be removed in Python 3.12. Use PyUnicode_InternInPlace() instead.
+Py_DEPRECATED(3.10) PyAPI_FUNC(void) PyUnicode_InternImmortal(PyObject **);
+
 /* Use only if you know it's a string */
 #define PyUnicode_CHECK_INTERNED(op) \
     (((PyASCIIObject *)(op))->state.interned)

Misc/NEWS.d/next/C API/2020-10-02-00-57-34.bpo-41692.fDScsF.rst

@@ -0,0 +1,3 @@
+The ``PyUnicode_InternImmortal()`` function is now deprecated and will be
+removed in Python 3.12: use :c:func:`PyUnicode_InternInPlace` instead.
+Patch by Victor Stinner.

Objects/unicodeobject.c

@@ -15764,6 +15764,15 @@ PyUnicode_InternInPlace(PyObject **p)
 void
 PyUnicode_InternImmortal(PyObject **p)
 {
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+            "PyUnicode_InternImmortal() is deprecated; "
+            "use PyUnicode_InternInPlace() instead", 1) < 0)
+    {
+        // The function has no return value, the exception cannot
+        // be reported to the caller, so just log it.
+        PyErr_WriteUnraisable(NULL);
+    }
+
     PyUnicode_InternInPlace(p);
     if (PyUnicode_CHECK_INTERNED(*p) != SSTATE_INTERNED_IMMORTAL) {
         _PyUnicode_STATE(*p).interned = SSTATE_INTERNED_IMMORTAL;