[3.10] bpo-46104: Reduce use of pre-PEP 526 syntax in typing docs (GH-30148)

[miss-islington]

Co-authored-by: Andrew Svetlov [email protected]
(cherry picked from commit 6ada013)

Co-authored-by: Alex Waygood [email protected]

https://bugs.python.org/issue46104

Automerge-Triggered-By: GH:Fidget-Spinner

[miss-islington]

@AlexWaygood and @Fidget-Spinner: Status check is done, and it's a success ✅ .

[gvanrossum]

Why not ‘s: str = “”’? That’s what the original meant and some checkers allow overriding inferred types.

[AlexWaygood]

That's what I originally had, but @sobolevn convinced me to change it (and after he pointed it out, I decided I agreed with him 🙂) #30148 (comment)

[gvanrossum]

Sorry, I disagree. The example is intended to show how Any works, not an example of best style. And there are plenty of reasons to redundantly type a variable.

[AlexWaygood]

Sorry, I disagree. The example is intended to show how Any works, not an example of best style. And there are plenty of reasons to redundantly type a variable.

Yeah, I see your point! What if we changed the example to separate the type declaration from the assignment? Then we don't look like we're redundantly typing the variable, but we also assert the type, rather than having it simply inferred.

s: str
s = 2  # Error!
s = '' # OK
s = a  # OK

Cc. @Fidget-Spinner, @sobolevn

[gvanrossum]

Sorry, I disagree. The example is intended to show how Any works, not an example of best style. And there are plenty of reasons to redundantly type a variable.

Yeah, I see your point! What if we changed the example to separate the type declaration from the assignment? Then we don't look like we're redundantly typing the variable, but we also assert the type, rather than having it simply inferred.

s: str
s = 2  # Error!
s = '' # OK
s = a  # OK

Cc. @Fidget-Spinner, @sobolevn

I believe there's a feature request that would allow

s = ""
s = 0

and Pyright already implements it. But

s: str = ""
s = 0

is still an error. So these are not 100% equivalent. Please just use s: str = "".

[sobolevn]

Maybe we can leave a note that initializing variables do not require adding explicit annotations in most of the cases? Because this is a problem I see way too often.

Is it a proper place for this?

[gvanrossum]

Maybe we can leave a note that initializing variables do not require adding explicit annotations in most of the cases? Because this is a problem I see way too often.

Is it a proper place for this?

Not in this section (which is about Any). And hence not in this PR (nor in the PR that fixes this example).

And many people actually like explicit annotations. If the initializer is not a literal (but e.g. a function call) it's often helpful to the reader who is new to the code.

I do think it's fine to add a section (if there isn't already one) about type inference. But it can't get too specific since this is an area where type checkers vary.

[Fidget-Spinner]

Hmm, I'm leaning slightly more towards Guido's argument here. If a section is dedicated to one thing, my opinion is to dedicate the example to just teaching that one thing.

Besides, there are many examples of less-than-best practices in other typing examples. E.g. the whatsnew in 3.10 Union docs give int | float as an example, but that's possibly redundant, because PEP 484 says

when an argument is annotated as having type float, an argument of type int is acceptable;

but it's used because it's simple to understand.

[AlexWaygood]

Hmm, I'm leaning slightly more towards Guido's argument here. If a section is dedicated to one thing, my opinion is to dedicate the example to just teaching that one thing.

Besides, there are many examples of less-than-best practices in other typing examples. E.g. the whatsnew in 3.10 Union docs give int | float as an example, but that's possibly redundant, because PEP 484 says

when an argument is annotated as having type float, an argument of type int is acceptable;

but it's used because it's simple to understand.

OK, happy to go with the consensus 🙂 PR to fix it is here: #30203