gh-92308: Add Pending Removal section to 3.11 What's New

[erlend-aasland]

Resolves gh-92308

[erlend-aasland]

This is mostly adaptions from the 3.10 What's New, Deprecated section. I kept the attributions.

[AA-Turner]

Wording suggestions, mainly on consistency (scheduled vs slated, I think scheduled is more immediately clear in meaning).

A broader point -- it might be more useful to re-group by module? So for importlib, group everything together, re-alphabetise the list, and then concatenate the issue and attribution links.

I think that would be more useful to the reader.

A

[ezio-melotti]

Would it make sense to group them by release, e.g.:

Python 3.12

• some func
• some other func

Python 3.13

• another func

TBD

• yet another func

---

This will also make it easier for the next version (unless we automate it in the meanwhile).

[erlend-aasland]

@ezio-melotti, I like that approach. If we can do without the attributions (?), it will make for a very compact list.

[hugovk]

I made PR erlend-aasland#30 to update this:

Add "What’s New In Python 3.10 > C API Changes > Deprecated"

to "What’s New In Python 3.11 > C API Changes > Pending Removal > Python 3.12"

https://docs.python.org/3.11/whatsnew/3.10.html#id3

No such section in:

• https://docs.python.org/3.11/whatsnew/3.9.html#changes-in-the-python-api
• https://docs.python.org/3.11/whatsnew/3.8.html#changes-in-the-python-api
• https://docs.python.org/3.11/whatsnew/3.7.html#changes-in-the-python-api
• https://docs.python.org/3.11/whatsnew/3.7.html#changes-in-the-python-api

(But I didn't check for deprecations mixed in the other sections.)

[hugovk]

@ezio-melotti, I like that approach. If we can do without the attributions (?), it will make for a very compact list.

Yes, looks good: users can easily prioritise what changes they need to make.

I think we could skip attributions because credit was already given when added in the first place?

[erlend-aasland]

I think we could skip attributions because credit was already given when added in the first place?

That was my thought as well. Please see recent commit. If this looks ok, I think pending removals for 3.12 is covered. I'll start looking for other stuff. Please shout out if I forget something (I likely will).

[erlend-aasland]

@hugovk, thanks for that heads-up. Would f8c2144 work?

[AA-Turner]

:: starts a code block (default Python), you just need a single colon here.

A

[AA-Turner]

The new format reads much better, thanks.

A

[erlend-aasland]

I think we got most stuff covered; we can expand this section later (IIRC, the docs are built and pushed out once a day). I'm inclined to marking this as ready for review and trying to land it.

[erlend-aasland]

The new format reads much better, thanks.

Thanks for helping!

[hugovk]

@hugovk, thanks for that heads-up. Would f8c2144 work?

Maybe it's better keeping it in the C API section? That's where new features and removed C API things go too:

https://docs.python.org/3.11/whatsnew/3.10.html#c-api-changes

Let's also ask @vstinner :)

[hugovk]

It's nice and compact but maybe too much info is missing: quite a few don't have links or further info (e.g. bpo links).

The extra info is important so users know what to replace with.

[AA-Turner]

quite a few don't have links or further info (e.g. bpo links)

That was part of removing the attributions I thought though, allowing re-sorting the list by module and not by tracker issue.

What would be the best remedy here? We could add the issue number per item (lots of duplication), break back to per-issue grouping (loose the nice sorting), perhaps add footnotes per-issue (break of source text and information link)?

A

[hugovk]

Ah, by attribution, I thought the "(Contributed by Hugo van Kemenade in bpo-47022.)" bit.

break back to per-issue grouping (loose the nice sorting)

I think this, sorting isn't so important, and we're grouping them by version number anyway.

[hugovk]

This "numeric literals followed by keyword" deprecation doesn't have a removal version, so would belong in a TDB/future section:

https://docs.python.org/3/whatsnew/3.10.html#deprecated

How would we put that in the compact list?

[AA-Turner]

How would we put that in the compact list?

By the compact list I'm assuming you mean the format as currently proposed by this PR. (Please correct me if you're not!)

