Skip to content

Commit b9aa12f

Browse files
hugovkStanFromIreland
hugovk
and
StanFromIreland
committed
[3.13] Add a new Sphinx soft-deprecated directive (GH-148630)
(cherry picked from commit e9bbf86) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Stan Ulbrych <stan@python.org>
1 parent 53e0725 commit b9aa12f

File tree

8 files changed

+96
-31
lines changed

8 files changed

+96
-31
lines changed

‎Doc/c-api/allocation.rst‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
.. _allocating-objects:
44

5-
Allocating Objects on the Heap
5+
Allocating objects on the heap
66
==============================
77

88

@@ -71,18 +71,20 @@ Allocating Objects on the Heap
7171
To allocate and create extension modules.
7272
7373
74-
Deprecated aliases
75-
^^^^^^^^^^^^^^^^^^
74+
Soft-deprecated aliases
75+
^^^^^^^^^^^^^^^^^^^^^^^
7676
77-
These are :term:`soft deprecated` aliases to existing functions and macros.
77+
.. soft-deprecated:: 3.15
78+
79+
These are aliases to existing functions and macros.
7880
They exist solely for backwards compatibility.
7981
8082
8183
.. list-table::
8284
:widths: auto
8385
:header-rows: 1
8486
85-
* * Deprecated alias
87+
* * Soft-deprecated alias
8688
* Function
8789
* * .. c:macro:: PyObject_NEW(type, typeobj)
8890
* :c:macro:`PyObject_New`

‎Doc/c-api/frame.rst‎

Lines changed: 7 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.. highlight:: c
22

3-
Frame Objects
3+
Frame objects
44
-------------
55

66
.. c:type:: PyFrameObject
@@ -147,7 +147,7 @@ See also :ref:`Reflection <reflection>`.
147147
Return the line number that *frame* is currently executing.
148148
149149
150-
Frame Locals Proxies
150+
Frame locals proxies
151151
^^^^^^^^^^^^^^^^^^^^
152152
153153
.. versionadded:: 3.13
@@ -169,7 +169,7 @@ See :pep:`667` for more information.
169169
Return non-zero if *obj* is a frame :func:`locals` proxy.
170170
171171
172-
Legacy Local Variable APIs
172+
Legacy local variable APIs
173173
^^^^^^^^^^^^^^^^^^^^^^^^^^
174174
175175
These APIs are :term:`soft deprecated`. As of Python 3.13, they do nothing.
@@ -178,48 +178,42 @@ They exist solely for backwards compatibility.
178178
179179
.. c:function:: void PyFrame_LocalsToFast(PyFrameObject *f, int clear)
180180
181-
This function is :term:`soft deprecated` and does nothing.
182-
183181
Prior to Python 3.13, this function would copy the :attr:`~frame.f_locals`
184182
attribute of *f* to the internal "fast" array of local variables, allowing
185183
changes in frame objects to be visible to the interpreter. If *clear* was
186184
true, this function would process variables that were unset in the locals
187185
dictionary.
188186
189-
.. versionchanged:: 3.13
187+
.. soft-deprecated:: 3.13
190188
This function now does nothing.
191189
192190
193191
.. c:function:: void PyFrame_FastToLocals(PyFrameObject *f)
194192
195-
This function is :term:`soft deprecated` and does nothing.
196-
197193
Prior to Python 3.13, this function would copy the internal "fast" array
198194
of local variables (which is used by the interpreter) to the
199195
:attr:`~frame.f_locals` attribute of *f*, allowing changes in local
200196
variables to be visible to frame objects.
201197
202-
.. versionchanged:: 3.13
198+
.. soft-deprecated:: 3.13
203199
This function now does nothing.
204200
205201
206202
.. c:function:: int PyFrame_FastToLocalsWithError(PyFrameObject *f)
207203
208-
This function is :term:`soft deprecated` and does nothing.
209-
210204
Prior to Python 3.13, this function was similar to
211205
:c:func:`PyFrame_FastToLocals`, but would return ``0`` on success, and
212206
``-1`` with an exception set on failure.
213207
214-
.. versionchanged:: 3.13
208+
.. soft-deprecated:: 3.13
215209
This function now does nothing.
216210
217211
218212
.. seealso::
219213
:pep:`667`
220214
221215
222-
Internal Frames
216+
Internal frames
223217
^^^^^^^^^^^^^^^
224218
225219
Unless using :pep:`523`, you will not need this.
@@ -249,5 +243,3 @@ Unless using :pep:`523`, you will not need this.
249243
Return the currently executing line number, or -1 if there is no line number.
250244
251245
.. versionadded:: 3.12
252-
253-

‎Doc/c-api/long.rst‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -177,12 +177,10 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
177177
178178
.. c:function:: long PyLong_AS_LONG(PyObject *obj)
179179
180-
A :term:`soft deprecated` alias.
181180
Exactly equivalent to the preferred ``PyLong_AsLong``. In particular,
182181
it can fail with :exc:`OverflowError` or another exception.
183182
184-
.. deprecated:: 3.14
185-
The function is soft deprecated.
183+
.. soft-deprecated:: 3.14
186184
187185
.. c:function:: int PyLong_AsInt(PyObject *obj)
188186

