Repository navigation
Deprecate private C API functions #141049
Description
I propose to deprecate 42 private functions of the C API:
_PyArg_ParseTupleAndKeywordsFast(): see [C API] Removed private _PyArg_Parser API has no replacement in Python 3.13 #112136_PyCode_CheckLineNumber()_PyDict_GetItem_KnownHash()_PyDict_NewPresized(): see [C API] Add PyDict_NewPresized() function #139772_PyErr_ChainExceptions1(): see _PyErr_ChainExceptions1 no longer avallable to extension modules in Python 3.13 alpha headers #116809_PyEval_SliceIndex()_PyEval_SliceIndexNotNone()_PyFrame_IsEntryFrame()_PyInterpreterState_GetEvalFrameFunc(),_PyInterpreterState_SetEvalFrameFunc(),_PyEval_EvalFrameDefault(): PEP 523, see [C API] Promote PEP 523 functions to public functions: addPyUnstable_InterpreterState_SetEvalFrameFunc()#141518_PyInterpreterState_RequireIDRef()_PyInterpreterState_RequiresIDRef()_PyLong_AsByteArray(): usePyLong_AsNativeBytes()_PyLong_Copy()_PyLong_FromByteArray(): usePyLong_FromNativeBytes()_PyLong_GCD(): call Pythonmath.gcd()function_PyLong_NumBits(): call Pythonint.bit_length()method_PyObject_CallMethodId(): usePyObject_CallMethod()_PyObject_Dump(): see [C API] Promote _PyObject_Dump() to a public function #141070_PyObject_FunctionStr()_PyObject_GetAttrId(): usePyObject_GetAttr()_PyObject_GetDictPtr(): see [C API] Add PyObject_GetDict() function #139852_PySlice_FromIndices(): usePySlice_New()_PySlice_GetLongIndices()_PyStack_AsDict()_PyThread_CurrentFrames(): call Pythonsys._current_frames()function_PyType_Lookup(),_PyType_LookupRef(): see [C API] Add PyType_Lookup() function #139847_PyType_Name(): usePyType_GetName()_PyUnicode_FromId(): usePyUnicode_FromString()and cache the result; see the old discussion (2023)_PyWeakref_ClearRef()_Py_BreakPoint()_Py_GetGlobalRefTotal(),_Py_GetLegacyRefTotal(),_PyInterpreterState_GetRefTotal(): call Pythonsys.gettotalrefcount()function_Py_HashDouble(): see decision issue #2 and decision issue #10_Py_NewReference(),_Py_NewReferenceNoTotal(),_Py_ForgetReference(),_Py_ResurrectReference(): see old issue_Py_ReachedRecursionLimitWithMargin()
If one of these functions is used, users should request a public C API replacing the private function.
I propose to not schedule the removal of these functions for now.
Activity
ZeroIntensity commentedon Nov 5, 2025
Please add a public API for
_PyObject_Dump. It's quite useful for debugging.AraHaan commentedon Nov 5, 2025
I second a public api for
_PyObject_Dump, but I think renaming it and making it public would be much better instead due to also using it to debug my C extensions.vstinner commentedon Nov 5, 2025
Is it really useful to add a public C API for that? Even if the API is deprecated, you can still use it in gdb/lldb and in your code. Even if later the function will be removed from the public C API, it would only be moved to the internal C API, not really removed.
ZeroIntensity commentedon Nov 5, 2025
It's also helpful for debugging extensions outside of CPython. I'd find debugging extensions to be a little bit harder if it were removed from the public headers without a replacement.
vstinner commentedon Nov 5, 2025
Ok, I created #141070 to add
PyObject_Dump().skirpichev commentedon Nov 5, 2025
I would rather expose this as public. Why do we want to hide (under a slower interface) this from users? These functions are something common for all big ints libraries.
encukou commentedon Nov 6, 2025
Makes sense in general, but please don't add just “use XYZ()” in the What's New. With any deprecation we should help people update code that starts raising warnings.
Definitely don't recommend
PySlice_GetIndices()-- it's docs say “You probably do not want to use this function”; it's effectively been soft-deprecated since 2003.vstinner commentedon Nov 6, 2025
I already proposed adding a public
PyLong_GCD()function in #111139 but the idea got rejected.emmatyping commentedon Nov 7, 2025
I think deprecating the PEP 523 APIs would take a PEP with a better solution. There are a number of JITs that use these APIs despite being private and I think it would break too many things to remove them without a replacement. There was some discussion at PyCon US last year about a better frame evaluation API for JITs but I don't recall if anyone was planning on working on a PEP with a solution in mind.
vstinner commentedon Nov 8, 2025
For PEP 523 functions,
_PyInterpreterState_GetEvalFrameFunc(),_PyInterpreterState_SetEvalFrameFunc()and_PyEval_EvalFrameDefault(), I think that public functions should be added to replace them:PyInterpreterState_GetEvalFrameFunc(),PyInterpreterState_SetEvalFrameFunc()andPyEval_EvalFrameDefault()(just remove the_prefix).emmatyping commentedon Nov 8, 2025
That's certainly one solution, but I think there is more to be decided around what a public facing API for those should be. I'd say they should be considered separately and will almost certainly require more discussion.
vstinner commentedon Nov 13, 2025
I created #141518 for PEP 523 functions. We can start a discussion there.
vstinner commentedon Dec 3, 2025
I created issue #142217 and PR #142221 to deprecate the 3 functions using the
_Py_Identifierstructure.vstinner commentedon May 29, 2026
I spent significant time on trying to promote the last private functions to the first-class public API category. It seems like remaining private functions are really in a grey area, not really internal, not really public, but in between. It's hard to argue to promote them as public functions. I'm not sure that it's worth it to spend more time on the remaining functions. Or maybe if the effort is continued, it should be on a case by case basis, by promoting a function or a small set of functions.
I close the issue. Thanks for helping me to look at these functions.