Description

vstinner

opened on Nov 5, 2025

Issue body actions

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

1. vstinner

   added

   topic-C-API

   on Nov 5, 2025
2. StanFromIreland

   added

   type-featureA feature request or enhancementA feature request or enhancement

   interpreter-core(Objects, Python, Grammar, and Parser dirs)(Objects, Python, Grammar, and Parser dirs)

   on Nov 5, 2025
3. ZeroIntensity commented on Nov 5, 2025

   

   ZeroIntensity

   on Nov 5, 2025

   Member

   More actions

   Please add a public API for _PyObject_Dump. It's quite useful for debugging.
4. AraHaan commented on Nov 5, 2025

   

   AraHaan

   on Nov 5, 2025

   Contributor

   More actions

   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.
5. vstinner commented on Nov 5, 2025

   

   vstinner

   on Nov 5, 2025

   MemberAuthor

   More actions

   Please add a public API for _PyObject_Dump. It's quite useful for debugging.

   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.
6. ZeroIntensity commented on Nov 5, 2025

   

   ZeroIntensity

   on Nov 5, 2025

   Member

   More actions

   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.
7. vstinner commented on Nov 5, 2025

   

   vstinner

   on Nov 5, 2025

   MemberAuthor

   More actions

   Ok, I created #141070 to add PyObject_Dump().
8. skirpichev commented on Nov 5, 2025

   

   skirpichev

   on Nov 5, 2025

   Member

   More actions

   _PyLong_GCD(): call Python math.gcd() function
   _PyLong_NumBits(): call Python int.bit_length() method

   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.
9. encukou commented on Nov 6, 2025

   

   encukou

   on Nov 6, 2025

   Member

   More actions

   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.
10. vstinner commented on Nov 6, 2025

    

    vstinner

    on Nov 6, 2025

    MemberAuthor

    More actions

    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.

    I already proposed adding a public PyLong_GCD() function in #111139 but the idea got rejected.
11. emmatyping commented on Nov 7, 2025

    

    emmatyping

    on Nov 7, 2025

    Member

    More actions

    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.
12. vstinner commented on Nov 8, 2025

    

    vstinner

    on Nov 8, 2025

    MemberAuthor

    More actions

    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).
13. emmatyping commented on Nov 8, 2025

    

    emmatyping

    on Nov 8, 2025

    Member

    More actions

    I think that public functions should be added to replace them

    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.
14. vstinner commented on Nov 13, 2025

    

    vstinner

    on Nov 13, 2025

    MemberAuthor

    More actions

    I created #141518 for PEP 523 functions. We can start a discussion there.

    Reacted by Emma Smith
15. vstinner commented on Dec 3, 2025

    

    vstinner

    on Dec 3, 2025

    MemberAuthor

    More actions

    _PyUnicode_FromId(): use PyUnicode_FromString() and cache the result; see the old discussion (2023)

    I created issue #142217 and PR #142221 to deprecate the 3 functions using the _Py_Identifier structure.
16. vstinner commented on May 29, 2026

    

    vstinner

    on May 29, 2026

    MemberAuthor

    More actions

    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.
17. vstinner

    closed this as not plannedon May 29, 2026

Issue actions