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 0eb5922f6da75f..fd5c529345b068 100644 --- a/Doc/c-api/gen.rst +++ b/Doc/c-api/gen.rst @@ -44,3 +44,14 @@ than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`. with ``__name__`` and ``__qualname__`` set to *name* and *qualname*. A reference to *frame* is stolen by this function. The *frame* argument must not be ``NULL``. + + +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 cba823aa027bd6..f17558f20cd1a3 100644 --- a/Doc/c-api/set.rst +++ b/Doc/c-api/set.rst @@ -166,3 +166,15 @@ 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 + + This is a :term:`soft deprecated` constant representing the size of a + preallocated table inside :c:type:`PySetObject` instances. + + This is documented solely for completeness and not useful to users in any + way. If looking for the size of a set, use :c:func:`PySet_Size` instead.