Document type inference behavior in case type declaration has (not) initializer

[JukkaL]

In cases like this mypy doesn't narrow down the type in assignment:

x: Union[int, str] = 0
# type of x is Union[int, str] here!

Any assignment after the initial declaration will narrow the type down:

x: Union[int, str]
x = 0
# type of x is int here!

Document this behavior since it can be surprising. The motivation for this is that this behavior makes it easy to override the inferred type for a variable, which is sometimes useful.

[ilevkivskyi]

Related #2008

[tz-earl]

Beginner contributor here. I'd like to add the above explanation by JukkaL to the docs.

Would Common Issues and Solutions be an appropriate place?

[gvanrossum]

@tz-earl I'm sorry we dropped your question. This is a very busy project, with an all volunteer crew! I think the right place to document this would be a new section in Type inference and type annotations, perhaps right after Explicit types for variables.