pythongh-128863: Deprecate private C API functions

* _PyBytes_Join() * _PyThreadState_UncheckedGet() * _PyUnicode_AsString() * _Py_HashPointer() * _Py_fopen_obj() Replace _Py_HashPointer() with Py_HashPointer(). Remove references to deprecated functions.
vstinner · Jan 15, 2025 · 814670d · 814670d
1 parent ae7f621
commit 814670d
Show file tree

Hide file tree

Showing 14 changed files with 71 additions and 26 deletions.
diff --git a/Doc/deprecations/c-api-pending-removal-in-3.16.rst b/Doc/deprecations/c-api-pending-removal-in-3.16.rst
@@ -0,0 +1,10 @@
+Pending removal in Python 3.16
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Deprecated private functions (:gh:`128863`):
+
+  * :c:func:`!_PyBytes_Join`: use :c:func:`PyBytes_Join`.
+  * :c:func:`!_PyThreadState_UncheckedGet`: use :c:func:`PyThreadState_GetUnchecked`.
+  * :c:func:`!_PyUnicode_AsString`: use :c:func:`PyUnicode_AsUTF8`.
+  * :c:func:`!_Py_HashPointer`: use :c:func:`Py_HashPointer`.
+  * :c:func:`!_Py_fopen_obj`: use :c:func:`Py_fopen`.
diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
@@ -1356,12 +1356,26 @@ Deprecated
 
 .. include:: ../deprecations/c-api-pending-removal-in-3.15.rst
 
+.. include:: ../deprecations/c-api-pending-removal-in-3.16.rst
+
 .. include:: ../deprecations/c-api-pending-removal-in-future.rst
 
 * The ``PyMonitoring_FireBranchEvent`` function is deprecated and should
   be replaced with calls to :c:func:`PyMonitoring_FireBranchLeftEvent`
   and :c:func:`PyMonitoring_FireBranchRightEvent`.
 
+* The following private functions are deprecated and planned for removal in
+  Python 3.16:
+
+  * :c:func:`!_PyBytes_Join`: use :c:func:`PyBytes_Join`.
+  * :c:func:`!_PyThreadState_UncheckedGet`: use :c:func:`PyThreadState_GetUnchecked`.
+  * :c:func:`!_PyUnicode_AsString`: use :c:func:`PyUnicode_AsUTF8`.
+  * :c:func:`!_Py_HashPointer`: use :c:func:`Py_HashPointer`.
+  * :c:func:`!_Py_fopen_obj`: use :c:func:`Py_fopen`.
+
+  (Contributed by Victor Stinner in :gh:`128863`.)
+
+
 Removed
 -------
 

