Enforce the use of `deprecated-removed` in docs · Issue #92564 · python/cpython

As a "regular" Python user (er, well, docs team member, PEP editor and triager, but not a core dev), I'd strongly err on the side of being explicit over implicit and specifying something with regard to the removal version, even if that's 4.0, TBD or never.

If a specific 3.x version is known (or can be decided on), it is very helpful to state that up front, even if is later pushed back, in order to be able to plan around it as a library maintainer who wants to support a reasonably wide range of Python versions, and a FOSS application developer with limited bandwidth who wants to prioritize addressing things that will be actively removed soon; not only is this helpful for users like myself who actively watch, test for and fix deprecations, but also in convincing others convincing others of the necessity of doing so.

And if one is not known (yet), in a future major release or the deprecation is forseeably indefinite, this is likewise very helpful, as it both helps explicitly document (for both users and contributors) that an exact removal version is not yet planned, without having to dig through old threads, ask people or get blindsided by an unexpected removal, and these individual distinctions are still important and can result in different appropriate choices as both a Python user and a contributors.

deprecated is also needed for cases such as #31891 (comment), where the SC wanted to leave out the removal version from docs (but not code warnings).

@hugovk @brettcannon I really don't understand the reason for providing the target removal version up front in the DeprecationWarning (which unfortunately many devs will never see, at least not in a timely manner), but hiding it in the actual documentation, unless users click the link and dig through the PEP?

As discussed above, many deprecated items have been deprecated for years or even a decade or more, and some even potentially indefinitely, the lack of a removal version does not convey any of the actual urgency of the imminent complete removal. Furthermore, I'd think it is much better to err on the side of caution, make the current planned removal date clear so users can respond to it with appropriate urgency, rather than encouraging complacency until it is too late to either address or revert it.

If the concern is the possibility it may be pushed back, the docs can be updated instantly, whereas it is much harder and slower to update released Python versions, if that is possible at all, and @brettcannon you yourself mentioned on the PEP 594 Discourse thread that the PEP is now considered a historical document. And as we saw with PEP 563 and others, clearly establishing an initial set date is a great catalyst for users and ecosystems testing the change and sharing any unanticipated impacts that might justify such a delay, before it is too late.