Skip to content
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

Document "the Any trick" #11117

Merged
merged 11 commits into from
Dec 18, 2023
Merged

Document "the Any trick" #11117

merged 11 commits into from
Dec 18, 2023

Conversation

Avasam
Copy link
Collaborator

@Avasam Avasam commented Dec 7, 2023

Addresses the documentation part of #11094 .

Copied almost directly from #7770 (comment) just to get the ball rolling.
Wordsmith away! I don't feel strongly about any particular description, as long as it ends up documented and explained!

I'm not including an alias here because getting "the Any trick" documented at all is the most important part we all agreed on. I also noticed that it's not always clear why an Any union is used. So an alias for those cases should definitely help, but will require some thinking over changes. When creating the alias, it can immediately be used in stdlib as well. And a small mention can be added to the this here documentation. Something like:

### "The `Any` trick" and `MaybeNone`
...

To help with semantics and avoid confusion, we defined an alias `MaybeNone` to be used in the same way. Indicating that the developper can be ready to deal with a potentially `None` value, and let type-checkers know that type-guarding on `None` is not redundant.

@AlexWaygood
Copy link
Member

+1 for adding docs first — it doesn't preclude adding an alias at a later date, and it's easier to get consensus on!

Copy link
Collaborator

@Akuli Akuli left a comment

Choose a reason for hiding this comment

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

A pile of small nits that should make this easier to understand.

CONTRIBUTING.md Outdated Show resolved Hide resolved
CONTRIBUTING.md Outdated Show resolved Hide resolved
CONTRIBUTING.md Outdated Show resolved Hide resolved
CONTRIBUTING.md Outdated Show resolved Hide resolved
CONTRIBUTING.md Outdated Show resolved Hide resolved
Copy link
Collaborator

@Akuli Akuli left a comment

Choose a reason for hiding this comment

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

This is pretty good. A few more nits.

CONTRIBUTING.md Outdated Show resolved Hide resolved
CONTRIBUTING.md Show resolved Hide resolved
CONTRIBUTING.md Outdated Show resolved Hide resolved
CONTRIBUTING.md Outdated Show resolved Hide resolved
CONTRIBUTING.md Show resolved Hide resolved
Copy link
Collaborator

@Akuli Akuli left a comment

Choose a reason for hiding this comment

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

Looks good to me, but another review would be good IMO.

@srittau srittau merged commit 9d8188c into python:main Dec 18, 2023
1 check passed
@Avasam Avasam deleted the Document-the-Any-trick branch December 18, 2023 15:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants