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 1 commit
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
Prev Previous commit
Next Next commit
Update some C API entries
  • Loading branch information
@hugovk
hugovk committed Apr 16, 2026
commit b43e9c2e2ec1c00497d2516ca41031f3d65cdb70
12 changes: 7 additions & 5 deletions Doc/c-api/allocation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

.. _allocating-objects:

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


Expand Down Expand 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

@hugovk hugovk Apr 16, 2026

Copy link
Copy Markdown
Member Author

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

@StanFromIreland StanFromIreland Apr 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.

@hugovk hugovk Apr 16, 2026

Copy link
Copy Markdown
Member Author

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.

@StanFromIreland StanFromIreland Apr 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.

@hugovk hugovk Apr 16, 2026

Copy link
Copy Markdown
Member Author

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

@hugovk hugovk Apr 18, 2026

Copy link
Copy Markdown
Member Author

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?

@StanFromIreland StanFromIreland Apr 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.

@ZeroIntensity ZeroIntensity Apr 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.

@hugovk hugovk Apr 20, 2026

Copy link
Copy Markdown
Member Author

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
9 changes: 5 additions & 4 deletions Doc/c-api/file.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

.. _fileobjects:

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

.. index:: pair: object; file
Expand Down Expand 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

@hugovk hugovk Apr 18, 2026

Copy link
Copy Markdown
Member Author

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?

@hugovk hugovk Apr 20, 2026

Copy link
Copy Markdown
Member Author

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?

@ZeroIntensity ZeroIntensity Apr 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
22 changes: 7 additions & 15 deletions Doc/c-api/frame.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.. highlight:: c

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

.. c:type:: PyFrameObject
Expand Down Expand 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 Down Expand 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


Loading