diff --git a/Include/cpython/bytesobject.h b/Include/cpython/bytesobject.h
@@ -34,5 +34,9 @@ static inline Py_ssize_t PyBytes_GET_SIZE(PyObject *op) {
 
 PyAPI_FUNC(PyObject*) PyBytes_Join(PyObject *sep, PyObject *iterable);
 
-// Alias kept for backward compatibility
-#define _PyBytes_Join PyBytes_Join
+// Deprecated alias kept for backward compatibility
+Py_DEPRECATED(3.14) static inline PyObject*
+_PyBytes_Join(PyObject *sep, PyObject *iterable)
+{
+    return PyBytes_Join(sep, iterable);
+}
diff --git a/Include/cpython/fileutils.h b/Include/cpython/fileutils.h
@@ -6,9 +6,11 @@ PyAPI_FUNC(FILE*) Py_fopen(
     PyObject *path,
     const char *mode);
 
-// Deprecated alias to Py_fopen() kept for backward compatibility
-Py_DEPRECATED(3.14) PyAPI_FUNC(FILE*) _Py_fopen_obj(
-    PyObject *path,
-    const char *mode);
+// Deprecated alias kept for backward compatibility
+Py_DEPRECATED(3.14) static inline FILE*
+_Py_fopen_obj(PyObject *path, const char *mode)
+{
+    return Py_fopen(path, mode);
+}
 
 PyAPI_FUNC(int) Py_fclose(FILE *file);
diff --git a/Include/cpython/pyhash.h b/Include/cpython/pyhash.h
@@ -29,9 +29,6 @@
 /* Helpers for hash functions */
 PyAPI_FUNC(Py_hash_t) _Py_HashDouble(PyObject *, double);
 
-// Kept for backward compatibility
-#define _Py_HashPointer Py_HashPointer
-
 
 /* hash function definition */
 typedef struct {
@@ -44,6 +41,14 @@ typedef struct {
 PyAPI_FUNC(PyHash_FuncDef*) PyHash_GetFuncDef(void);
 
 PyAPI_FUNC(Py_hash_t) Py_HashPointer(const void *ptr);
+
+// Deprecated alias kept for backward compatibility
+Py_DEPRECATED(3.14) static inline Py_hash_t
+_Py_HashPointer(const void *ptr)
+{
+    return Py_HashPointer(ptr);
+}
+
 PyAPI_FUNC(Py_hash_t) PyObject_GenericHash(PyObject *);
 
 PyAPI_FUNC(Py_hash_t) Py_HashBuffer(const void *ptr, Py_ssize_t len);
diff --git a/Include/cpython/pystate.h b/Include/cpython/pystate.h
@@ -239,8 +239,12 @@ struct _ts {
  * if it is NULL. */
 PyAPI_FUNC(PyThreadState *) PyThreadState_GetUnchecked(void);
 
-// Alias kept for backward compatibility
-#define _PyThreadState_UncheckedGet PyThreadState_GetUnchecked
+// Deprecated alias kept for backward compatibility
+Py_DEPRECATED(3.14) static inline PyThreadState*
+_PyThreadState_UncheckedGet(void)
+{
+    return PyThreadState_GetUnchecked();
+}
 
 
 // Disable tracing and profiling.

diff --git a/Include/cpython/unicodeobject.h b/Include/cpython/unicodeobject.h
@@ -630,8 +630,12 @@ _PyUnicodeWriter_Dealloc(_PyUnicodeWriter *writer);
 
 PyAPI_FUNC(const char *) PyUnicode_AsUTF8(PyObject *unicode);
 
-// Alias kept for backward compatibility
-#define _PyUnicode_AsString PyUnicode_AsUTF8
+// Deprecated alias kept for backward compatibility
+Py_DEPRECATED(3.14) static inline const char*
+_PyUnicode_AsString(PyObject *unicode)
+{
+    return PyUnicode_AsUTF8(unicode);
+}
 
 
 /* === Characters Type APIs =============================================== */

diff --git a/Lib/test/audit-tests.py b/Lib/test/audit-tests.py
@@ -187,7 +187,7 @@ class C(A):
 
 
 def test_open(testfn):
-    # SSLContext.load_dh_params uses _Py_fopen_obj rather than normal open()
+    # SSLContext.load_dh_params uses Py_fopen() rather than normal open()
     try:
         import ssl
 

diff --git a/Misc/NEWS.d/next/C_API/2025-01-15-11-42-07.gh-issue-128863.C9MkB_.rst b/Misc/NEWS.d/next/C_API/2025-01-15-11-42-07.gh-issue-128863.C9MkB_.rst
@@ -0,0 +1,10 @@
+The following private functions are deprecated and planned for removal in
+Python 3.16:
+
+* :c:func:`!_PyBytes_Join`: use :c:func:`PyBytes_Join`.
+* :c:func:`!_PyThreadState_UncheckedGet`: use :c:func:`PyThreadState_GetUnchecked`.
+* :c:func:`!_PyUnicode_AsString`: use :c:func:`PyUnicode_AsUTF8`.
+* :c:func:`!_Py_HashPointer`: use :c:func:`Py_HashPointer`.
+* :c:func:`!_Py_fopen_obj`: use :c:func:`Py_fopen`.
+
+Patch by Victor Stinner.
diff --git a/Objects/descrobject.c b/Objects/descrobject.c
@@ -1349,7 +1349,7 @@ wrapper_hash(PyObject *self)
     wrapperobject *wp = (wrapperobject *)self;
     Py_hash_t x, y;
     x = PyObject_GenericHash(wp->self);
-    y = _Py_HashPointer(wp->descr);
+    y = Py_HashPointer(wp->descr);
     x = x ^ y;
     if (x == -1)
         x = -2;

diff --git a/Objects/methodobject.c b/Objects/methodobject.c
@@ -331,7 +331,7 @@ meth_hash(PyObject *self)
 {
     PyCFunctionObject *a = _PyCFunctionObject_CAST(self);
     Py_hash_t x = PyObject_GenericHash(a->m_self);
-    Py_hash_t y = _Py_HashPointer((void*)(a->m_ml->ml_meth));
+    Py_hash_t y = Py_HashPointer((void*)(a->m_ml->ml_meth));
     x ^= y;
     if (x == -1) {
         x = -2;

diff --git a/Objects/odictobject.c b/Objects/odictobject.c
@@ -260,7 +260,7 @@ mp_length         __len__          -                   dict_length
 mp_subscript      __getitem__      -                   dict_subscript
 mp_ass_subscript  __setitem__      -                   dict_ass_sub
                   __delitem__
-tp_hash           __hash__         _Py_HashPointer     ..._HashNotImpl
+tp_hash           __hash__         Py_HashPointer      ..._HashNotImpl
 tp_str            __str__          object_str          -
 tp_getattro       __getattribute__ ..._GenericGetAttr  (repeated)
                   __getattr__

diff --git a/Python/context.c b/Python/context.c
@@ -860,7 +860,7 @@ contextvar_generate_hash(void *addr, PyObject *name)
         return -1;
     }
 
-    Py_hash_t res = _Py_HashPointer(addr) ^ name_hash;
+    Py_hash_t res = Py_HashPointer(addr) ^ name_hash;
     return res == -1 ? -2 : res;
 }
 

diff --git a/Python/fileutils.c b/Python/fileutils.c
@@ -1841,14 +1841,6 @@ Py_fopen(PyObject *path, const char *mode)
 }
 
 
-// Deprecated alias to Py_fopen() kept for backward compatibility
-FILE*
-_Py_fopen_obj(PyObject *path, const char *mode)
-{
-    return Py_fopen(path, mode);
-}
-
-
 // Call fclose().
 //
 // On Windows, files opened by Py_fopen() in the Python DLL must be closed by