Deprecate private C API functions

[vstinner]

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.

[ZeroIntensity]

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

[AraHaan]

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]

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.

[ZeroIntensity]

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]

Ok, I created #141070 to add PyObject_Dump().

[skirpichev]

_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.

[encukou]

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]

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.

[emmatyping]

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]

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).