‎Doc/c-api/module.rst‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -662,9 +662,7 @@ state:
662662
// PyModule_AddObject() stole a reference to obj:
663663
// Py_XDECREF(obj) is not needed here.
664664
665-
.. deprecated:: 3.13
666-
667-
:c:func:`PyModule_AddObject` is :term:`soft deprecated`.
665+
.. soft-deprecated:: 3.13
668666
669667
670668
.. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)

‎Doc/c-api/monitoring.rst‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,4 @@ would typically correspond to a Python function.
199199
200200
.. versionadded:: 3.13
201201
202-
.. deprecated:: 3.13.3
203-
204-
This function is :term:`soft deprecated`.
202+
.. soft-deprecated:: 3.13.3

‎Doc/library/mimetypes.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ the information :func:`init` sets up.
5454
.. versionchanged:: 3.8
5555
Added support for *url* being a :term:`path-like object`.
5656

57-
.. deprecated:: 3.13
57+
.. soft-deprecated:: 3.13
5858
Passing a file path instead of URL is :term:`soft deprecated`.
5959
Use :func:`guess_file_type` for this.
6060

‎Doc/tools/extensions/changes.py‎

Lines changed: 77 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,18 @@
22

33
from __future__ import annotations
44

5-
from typing import TYPE_CHECKING
5+
import re
66

7+
from docutils import nodes
8+
from sphinx import addnodes
79
from sphinx.domains.changeset import (
810
VersionChange,
911
versionlabel_classes,
1012
versionlabels,
1113
)
1214
from sphinx.locale import _ as sphinx_gettext
1315

16+
TYPE_CHECKING = False
1417
if TYPE_CHECKING:
1518
from docutils.nodes import Node
1619
from sphinx.application import Sphinx
@@ -73,6 +76,76 @@ def run(self) -> list[Node]:
7376
versionlabel_classes[self.name] = ""
7477

7578

79+
class SoftDeprecated(PyVersionChange):
80+
"""Directive for soft deprecations that auto-links to the glossary term.
81+
82+
Usage::
83+
84+
.. soft-deprecated:: 3.15
85+
86+
Use :func:`new_thing` instead.
87+
88+
Renders as: "Soft deprecated since version 3.15: Use new_thing() instead."
89+
with "Soft deprecated" linking to the glossary definition.
90+
"""
91+
92+
_TERM_RE = re.compile(r":term:`([^`]+)`")
93+
94+
def run(self) -> list[Node]:
95+
versionlabels[self.name] = sphinx_gettext(
96+
":term:`Soft deprecated` since version %s"
97+
)
98+
versionlabel_classes[self.name] = "soft-deprecated"
99+
try:
100+
result = super().run()
101+
finally:
102+
versionlabels[self.name] = ""
103+
versionlabel_classes[self.name] = ""
104+
105+
for node in result:
106+
# Add "versionchanged" class so existing theme CSS applies
107+
node["classes"] = node.get("classes", []) + ["versionchanged"]
108+
# Replace the plain-text "Soft deprecated" with a glossary reference
109+
for inline in node.findall(nodes.inline):
110+
if "versionmodified" in inline.get("classes", []):
111+
self._add_glossary_link(inline)
112+
113+
return result
114+
115+
@classmethod
116+
def _add_glossary_link(cls, inline: nodes.inline) -> None:
117+
"""Replace :term:`soft deprecated` text with a cross-reference to the
118+
'Soft deprecated' glossary entry."""
119+
for child in inline.children:
120+
if not isinstance(child, nodes.Text):
121+
continue
122+
123+
text = str(child)
124+
match = cls._TERM_RE.search(text)
125+
if match is None:
126+
continue
127+
128+
ref = addnodes.pending_xref(
129+
"",
130+
nodes.Text(match.group(1)),
131+
refdomain="std",
132+
reftype="term",
133+
reftarget="soft deprecated",
134+
refwarn=True,
135+
)
136+
137+
start, end = match.span()
138+
new_nodes: list[nodes.Node] = []
139+
if start > 0:
140+
new_nodes.append(nodes.Text(text[:start]))
141+
new_nodes.append(ref)
142+
if end < len(text):
143+
new_nodes.append(nodes.Text(text[end:]))
144+
145+
child.parent.replace(child, new_nodes)
146+
break
147+
148+
76149
def setup(app: Sphinx) -> ExtensionMetadata:
77150
# Override Sphinx's directives with support for 'next'
78151
app.add_directive("versionadded", PyVersionChange, override=True)
@@ -83,6 +156,9 @@ def setup(app: Sphinx) -> ExtensionMetadata:
83156
# Register the ``.. deprecated-removed::`` directive
84157
app.add_directive("deprecated-removed", DeprecatedRemoved)
85158

159+
# Register the ``.. soft-deprecated::`` directive
160+
app.add_directive("soft-deprecated", SoftDeprecated)
161+
86162
return {
87163
"version": "1.0",
88164
"parallel_read_safe": True,

‎Doc/tools/templates/dummy.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929

3030
{% trans %}Deprecated since version %s, will be removed in version %s{% endtrans %}
3131
{% trans %}Deprecated since version %s, removed in version %s{% endtrans %}
32+
{% trans %}:term:`Soft deprecated` since version %s{% endtrans %}
3233

3334
In docsbuild-scripts, when rewriting indexsidebar.html with actual versions:
3435

0 commit comments

Comments
 (0)