I would suggest the final section after the version-specific sections would be entitled "Pending Removal" or some similarly generic title, and the lead would say something along the lines of:

"The following APIs were deprecated in earlier Python versions and will be removed, although there is currently no date scheduled for their removal."

A

[hugovk]

How would we put that in the compact list?

By the compact list I'm assuming you mean the format as currently proposed by this PR. (Please correct me if you're not!)

Yes, this list of mostly method/function/constant names.

I would suggest the final section after the version-specific sections would be entitled "Pending Removal" or some similarly generic title, and the lead would say something along the lines of:

"The following APIs were deprecated in earlier Python versions and will be removed, although there is currently no date scheduled for their removal."

Not so much about the lead, but about the content of the bullet point which can't really be distilled to a single name. I guess it could just be included more-or-less as is?

(This bit of course doesn't need to be part of this PR for the first beta, we can add it later :)

[AA-Turner]

the content of the bullet point which can't really be distilled to a single name. I guess it could just be included more-or-less as is?

Ahh, yes I understand. I'd suggest that pragmatism dictates simplifying to a single name where possible, and where there are language or syntax changes (such as this), we include a short prose explanation and a link if appropriate.

The text as written seems reasonable to copy verbatim, following this framework.

A

[ezio-melotti]

Not so much about the lead, but about the content of the bullet point which can't really be distilled to a single name.

The "short" name could be "numeric literals immediately followed by a keyword", and then you can expand on it:

Numeric literals immediately followed by a keyword. Currently Python accepts expressions like 0in x, 1or x, 0if 1else 2, or [0x1for x in y] (which is ambiguous because it can be interpreted as [0x1 for x in y] or [0x1f or x in y]). Starting in this release, a deprecation warning is raised if the numeric literal is immediately followed by and, or, in, is, if, else or for. In future releases it will be changed to syntax warning, and finally to syntax error.

---

This "numeric literals followed by keyword" deprecation doesn't have a removal version, so would belong in a TDB/future section:

We could also try to enforce a target release for removal, even if it ends up being postponed. This will also make it easier to track deprecations. I also (half-jokingly) suggested to deprecate the deprecated directive in favor of deprecated-removed.

In the meanwhile, a TBD/Future section works.

[hugovk]

I created erlend-aasland#31 as a suggestion to add this future pending removal.

Whether we include it now or later, I think this PR as it stands is good to merge so we can get it in today's beta :)

It would be nice if every entry had a link, so the user can find out more about what/why something is deprecated, but it's not a blocker.

Thanks!

[vstinner]

LGTM.

While they are many ways to document these pending removals. I'm also fine with current list with just give names and nothing else. It's easy to name, easy to maintain.

If you click on a function, you can find the deprecation note there and usually you get a suggestion to replace the deprecated function. For example, importlib.find_loader() suggests using importlib.util.find_spec() instead.

I just suggest to move the C API list in the C API Changes section (near the end of the document).

[vstinner]

Around Python 3.9, I moved Build Changes and C API changes at the end of the document since most users never write any line of C API. I suggest you to move this list inside the C API Changes section: add a new " Pending Removal in Python 3.12" section there.

[CAM-Gerlach]

If you click on a function, you can find the deprecation note there and usually you get a suggestion to replace the deprecated function. For example, importlib.find_loader() suggests using importlib.util.find_spec() instead.

Yeah; typically, I'd think if a user actually uses a function, they'd want more details anyway, and if functions don't have clear guidance on why they are deprecated and what to replace them with (or not), then it can be added there.

[erlend-aasland]

I'll follow up the comments on this PR over the weekend; if any one would like to land this earlier, please create a new PR (or just take over this PR) 🙂

[bedevere-bot]

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

And if you don't make the requested changes, you will be put in the comfy chair!

[miss-islington]

Thanks @erlend-aasland for the PR, and @ezio-melotti for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖

[bedevere-bot]

GH-92444 is a backport of this pull request to the 3.11 branch.