https://github.com/python/cpython/commit/0e0d51cdcef903d8a990c8e264f32f2f28af0673 commit: 0e0d51cdcef903d8a990c8e264f32f2f28af0673 branch: main author: Peter Bierma <[email protected]> committer: ZeroIntensity <[email protected]> date: 2026-01-14T08:20:33-05:00 summary:
gh-141004: Document several soft-deprecated C APIs (GH-141634) Co-authored-by: Petr Viktorin <[email protected]> Co-authored-by: Victor Stinner <[email protected]> files: M Doc/c-api/file.rst M Doc/c-api/gen.rst M Doc/c-api/long.rst M Doc/c-api/set.rst M Tools/check-c-api-docs/ignored_c_api.txt diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst index 9d01254ddb2a11..0580e4c8f79db0 100644 --- a/Doc/c-api/file.rst +++ b/Doc/c-api/file.rst @@ -131,3 +131,22 @@ the :mod:`io` APIs instead. Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on failure; the appropriate exception will be set. + + +Deprecated API +^^^^^^^^^^^^^^ + + +These are :term:`soft deprecated` APIs that were included in Python's C API +by mistake. They are documented solely for completeness; use other +``PyFile*`` APIs instead. + +.. c:function:: PyObject *PyFile_NewStdPrinter(int fd) + + Use :c:func:`PyFile_FromFd` with defaults (``fd, NULL, "w", -1, NULL, NULL, NULL, 0``) instead. + +.. c:var:: PyTypeObject PyStdPrinter_Type + + Type of file-like objects used internally at Python startup when :py:mod:`io` is + not yet available. + Use Python :py:func:`open` or :c:func:`PyFile_FromFd` to create file objects instead. diff --git a/Doc/c-api/gen.rst b/Doc/c-api/gen.rst index 44f3bdbf959b9c..74db49a6814800 100644 --- a/Doc/c-api/gen.rst +++ b/Doc/c-api/gen.rst @@ -45,6 +45,7 @@ than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`. A reference to *frame* is stolen by this function. The *frame* argument must not be ``NULL``. + .. c:function:: PyCodeObject* PyGen_GetCode(PyGenObject *gen) Return a new :term:`strong reference` to the code object wrapped by *gen*. @@ -82,3 +83,14 @@ Asynchronous Generator Objects This function always succeeds. .. versionadded:: 3.6 + + +Deprecated API +^^^^^^^^^^^^^^ + +.. c:macro:: PyAsyncGenASend_CheckExact(op) + + This is a :term:`soft deprecated` API that was included in Python's C API + by mistake. + + It is solely here for completeness; do not use this API. diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index ed34efe716d8b9..6834c872c8cfcd 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -855,3 +855,31 @@ The :c:type:`PyLongWriter` API can be used to import an integer. If *writer* is ``NULL``, no operation is performed. The writer instance and the *digits* array are invalid after the call. + + +Deprecated API +^^^^^^^^^^^^^^ + +These macros are :term:`soft deprecated`. They describe parameters +of the internal representation of :c:type:`PyLongObject` instances. + +Use :c:func:`PyLong_GetNativeLayout` instead, along with :c:func:`PyLong_Export` +to read integer data or :c:type:`PyLongWriter` to write it. +These currently use the same layout, but are designed to continue working correctly +even if CPython's internal integer representation changes. + + +.. c:macro:: PyLong_SHIFT + + This is equivalent to :c:member:`~PyLongLayout.bits_per_digit` in + the output of :c:func:`PyLong_GetNativeLayout`. + + +.. c:macro:: PyLong_BASE + + This is currently equivalent to :c:expr:`1 << PyLong_SHIFT`. + + +.. c:macro:: PyLong_MASK + + This is currently equivalent to :c:expr:`(1 << PyLong_SHIFT) - 1` diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst index 09c0fb6b9c5f23..b74859dd669c54 100644 --- a/Doc/c-api/set.rst +++ b/Doc/c-api/set.rst @@ -166,3 +166,20 @@ subtypes but not for instances of :class:`frozenset` or its subtypes. Empty an existing set of all elements. Return ``0`` on success. Return ``-1`` and raise :exc:`SystemError` if *set* is not an instance of :class:`set` or its subtype. + + +Deprecated API +^^^^^^^^^^^^^^ + +.. c:macro:: PySet_MINSIZE + + A :term:`soft deprecated` constant representing the size of an internal + preallocated table inside :c:type:`PySetObject` instances. + + This is documented solely for completeness, as there are no guarantees + that a given version of CPython uses preallocated tables with a fixed + size. + In code that does not deal with unstable set internals, + :c:macro:`!PySet_MINSIZE` can be replaced with a small constant like ``8``. + + If looking for the size of a set, use :c:func:`PySet_Size` instead. diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt index 096a14a3cc4869..de78f6425803cb 100644 --- a/Tools/check-c-api-docs/ignored_c_api.txt +++ b/Tools/check-c-api-docs/ignored_c_api.txt @@ -71,21 +71,11 @@ PyDescr_NAME PyDescr_TYPE PyWrapperFlag_KEYWORDS # cpython/fileobject.h -PyFile_NewStdPrinter -PyStdPrinter_Type Py_UniversalNewlineFgets -# cpython/setobject.h -PySet_MINSIZE # cpython/ceval.h PyUnstable_CopyPerfMapFile PyUnstable_PerfTrampoline_CompileCode PyUnstable_PerfTrampoline_SetPersistAfterFork -# cpython/genobject.h -PyAsyncGenASend_CheckExact -# cpython/longintrepr.h -PyLong_BASE -PyLong_MASK -PyLong_SHIFT # cpython/pyerrors.h PyException_HEAD # cpython/pyframe.h _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
