From 596d4ec3878481cd355862bc1cc276b11619939e Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sun, 16 Nov 2025 13:48:31 -0500 Subject: [PATCH 01/12] Document soft-deprecated symbols --- Doc/c-api/stable.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst index f5e6b7ad157e99..49ba6f42fecedc 100644 --- a/Doc/c-api/stable.rst +++ b/Doc/c-api/stable.rst @@ -364,3 +364,32 @@ Contents of Limited API Currently, the :ref:`Limited API ` includes the following items: .. limited-api-list:: + + +Soft-deprecated Symbols +======================= + +There are a few symbols included in Python's C API are :term:`soft deprecated`. +Soft deprecated symbols should not be used in new code, but have no planned +removal for compatibility's sake. + +The following is a list of soft deprecated symbols that were included in +Python's public C API by mistake. They intentionally come with no additional +documentation. In practice, very few extensions use these APIs. + +.. c:function:: PyObject *PyFile_NewStdPrinter(void) + +.. c:var:: PyTypeObject PyStdPrinter_Type + +.. c:macro:: PyLong_BASE + +.. c:macro:: PyLong_MASK + +.. c:macro:: PyLong_SHIFT + +.. c:macro:: PySet_MINSIZE + +.. c:macro:: PyAsyncGenASend_CheckExact(op) + + Do not use these APIs in your extension. They expose Python implementation + details and attempts to use them will not be supported by Python maintainers. From 5297d4a8a7fda08bf941a5a2c6d574939f9dc03d Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sun, 16 Nov 2025 13:53:16 -0500 Subject: [PATCH 02/12] Add a note about completeness. --- Doc/c-api/stable.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst index 49ba6f42fecedc..801d7db2f92d61 100644 --- a/Doc/c-api/stable.rst +++ b/Doc/c-api/stable.rst @@ -375,7 +375,8 @@ removal for compatibility's sake. The following is a list of soft deprecated symbols that were included in Python's public C API by mistake. They intentionally come with no additional -documentation. In practice, very few extensions use these APIs. +documentation and are only here for completeness. In practice, very few +extensions use these APIs. .. c:function:: PyObject *PyFile_NewStdPrinter(void) From 5559162ef194aed98bf3d9cfaf87a8d8519ee034 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sun, 16 Nov 2025 14:03:05 -0500 Subject: [PATCH 03/12] Fix typo. --- Doc/c-api/stable.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst index 801d7db2f92d61..fd471898423616 100644 --- a/Doc/c-api/stable.rst +++ b/Doc/c-api/stable.rst @@ -369,9 +369,9 @@ Currently, the :ref:`Limited API ` includes the following items: Soft-deprecated Symbols ======================= -There are a few symbols included in Python's C API are :term:`soft deprecated`. -Soft deprecated symbols should not be used in new code, but have no planned -removal for compatibility's sake. +There are a few symbols included in Python's C API that are +:term:`soft deprecated`. Soft deprecated symbols should not be used in new +code, but have no planned removal for compatibility's sake. The following is a list of soft deprecated symbols that were included in Python's public C API by mistake. They intentionally come with no additional From 5516aeb2639e0e03a01c5e01fcc6ad5cd19d8896 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 19 Nov 2025 06:26:34 -0500 Subject: [PATCH 04/12] Remove changes to stable.rst --- Doc/c-api/stable.rst | 30 ------------------------------ 1 file changed, 30 deletions(-) diff --git a/Doc/c-api/stable.rst b/Doc/c-api/stable.rst index fd471898423616..f5e6b7ad157e99 100644 --- a/Doc/c-api/stable.rst +++ b/Doc/c-api/stable.rst @@ -364,33 +364,3 @@ Contents of Limited API Currently, the :ref:`Limited API ` includes the following items: .. limited-api-list:: - - -Soft-deprecated Symbols -======================= - -There are a few symbols included in Python's C API that are -:term:`soft deprecated`. Soft deprecated symbols should not be used in new -code, but have no planned removal for compatibility's sake. - -The following is a list of soft deprecated symbols that were included in -Python's public C API by mistake. They intentionally come with no additional -documentation and are only here for completeness. In practice, very few -extensions use these APIs. - -.. c:function:: PyObject *PyFile_NewStdPrinter(void) - -.. c:var:: PyTypeObject PyStdPrinter_Type - -.. c:macro:: PyLong_BASE - -.. c:macro:: PyLong_MASK - -.. c:macro:: PyLong_SHIFT - -.. c:macro:: PySet_MINSIZE - -.. c:macro:: PyAsyncGenASend_CheckExact(op) - - Do not use these APIs in your extension. They expose Python implementation - details and attempts to use them will not be supported by Python maintainers. From d02736d2114724f2a8b7b97300219c9ad549e67f Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 19 Nov 2025 06:29:20 -0500 Subject: [PATCH 05/12] Move PyLong* symbols to long.rst --- Doc/c-api/long.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index ed34efe716d8b9..af36fcc8e5b3dc 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -855,3 +855,16 @@ 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 +^^^^^^^^^^^^^^ + +.. c:macro:: PyLong_BASE +.. c:macro:: PyLong_SHIFT +.. c:macro:: PyLong_MASK + + These macros are :term:`soft deprecated`. They represent internal constants + for :c:type:`PyLongObject` instances. + + Do not use these; use :c:func:`PyLong_GetNativeLayout` instead. From 0d0ca9a14a732eaf9d3c48fe460099b2d1f1e118 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 19 Nov 2025 06:31:42 -0500 Subject: [PATCH 06/12] Document PyAsyncGenASend_CheckExact() --- Doc/c-api/gen.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) 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. From 8f2e9244787169a3a9b6cbd04af92e284dae8c08 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 19 Nov 2025 06:34:50 -0500 Subject: [PATCH 07/12] Document PyFile_NewStdPrinter() and PyStdPrinter_Type --- Doc/c-api/file.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst index 9d01254ddb2a11..c5f9aea703c402 100644 --- a/Doc/c-api/file.rst +++ b/Doc/c-api/file.rst @@ -131,3 +131,15 @@ 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 +^^^^^^^^^^^^^^ + +.. c:function:: PyObject *PyFile_NewStdPrinter(void) + +.. c:var:: PyTypeObject PyStdPrinter_Type + + 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. From c1516846c69ef6ed4aba2ef48e3386c29d6befea Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 19 Nov 2025 06:38:49 -0500 Subject: [PATCH 08/12] Document PySet_MINSIZE --- Doc/c-api/set.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) 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. From df5566c2b6293c090be7739521cc6814d36db2e2 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 19 Nov 2025 07:40:50 -0500 Subject: [PATCH 09/12] Document the values of PyLong* macros. --- Doc/c-api/long.rst | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index af36fcc8e5b3dc..43c7b78c6ba9a4 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -860,11 +860,21 @@ The :c:type:`PyLongWriter` API can be used to import an integer. Deprecated API ^^^^^^^^^^^^^^ -.. c:macro:: PyLong_BASE +These macros are :term:`soft deprecated`. They represent internal constants +for :c:type:`PyLongObject` instances. + +Do not use these; use :c:func:`PyLong_GetNativeLayout` instead. + .. c:macro:: PyLong_SHIFT -.. c:macro:: PyLong_MASK - These macros are :term:`soft deprecated`. They represent internal constants - for :c:type:`PyLongObject` instances. + This is currently equivalent to ``30``. + + +.. c:macro:: PyLong_BASE + + This is currently equivalent to :c:expr:`1 << PyLong_SHIFT`. + + +.. c:macro:: PyLong_MASK - Do not use these; use :c:func:`PyLong_GetNativeLayout` instead. + This is currently equivalent to :c:expr:`PyLong_BASE - 1` From 8bcf20b9898d7663cc8911294c514629a313ec11 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 19 Nov 2025 09:37:16 -0500 Subject: [PATCH 10/12] Apply suggestions from code review Co-authored-by: Petr Viktorin --- Doc/c-api/file.rst | 15 +++++++++++---- Doc/c-api/long.rst | 15 ++++++++++----- 2 files changed, 21 insertions(+), 9 deletions(-) diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst index c5f9aea703c402..b0958b0e5613eb 100644 --- a/Doc/c-api/file.rst +++ b/Doc/c-api/file.rst @@ -136,10 +136,17 @@ the :mod:`io` APIs instead. Deprecated API ^^^^^^^^^^^^^^ -.. c:function:: PyObject *PyFile_NewStdPrinter(void) + +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 - 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. + Type of file-like objects used internally at Python startup when :py:mod:`io` is + not yet available. + Use :py:func:`io.open` or :c:func:`PyFile_FromFd` to create file objects instead. diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index 43c7b78c6ba9a4..afeb392b60bc95 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -860,14 +860,19 @@ The :c:type:`PyLongWriter` API can be used to import an integer. Deprecated API ^^^^^^^^^^^^^^ -These macros are :term:`soft deprecated`. They represent internal constants -for :c:type:`PyLongObject` instances. +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:`PyLongExport` and +:c:type:`PyLongWriter` to access integer data. +These currently use the same layout, but are designed to continue working correctly +even if CPython's internal integer representation changes. -Do not use these; use :c:func:`PyLong_GetNativeLayout` instead. .. c:macro:: PyLong_SHIFT - This is currently equivalent to ``30``. + This is equivalent to :c:member:`~PyLongLayout.bits_per_digit` in + the output of :c:func:`PyLong_GetNativeLayout`. .. c:macro:: PyLong_BASE @@ -877,4 +882,4 @@ Do not use these; use :c:func:`PyLong_GetNativeLayout` instead. .. c:macro:: PyLong_MASK - This is currently equivalent to :c:expr:`PyLong_BASE - 1` + This is currently equivalent to :c:expr:`(1 << PyLong_SHIFT) - 1` From e794b69e207defe308fe2a926169d7226a7cb858 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 19 Nov 2025 13:27:06 -0500 Subject: [PATCH 11/12] Update Doc/c-api/file.rst Co-authored-by: Victor Stinner --- Doc/c-api/file.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst index b0958b0e5613eb..0580e4c8f79db0 100644 --- a/Doc/c-api/file.rst +++ b/Doc/c-api/file.rst @@ -149,4 +149,4 @@ by mistake. They are documented solely for completeness; use other Type of file-like objects used internally at Python startup when :py:mod:`io` is not yet available. - Use :py:func:`io.open` or :c:func:`PyFile_FromFd` to create file objects instead. + Use Python :py:func:`open` or :c:func:`PyFile_FromFd` to create file objects instead. From 9e282c66a94cd370ead858d8995123225ee07b00 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Wed, 19 Nov 2025 13:27:16 -0500 Subject: [PATCH 12/12] Update Doc/c-api/long.rst Co-authored-by: Petr Viktorin --- Doc/c-api/long.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index afeb392b60bc95..6834c872c8cfcd 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -863,8 +863,8 @@ 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:`PyLongExport` and -:c:type:`PyLongWriter` to access integer data. +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.