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

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/

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

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.

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>

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.

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

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

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

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

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

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

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

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

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

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

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:

I firmly believe that aliases should be inherently soft-deprecated ("There should be one-- and preferably only one --obvious way to do it").
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.
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.

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

And update main in the next PR.

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?

@ZeroIntensity And what about this one?

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

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

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

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>

) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Stan Ulbrych <stan@python.org>

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

) 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

Merged

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

Merged

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

Merged

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

hugovk added a commit that referenced this pull request Apr 22, 2026

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

5b33424

) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Stan Ulbrych <stan@python.org>

ljfp pushed a commit to ljfp/cpython that referenced this pull request Apr 25, 2026

Add a new Sphinx soft-deprecated directive (python#148630 )

f960f2b

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

hugovk added a commit that referenced this pull request Jun 14, 2026

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

6971e05

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

hugovk mentioned this pull request Aug 4, 2026

Support soft-deprecated directive python/release-tools#428

Merged

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

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

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

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

Uh oh!

Uh oh!

Add a new Sphinx soft-deprecated directive - #148630

Add a new Sphinx soft-deprecated directive#148630hugovk merged 14 commits intopython:mainpython/cpython:mainfrom hugovk:3.15-docs-soft-deprecate-directivehugovk/cpython:3.15-docs-soft-deprecate-directiveCopy head branch name to clipboard

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!

Add a new Sphinx soft-deprecated directive#148630
hugovk merged 14 commits into
python:mainfrom
hugovk:3.15-docs-soft-deprecate-directive

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