Skip to content

Add a new Sphinx soft-deprecated directive#148630

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hugovk merged 14 commits into from
Apr 18, 2026
Merged

Add a new Sphinx soft-deprecated directive #148630

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
df3809c
Add soft-deprecated directive
hugovk Apr 5, 2026
3f88cf5
Use 'soft-deprecated' directive instead of 'deprecated'
hugovk Apr 5, 2026
fe5f42e
Split prefixmatch/match into versionadded/soft-deprecated
hugovk Apr 15, 2026
83ebd59
Fix wording
hugovk Apr 15, 2026
9b84663
Remove outdated note
hugovk Apr 15, 2026
d20f5bf
Make directive translatable
hugovk Apr 15, 2026
bee4f6c
Make 'soft deprecated' translatable
hugovk Apr 15, 2026
b43e9c2
Update some C API entries
hugovk Apr 16, 2026
0eee3e3
Update class name
hugovk Apr 16, 2026
768cab3
Ignore c-api/file.html: deprecated-api
hugovk Apr 16, 2026
2d493f0
Ignore c-api/allocation.html: deprecated-aliases
hugovk Apr 16, 2026
a16ca8b
Use `:term:` instead for translators
StanFromIreland Apr 17, 2026
7ebf41b
Use `:term:` instead for translators (#81)
hugovk Apr 17, 2026
70e7f8d
fixup! Use 'soft-deprecated' directive instead of 'deprecated'
hugovk Apr 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions Doc/c-api/allocation.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

.. _allocating-objects:

Allocating Objects on the Heap
Allocating objects on the heap
==============================


Expand DownExpand Up@@ -153,18 +153,20 @@ Allocating Objects on the Heap
To allocate and create extension modules.


Deprecated aliases
^^^^^^^^^^^^^^^^^^
Soft-deprecated aliases
^^^^^^^^^^^^^^^^^^^^^^^
Comment on lines +156 to +157

@hugovkhugovkApr 16, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

ERROR: Removed IDs found
The above HTML IDs were removed from the documentation, resulting in broken links. Please add them back.
c-api/allocation.html: deprecated-aliases
c-api/file.html: deprecated-api
Alternatively, add them to Doc/tools/removed-ids.txt.

This change was intentional as it makes it explicit these aren't going away, and the header is new in 3.15.

Shall I:

  • Add ref deprecated-alises just above it
  • Add to Doc/tools/removed-ids.txt
  • Revert

@StanFromIrelandStanFromIrelandApr 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seeing as it's quite new I think it is unlikely we're breaking anyone’s reference. So, I suggest we create a "remove from here in 3.16" section in removed-ids.txt for such changes.

@hugovkhugovkApr 16, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feedback for the tool output:

The above HTML IDs were removed from the documentation, resulting in broken links. Please add them back.
c-api/allocation.html: deprecated-aliases
c-api/file.html: deprecated-api
Alternatively, add them to Doc/tools/removed-ids.txt.

"above" should read "below". Can improve spacing to make both warnings more obvious:

The below HTML IDs were removed from the documentation, resulting in broken links. Please add them back.
c-api/allocation.html: deprecated-aliases
c-api/file.html: deprecated-api
Alternatively, add them to Doc/tools/removed-ids.txt.

@StanFromIrelandStanFromIrelandApr 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"above" should read "below". Can improve spacing to make both warnings more obvious:

"above" is technically correct IIRC (from when I tried to add color), it is just GitHub mangling stdout/err and the line ends up above. We should have an issue for further improvements.

@hugovkhugovkApr 16, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, indeed, we can have different output:

ERROR: Removed IDs found
The above HTML IDs were removed from the documentation, resulting in broken links. Please add them back.
c-api/allocation.html: deprecated-aliases
c-api/file.html: deprecated-api
Alternatively, add them to Doc/tools/removed-ids.txt.

https://github.com/python/cpython/actions/runs/24515704242/job/71659379442?pr=148630

ERROR: Removed IDs found
c-api/allocation.html: deprecated-aliases
The above HTML IDs were removed from the documentation, resulting in broken links. Please add them back.
c-api/file.html: deprecated-api
Alternatively, add them to Doc/tools/removed-ids.txt.

https://github.com/python/cpython/actions/runs/24517209594/job/71664949402?pr=148630

After ignoring file.html:

ERROR: Removed IDs found
c-api/allocation.html: deprecated-aliases
The above HTML IDs were removed from the documentation, resulting in broken links. Please add them back.
Alternatively, add them to Doc/tools/removed-ids.txt.

https://github.com/python/cpython/actions/runs/24521766250/job/71681524452?pr=148630


These are :term:`soft deprecated` aliases to existing functions and macros.
.. soft-deprecated:: 3.15

@hugovkhugovkApr 18, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ZeroIntensity This section was first added to docs in #141146 and backported to 3.13.

That PR said:

There are already deprecated, so this can be backported.

That links to code from PR #23586, which deprecated them in code comments in 3.10.

So, should this say 3.15 or 3.10 or something else?

@StanFromIrelandStanFromIrelandApr 20, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A 'lil ping @ZeroIntensity in case you missed these.

@ZeroIntensityZeroIntensityApr 20, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I missed this, thanks for the ping.

I think 3.10 makes the most sense here. For clarification, some aliases documented by #141004 were marked with "soft deprecated" without a formal decision by the C API WG to mark them as such. I did this because:

  1. I firmly believe that aliases should be inherently soft-deprecated ("There should be one-- and preferably only one --obvious way to do it").
  2. There's not really any to not deprecate an alias, so asking the WG several times would have just been noise and a waste of time.
  3. If someone really objected for whatever reason, it's super easy to un-soft-deprecate something.

This means that I bypassed the formal process for soft-deprecation on a few things (sorry!), so, at least for aliases, there's not always a clear version in which something was soft deprecated. For .. soft-deprecated markers, I think it would be best to use the version in which the thing became an alias, or if it started out as an alias (such as PyBUF_WRITEABLE), we should just use the version in which it was added.

@hugovkhugovkApr 20, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, we can update it to 3.10 in the backports: #148714, #148715.

And update main in the next PR.


These are aliases to existing functions and macros.
They exist solely for backwards compatibility.


.. list-table::
:widths: auto
:header-rows: 1

* * Deprecated alias
* * Soft-deprecated alias
* Function
* * .. c:macro:: PyObject_NEW(type, typeobj)
* :c:macro:`PyObject_New`
Expand Down
11 changes: 5 additions & 6 deletions Doc/c-api/bytes.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -47,9 +47,9 @@ called with a non-bytes parameter.
*len* on success, and ``NULL`` on failure. If *v* is ``NULL``, the contents of
the bytes object are uninitialized.

.. deprecated:: 3.15
``PyBytes_FromStringAndSize(NULL, len)`` is :term:`soft deprecated`,
use the :c:type:`PyBytesWriter` API instead.
.. soft-deprecated:: 3.15
Use the :c:type:`PyBytesWriter` API instead of
``PyBytes_FromStringAndSize(NULL, len)``.


.. c:function:: PyObject* PyBytes_FromFormat(const char *format, ...)
Expand DownExpand Up@@ -238,9 +238,8 @@ called with a non-bytes parameter.
*\*bytes* is set to ``NULL``, :exc:`MemoryError` is set, and ``-1`` is
returned.

.. deprecated:: 3.15
The function is :term:`soft deprecated`,
use the :c:type:`PyBytesWriter` API instead.
.. soft-deprecated:: 3.15
Use the :c:type:`PyBytesWriter` API instead.


.. c:function:: PyObject *PyBytes_Repr(PyObject *bytes, int smartquotes)
Expand Down
11 changes: 5 additions & 6 deletions Doc/c-api/extension-modules.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -191,10 +191,10 @@ the :c:data:`Py_mod_multiple_interpreters` slot.
``PyInit`` function
...................

.. deprecated:: 3.15
.. soft-deprecated:: 3.15

This functionality is :term:`soft deprecated`.
It will not get new features, but there are no plans to remove it.
This functionality will not get new features,
but there are no plans to remove it.

Instead of :c:func:`PyModExport_modulename`, an extension module can define
an older-style :dfn:`initialization function` with the signature:
Expand DownExpand Up@@ -272,10 +272,9 @@ For example, a module called ``spam`` would be defined like this::
Legacy single-phase initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. deprecated:: 3.15
.. soft-deprecated:: 3.15

Single-phase initialization is :term:`soft deprecated`.
It is a legacy mechanism to initialize extension
Single-phase initialization is a legacy mechanism to initialize extension
modules, with known drawbacks and design flaws. Extension module authors
are encouraged to use multi-phase initialization instead.

Expand Down
9 changes: 5 additions & 4 deletions Doc/c-api/file.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,7 +2,7 @@

.. _fileobjects:

File Objects
File objects
------------

.. index:: pair: object; file
Expand DownExpand Up@@ -136,11 +136,12 @@ the :mod:`io` APIs instead.
failure; the appropriate exception will be set.


Deprecated API
^^^^^^^^^^^^^^
Soft-deprecated API
^^^^^^^^^^^^^^^^^^^

.. soft-deprecated:: 3.15

@hugovkhugovkApr 18, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similarly, this section was added in #141634 and backported to 3.13.

I don't think this was deprecated in code comments. What version should we have?

@hugovkhugovkApr 20, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ZeroIntensity And what about this one?

@ZeroIntensityZeroIntensityApr 20, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These were deprecated via a WG vote, so the formal version for deprecation is 3.15. As Petr said, #141634 wasn't supposed to be backported, but it wasn't worth reverting the 3.14 backport (the 3.13 one failed).


These are :term:`soft deprecated` APIs that were included in Python's C API
These are APIs that were included in Python's C API
by mistake. They are documented solely for completeness; use other
``PyFile*`` APIs instead.

Expand Down
18 changes: 8 additions & 10 deletions Doc/c-api/float.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -86,8 +86,7 @@ Floating-Point Objects
It is equivalent to the :c:macro:`!INFINITY` macro from the C11 standard
``<math.h>`` header.

.. deprecated:: 3.15
The macro is :term:`soft deprecated`.
.. soft-deprecated:: 3.15


.. c:macro:: Py_NAN
Expand All@@ -103,8 +102,7 @@ Floating-Point Objects

Equivalent to :c:macro:`!INFINITY`.

.. deprecated:: 3.14
The macro is :term:`soft deprecated`.
.. soft-deprecated:: 3.14


.. c:macro:: Py_MATH_E
Expand DownExpand Up@@ -161,26 +159,26 @@ Floating-Point Objects
that is, it is normal, subnormal or zero, but not infinite or NaN.
Return ``0`` otherwise.

.. deprecated:: 3.14
The macro is :term:`soft deprecated`. Use :c:macro:`!isfinite` instead.
.. soft-deprecated:: 3.14
Use :c:macro:`!isfinite` instead.


.. c:macro:: Py_IS_INFINITY(X)

Return ``1`` if the given floating-point number *X* is positive or negative
infinity. Return ``0`` otherwise.

.. deprecated:: 3.14
The macro is :term:`soft deprecated`. Use :c:macro:`!isinf` instead.
.. soft-deprecated:: 3.14
Use :c:macro:`!isinf` instead.


.. c:macro:: Py_IS_NAN(X)

Return ``1`` if the given floating-point number *X* is a not-a-number (NaN)
value. Return ``0`` otherwise.

.. deprecated:: 3.14
The macro is :term:`soft deprecated`. Use :c:macro:`!isnan` instead.
.. soft-deprecated:: 3.14
Use :c:macro:`!isnan` instead.


Pack and Unpack functions
Expand Down
22 changes: 7 additions & 15 deletions Doc/c-api/frame.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
.. highlight:: c

Frame Objects
Frame objects
-------------

.. c:type:: PyFrameObject
Expand DownExpand Up@@ -147,7 +147,7 @@ See also :ref:`Reflection <reflection>`.
Return the line number that *frame* is currently executing.


Frame Locals Proxies
Frame locals proxies
^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 3.13
Expand All@@ -169,7 +169,7 @@ See :pep:`667` for more information.
Return non-zero if *obj* is a frame :func:`locals` proxy.


Legacy Local Variable APIs
Legacy local variable APIs
^^^^^^^^^^^^^^^^^^^^^^^^^^

These APIs are :term:`soft deprecated`. As of Python 3.13, they do nothing.
Expand All@@ -178,48 +178,42 @@ They exist solely for backwards compatibility.

.. c:function:: void PyFrame_LocalsToFast(PyFrameObject *f, int clear)

This function is :term:`soft deprecated` and does nothing.

Prior to Python 3.13, this function would copy the :attr:`~frame.f_locals`
attribute of *f* to the internal "fast" array of local variables, allowing
changes in frame objects to be visible to the interpreter. If *clear* was
true, this function would process variables that were unset in the locals
dictionary.

.. versionchanged:: 3.13
.. soft-deprecated:: 3.13
This function now does nothing.


.. c:function:: void PyFrame_FastToLocals(PyFrameObject *f)

This function is :term:`soft deprecated` and does nothing.

Prior to Python 3.13, this function would copy the internal "fast" array
of local variables (which is used by the interpreter) to the
:attr:`~frame.f_locals` attribute of *f*, allowing changes in local
variables to be visible to frame objects.

.. versionchanged:: 3.13
.. soft-deprecated:: 3.13
This function now does nothing.


.. c:function:: int PyFrame_FastToLocalsWithError(PyFrameObject *f)

This function is :term:`soft deprecated` and does nothing.

Prior to Python 3.13, this function was similar to
:c:func:`PyFrame_FastToLocals`, but would return ``0`` on success, and
``-1`` with an exception set on failure.

.. versionchanged:: 3.13
.. soft-deprecated:: 3.13
This function now does nothing.


.. seealso::
:pep:`667`


Internal Frames
Internal frames
^^^^^^^^^^^^^^^

Unless using :pep:`523`, you will not need this.
Expand DownExpand Up@@ -249,5 +243,3 @@ Unless using :pep:`523`, you will not need this.
Return the currently executing line number, or -1 if there is no line number.

.. versionadded:: 3.12


27 changes: 9 additions & 18 deletions Doc/c-api/intro.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -536,16 +536,14 @@ have been standardized in C11 (or previous standards).

Use the standard ``alignas`` specifier rather than this macro.

.. deprecated:: 3.15
The macro is :term:`soft deprecated`.
.. soft-deprecated:: 3.15

.. c:macro:: PY_FORMAT_SIZE_T

The :c:func:`printf` formatting modifier for :c:type:`size_t`.
Use ``"z"`` directly instead.

.. deprecated:: 3.15
The macro is :term:`soft deprecated`.
.. soft-deprecated:: 3.15

.. c:macro:: Py_LL(number)
Py_ULL(number)
Expand All@@ -558,8 +556,7 @@ have been standardized in C11 (or previous standards).

Consider using the C99 standard suffixes ``LL`` and ``LLU`` directly.

.. deprecated:: 3.15
The macro is :term:`soft deprecated`.
.. soft-deprecated:: 3.15

.. c:macro:: PY_LONG_LONG
PY_INT32_T
Expand All@@ -572,8 +569,7 @@ have been standardized in C11 (or previous standards).
respectively.
Historically, these types needed compiler-specific extensions.

.. deprecated:: 3.15
These macros are :term:`soft deprecated`.
.. soft-deprecated:: 3.15

.. c:macro:: PY_LLONG_MIN
PY_LLONG_MAX
Expand All@@ -587,16 +583,14 @@ have been standardized in C11 (or previous standards).
The required header, ``<limits.h>``,
:ref:`is included <capi-system-includes>` in ``Python.h``.

.. deprecated:: 3.15
These macros are :term:`soft deprecated`.
.. soft-deprecated:: 3.15

.. c:macro:: Py_MEMCPY(dest, src, n)

This is a :term:`soft deprecated` alias to :c:func:`!memcpy`.
Use :c:func:`!memcpy` directly instead.

.. deprecated:: 3.14
The macro is :term:`soft deprecated`.
.. soft-deprecated:: 3.14

.. c:macro:: Py_UNICODE_SIZE

Expand All@@ -606,16 +600,14 @@ have been standardized in C11 (or previous standards).
The required header for the latter, ``<limits.h>``,
:ref:`is included <capi-system-includes>` in ``Python.h``.

.. deprecated:: 3.15
The macro is :term:`soft deprecated`.
.. soft-deprecated:: 3.15

.. c:macro:: Py_UNICODE_WIDE

Defined if ``wchar_t`` can hold a Unicode character (UCS-4).
Use ``sizeof(wchar_t) >= 4`` instead

.. deprecated:: 3.15
The macro is :term:`soft deprecated`.
.. soft-deprecated:: 3.15

.. c:macro:: Py_VA_COPY

Expand All@@ -627,8 +619,7 @@ have been standardized in C11 (or previous standards).
.. versionchanged:: 3.6
This is now an alias to ``va_copy``.

.. deprecated:: 3.15
The macro is :term:`soft deprecated`.
.. soft-deprecated:: 3.15


.. _api-objects:
Expand Down
4 changes: 1 addition & 3 deletions Doc/c-api/long.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -197,12 +197,10 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.

.. c:function:: long PyLong_AS_LONG(PyObject *obj)

A :term:`soft deprecated` alias.
Exactly equivalent to the preferred ``PyLong_AsLong``. In particular,
it can fail with :exc:`OverflowError` or another exception.

.. deprecated:: 3.14
The function is soft deprecated.
.. soft-deprecated:: 3.14

.. c:function:: int PyLong_AsInt(PyObject *obj)

Expand Down
4 changes: 1 addition & 3 deletions Doc/c-api/module.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -954,9 +954,7 @@ or code that creates modules dynamically.
// PyModule_AddObject() stole a reference to obj:
// Py_XDECREF(obj) is not needed here.

.. deprecated:: 3.13

:c:func:`PyModule_AddObject` is :term:`soft deprecated`.
.. soft-deprecated:: 3.13


.. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
Expand Down
4 changes: 1 addition & 3 deletions Doc/c-api/monitoring.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -205,6 +205,4 @@ would typically correspond to a Python function.

.. versionadded:: 3.13

.. deprecated:: 3.14

This function is :term:`soft deprecated`.
.. soft-deprecated:: 3.14
5 changes: 2 additions & 3 deletions Doc/c-api/sequence.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -109,9 +109,8 @@ Sequence Protocol

Alias for :c:func:`PySequence_Contains`.

.. deprecated:: 3.14
The function is :term:`soft deprecated` and should no longer be used to
write new code.
.. soft-deprecated:: 3.14
The function should no longer be used to write new code.


.. c:function:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)
Expand Down
7 changes: 3 additions & 4 deletions Doc/library/ctypes.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -1756,11 +1756,10 @@ as a default or fallback.
(or by) Python.
It is recommended to only use this function as a default or fallback,

.. deprecated:: 3.15
.. soft-deprecated:: 3.15

This function is :term:`soft deprecated`.
It is kept for use in cases where it works, but not expected to be
updated for additional platforms and configurations.
This function is kept for use in cases where it works, but not expected to
be updated for additional platforms and configurations.

On Linux, :func:`!find_library` tries to run external
programs (``/sbin/ldconfig``, ``gcc``, ``objdump`` and ``ld``) to find the
Expand Down
Loading
Loading