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.

4 files changed, 24 insertions, 1 deletions

diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index f74dd1a..957a3e7 100644
--- a/Doc/whatsnew/3.10.rst
+++ b/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
 -------
 
diff --git a/Include/unicodeobject.h b/Include/unicodeobject.h
index 500ce24..90b3299 100644
--- a/Include/unicodeobject.h
+++ b/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)
diff --git a/Misc/NEWS.d/next/C API/2020-10-02-00-57-34.bpo-41692.fDScsF.rst b/Misc/NEWS.d/next/C API/2020-10-02-00-57-34.bpo-41692.fDScsF.rst
new file mode 100644
index 0000000..1be37c6
--- /dev/null
+++ b/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.
diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c
index f32ab41..cf72238 100644
--- a/Objects/unicodeobject.c
+++ b/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;