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: add PyUnstable_InterpreterState_SetEvalFrameFunc() #141518
- _PyInterpreterState_RequireIDRef()
- _PyInterpreterState_RequiresIDRef()
- _PyLong_AsByteArray(): use PyLong_AsNativeBytes()
- _PyLong_Copy()
- _PyLong_FromByteArray(): use PyLong_FromNativeBytes()
- _PyLong_GCD(): call Python math.gcd() function
- _PyLong_NumBits(): call Python int.bit_length() method
- _PyObject_CallMethodId(): use PyObject_CallMethod()
- _PyObject_Dump(): see [C API] Promote _PyObject_Dump() to a public function #141070
- _PyObject_FunctionStr()
- _PyObject_GetAttrId(): use PyObject_GetAttr()
- _PyObject_GetDictPtr(): see [C API] Add PyObject_GetDict() function #139852
- _PySlice_FromIndices(): use PySlice_New()
- _PySlice_GetLongIndices()
- _PyStack_AsDict()
- _PyThread_CurrentFrames(): call Python sys._current_frames() function
- _PyType_Lookup(), _PyType_LookupRef(): see [C API] Add PyType_Lookup() function #139847
- _PyType_Name(): use PyType_GetName()
- _PyUnicode_FromId(): use PyUnicode_FromString() and cache the result; see the old discussion (2023)
- _PyWeakref_ClearRef()
- _Py_BreakPoint()
- _Py_GetGlobalRefTotal(), _Py_GetLegacyRefTotal(), _PyInterpreterState_GetRefTotal(): call Python sys.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(): see gh-130396: Remove _Py_ReachedRecursionLimitWithMargin() function #141951
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 commented on Nov 5, 2025
Please add a public API for _PyObject_Dump. It's quite useful for debugging.
AraHaan commented on 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 commented on 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 commented on 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 commented on Nov 5, 2025
Ok, I created #141070 to add PyObject_Dump().
skirpichev commented on 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 commented on 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 commented on Nov 6, 2025
I already proposed adding a public PyLong_GCD() function in #111139 but the idea got rejected.
emmatyping commented on 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 commented on 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() and PyEval_EvalFrameDefault() (just remove the _ prefix).
emmatyping commented on 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 commented on Nov 13, 2025
I created #141518 for PEP 523 functions. We can start a discussion there.
vstinner commented on Dec 3, 2025
I created issue #142217 and PR #142221 to deprecate the 3 functions using the _Py_Identifier structure.
vstinner commented on 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.