Skip to content

gh-106745: typing docs: Clarify that removal of PEP-585 aliases is not currently planned #106748

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 14, 2023

Conversation

AlexWaygood
Copy link
Member

@AlexWaygood AlexWaygood commented Jul 14, 2023

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/

Copy link
Member

@Fidget-Spinner Fidget-Spinner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cool. Didn't know list-table existed!

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay!

(optparse and getopt (and likely several other modules) are 100% soft deprecated :)

Copy link
Member Author

@AlexWaygood AlexWaygood Jul 14, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(optparse and getopt (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.)

Copy link
Contributor

@hauntsaninja hauntsaninja left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this is an improvement!

@AlexWaygood AlexWaygood merged commit 89ec0e9 into python:main Jul 14, 2023
@miss-islington
Copy link
Contributor

Thanks @AlexWaygood for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

@AlexWaygood AlexWaygood deleted the clarify-585-depr branch July 14, 2023 18:49
@miss-islington
Copy link
Contributor

Sorry @AlexWaygood, I had trouble checking out the 3.12 backport branch.
Please retry by removing and re-adding the "needs backport to 3.12" label.
Alternatively, you can backport using cherry_picker on the command line.
cherry_picker 89ec0e952965b6a1be40e26c3ddc4131599e5ee9 3.12

@miss-islington
Copy link
Contributor

Sorry, @AlexWaygood, I could not cleanly backport this to 3.11 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 89ec0e952965b6a1be40e26c3ddc4131599e5ee9 3.11

@AlexWaygood AlexWaygood removed the needs backport to 3.12 only security fixes label Jul 14, 2023
@AlexWaygood AlexWaygood added the needs backport to 3.12 only security fixes label Jul 14, 2023
@miss-islington
Copy link
Contributor

Thanks @AlexWaygood for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

@miss-islington
Copy link
Contributor

Sorry @AlexWaygood, I had trouble checking out the 3.12 backport branch.
Please retry by removing and re-adding the "needs backport to 3.12" label.
Alternatively, you can backport using cherry_picker on the command line.
cherry_picker 89ec0e952965b6a1be40e26c3ddc4131599e5ee9 3.12

@AlexWaygood AlexWaygood added needs backport to 3.12 only security fixes and removed needs backport to 3.12 only security fixes labels Jul 14, 2023
@miss-islington
Copy link
Contributor

Thanks @AlexWaygood for the PR 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

@miss-islington
Copy link
Contributor

Sorry, @AlexWaygood, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 89ec0e952965b6a1be40e26c3ddc4131599e5ee9 3.12

AlexWaygood added a commit to AlexWaygood/cpython that referenced this pull request Jul 15, 2023
@bedevere-bot
Copy link

GH-106772 is a backport of this pull request to the 3.12 branch.

@bedevere-bot bedevere-bot removed the needs backport to 3.12 only security fixes label Jul 15, 2023
@bedevere-bot
Copy link

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

@bedevere-bot bedevere-bot removed the needs backport to 3.11 only security fixes label Jul 15, 2023
AlexWaygood added a commit that referenced this pull request Jul 15, 2023
AlexWaygood added a commit that referenced this pull request Jul 15, 2023
AlexWaygood added a commit to AlexWaygood/cpython that referenced this pull request Feb 22, 2024
…aliases is not currently planned (python#106748)

(cherry-picked from commit 89ec0e9)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants