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?

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.

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

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 added 3 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

		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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

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