gh-141004: Document several soft-deprecated C APIs (GH-141634)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>

diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst
index 9d01254ddb2a11f06e93b3a799b977309510bdc1..0580e4c8f79db082aae57b785d8609b885683227 100644 (file)
--- 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 44f3bdbf959b9cdccdf64a102bf594c90ae46506..74db49a6814800b6b58d5de7aeda699c97b4e712 100644 (file)
--- 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 ed34efe716d8b954aa1a64cc24b6d70e2fcb594a..6834c872c8cfcdb0dc1ad4dbe2e8f43f50894a7c 100644 (file)
--- 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 09c0fb6b9c5f233cef91971d3a8ebfda3d1dde4c..b74859dd669c54acf966c50cac021e8952cc92fc 100644 (file)
--- 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 096a14a3cc486961165596addf19638a17a56753..de78f6425803cb8f544157d2d65f07b7f62cb9f2 100644 (file)
--- 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