gh-106745: typing docs: Clarify that removal of PEP-585 aliases is not currently planned #106748
Conversation
… is not currently planned
| If at some point it is decided to remove these deprecated aliases, a | ||
| deprecation warning will be issued by the interpreter for at least two releases | ||
| prior to removal. The aliases are guaranteed to remain in the typing module | ||
| without deprecation warnings until at least Python 3.14. |
There was a problem hiding this comment.
Aha, so these are "soft deprecated".
https://peps.python.org/pep-0387/#soft-deprecation
It's a new term added in python/peps#3182.
Would referencing that help add clarity?
There was a problem hiding this comment.
I'm honestly not sure it would add clarity, to be honest :/ I feel like it might be just another cross-reference that people would have to look up if they're reading the docs.
I'm not aware of another module that has a similar situation where so much of the module is soft-deprecated. (In Python 3.13, 42 out of 101 items in typing.__all__ are soft-deprecated!) So I think I'd rather keep a verbose description in the typing docs of how we'll be specifically handling the typing deprecations, and treat them as their own unique thing, without reference to the broader concept of "soft deprecation"
There was a problem hiding this comment.
Okay!
(optparse and getopt (and likely several other modules) are 100% soft deprecated :)
There was a problem hiding this comment.
(
optparseandgetopt(and likely several other modules) are 100% soft deprecated :)
True!
(I still think I'd rather keep the explanation of what these deprecations mean inside the typing docs, though, rather than linking to the broader concept of soft deprecations. It's pretty important information for a lot of people who'll be visiting the docs.)
|
Thanks @AlexWaygood for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12. |
|
Sorry @AlexWaygood, I had trouble checking out the |
|
Sorry, @AlexWaygood, I could not cleanly backport this to |
|
Thanks @AlexWaygood for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12. |
|
Sorry @AlexWaygood, I had trouble checking out the |
|
Thanks @AlexWaygood for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12. |
|
Sorry, @AlexWaygood, I could not cleanly backport this to |
…aliases is not currently planned (python#106748)
|
GH-106772 is a backport of this pull request to the 3.12 branch. |
|
GH-106773 is a backport of this pull request to the 3.11 branch. |
…aliases is not currently planned (python#106748) (cherry-picked from commit 89ec0e9)
And convert the big deprecations table at the bottom into a list-table, so that it's more maintainable and extensible (it renders the same way).
📚 Documentation preview 📚: https://cpython-previews--106748.org.readthedocs.build/