Add a new Sphinx `soft-deprecated` directive by hugovk · Pull Request #148630 · python/cpython

hugovk · 2026-04-15T20:20:27Z

Follow on from #86519 and #148100.

Add a new Sphinx soft-deprecated directive, which explicitly links to the glossary definition, and is yellow instead of red because it does not indicate removal.

📚 Documentation preview 📚: https://cpython-previews--148630.org.readthedocs.build/

StanFromIreland

This is great Hugo, I also had been dreaming of this recently!

StanFromIreland · 2026-04-15T20:40:13Z

+    """
+
+    def run(self) -> list[Node]:
+        versionlabels[self.name] = sphinx_gettext(


How will this work in a translation, _add_glossary_link sets marker = "Soft deprecated"?

Also, you'll have to add the message to dummy.html for it to be extracted IIRC.

How will this work in a translation, _add_glossary_link sets marker = "Soft deprecated"?

I just pushed bee4f6c, I think that might do it?

Also, you'll have to add the message to dummy.html for it to be extracted IIRC.

Thanks, added.

I think that might do it?

It will do it for Polish, but I worry in other languages it might not (I fear it is possible in some there may be a slight difference between the term's stand-alone form and it in a sentence).

This standalone text is only used for replacing in the full sentence, and not used on its own. So each translation will need to put whatever they have in the sentence.

Yes, but how are translators supposed to know that?

Shall we add a comment in Doc/tools/templates/dummy.html?

Translators won't see it unfortunately, Sphinx doesn’t support adding comments for translators. Can we have :term:`soft deprecated` in the string?

I wrote hugovk#81.

StanFromIreland · 2026-04-15T20:40:22Z

+            versionlabel_classes[self.name] = ""
+
+        for node in result:
+            # Add "versionchanged" class so existing theme CSS applies


We use yellow for versionchanged and thread safety notes, I worry they all look a little too similar. I would suggest it gets its' own styling, maybe orange?

Hmm, yellow is more of a "heads up, note this". Orange might be considered closer to "red for danger", and we don't want to suggest it's going away.

Hmm, yellow is more of a "heads up, note this". Orange might be considered closer to "red for danger", and we don't want to suggest it's going away.

Indeed, but we also want it to stand out compared to other notes (at least that's what I think). Some functions have quite long lists of yellow change notes that, e.g. I often ignore when just looking for current information about a thing, and would probably miss a soft deprecation note at the end. We aren't removing it, but we also don't want people using it.

We use green for additions, yellow for changes and red for deprecations so I would suggest using blue/purple for soft deprecation. A soft deprecation is a change, but not one that screams "I am new!" or "I am bad" but rather "please note this".

To have the same color on both themes, I would go with 3b82f6 or 1e6ff5.

Here's the current, #3b82f6 and #1e6ff5 for each theme:

If we change the colour, we'll override it via https://github.com/python/python-docs-theme.

I like Bénédikt's purple (rgb(175, 0, 255) below) suggestion, but blue is alright:

I'm not so keen on purple, and the contrast ratio is too low for dark mode:

Oh I see, that's not ideal. I also checked #3b82f6 and neither dark (4.33) nor light (3.68) meet the requirements. Similarly for #1e6ff5, it meets the requirements only in light (4.52) and not in dark (3.52).

Yeah, we can use different colours for light and dark. Anyway, we can bikeshed that in the theme.

I wrote python/python-docs-theme#305.

Co-authored-by: Stan Ulbrych <stan@python.org>

ZeroIntensity · 2026-04-16T02:07:57Z

Would you mind also updating C API entries that only reference :term:`soft deprecated` (without the .. deprecated directive)? I decided not to use it when soft-deprecating things for #141004.

For example:

I'm also happy to do this in a follow-up if you'd rather land this PR sooner.

hugovk · 2026-04-16T14:24:59Z

@ZeroIntensity I've done those three, but there's quite a lot so I'll let you do the rest in a follow-up :) Alternatively, you're welcome to push to this branch or open a PR against mine.

hugovk · 2026-04-16T14:43:55Z

+Soft-deprecated aliases
+^^^^^^^^^^^^^^^^^^^^^^^


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

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.

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.

"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.

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

StanFromIreland

$${\color{purple}LGTM}$$!

We haven't covered all entries that are :term:`soft deprected` , but I think they can be done in follow ups.

ZeroIntensity · 2026-04-18T00:02:08Z

Yeah, let's get this merged. I'll handle the remaining C API entries later.

miss-islington-app · 2026-04-18T08:37:58Z

Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

miss-islington-app · 2026-04-18T08:38:00Z

Sorry, @hugovk, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker e9bbf8617dff942360b5d800769c00440dc93bac 3.14

miss-islington-app · 2026-04-18T08:38:04Z

Sorry, @hugovk, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker e9bbf8617dff942360b5d800769c00440dc93bac 3.13

hugovk · 2026-04-18T09:00:01Z

+^^^^^^^^^^^^^^^^^^^^^^^

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


@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?

hugovk · 2026-04-18T09:05:26Z

+Soft-deprecated API
+^^^^^^^^^^^^^^^^^^^

+.. soft-deprecated:: 3.15


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?

(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>

bedevere-app · 2026-04-18T09:06:54Z

GH-148714 is a backport of this pull request to the 3.14 branch.

bedevere-app · 2026-04-18T09:13:21Z

GH-148715 is a backport of this pull request to the 3.13 branch.

(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>

hugovk added 3 commits April 15, 2026 23:10

Add soft-deprecated directive

df3809c

Use 'soft-deprecated' directive instead of 'deprecated'

3f88cf5

Split prefixmatch/match into versionadded/soft-deprecated

fe5f42e

hugovk requested a review from a team as a code owner April 15, 2026 20:20

hugovk added the needs backport to 3.13 bugs and security fixes label Apr 15, 2026

hugovk requested review from AA-Turner, ZeroIntensity and ericsnowcurrently as code owners April 15, 2026 20:20

hugovk added the needs backport to 3.14 bugs and security fixes label Apr 15, 2026

hugovk requested a review from StanFromIreland as a code owner April 15, 2026 20:20

bedevere-app bot added the awaiting core review label Apr 15, 2026

hugovk mentioned this pull request Apr 15, 2026

Soft deprecate re.match and re.Pattern.match in favour of prefixmatch #148100

Closed

hugovk added skip issue skip news docs Documentation in the Doc dir labels Apr 15, 2026

github-project-automation bot added this to Docs PRs Apr 15, 2026

github-project-automation bot moved this to Todo in Docs PRs Apr 15, 2026

StanFromIreland reviewed Apr 15, 2026

View reviewed changes

hugovk and others added 4 commits April 15, 2026 23:51

Fix wording

83ebd59

Co-authored-by: Stan Ulbrych <stan@python.org>

Remove outdated note

9b84663

Make directive translatable

d20f5bf

Make 'soft deprecated' translatable

bee4f6c

Update some C API entries

b43e9c2

hugovk commented Apr 16, 2026

View reviewed changes

hugovk and others added 4 commits April 16, 2026 17:53

Update class name

0eee3e3

Ignore c-api/file.html: deprecated-api

768cab3

Ignore c-api/allocation.html: deprecated-aliases

2d493f0

Use :term: instead for translators

a16ca8b

StanFromIreland mentioned this pull request Apr 17, 2026

Add styling for soft-deprecated class python/python-docs-theme#305

Open

hugovk added 2 commits April 17, 2026 21:44

Use :term: instead for translators (#81)

7ebf41b

fixup! Use 'soft-deprecated' directive instead of 'deprecated'

70e7f8d

StanFromIreland approved these changes Apr 17, 2026

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting core review labels Apr 17, 2026

hugovk merged commit e9bbf86 into python:main Apr 18, 2026
34 checks passed

hugovk deleted the 3.15-docs-soft-deprecate-directive branch April 18, 2026 08:37

github-project-automation bot moved this from Todo to Done in Docs PRs Apr 18, 2026

bedevere-app bot removed the awaiting merge label Apr 18, 2026

miss-islington-app bot assigned hugovk Apr 18, 2026

hugovk commented Apr 18, 2026

View reviewed changes

hugovk mentioned this pull request Apr 18, 2026

[3.14] Add a new Sphinx soft-deprecated directive (GH-148630) #148714

Draft

bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Apr 18, 2026

hugovk mentioned this pull request Apr 18, 2026

[3.13] Add a new Sphinx soft-deprecated directive (GH-148630) #148715

Draft

bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Apr 18, 2026

		Soft-deprecated aliases
		^^^^^^^^^^^^^^^^^^^^^^^

Uh oh!

Conversation

hugovk commented Apr 15, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

picnixz Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StanFromIreland Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StanFromIreland Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity commented Apr 16, 2026

Uh oh!

hugovk commented Apr 16, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity commented Apr 18, 2026

Uh oh!

Uh oh!

miss-islington-app bot commented Apr 18, 2026

Uh oh!

miss-islington-app bot commented Apr 18, 2026

Uh oh!

miss-islington-app bot commented Apr 18, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hugovk commented Apr 15, 2026 •

edited by github-actions bot

Loading

picnixz Apr 16, 2026 •

edited

Loading

StanFromIreland Apr 16, 2026 •

edited

Loading

StanFromIreland Apr 16, 2026 •

edited

Loading