This pull request expands our "getting started" docs so they discuss how
to use type hints in more detail.
In general, I'm hoping this pull request will accomplish two main
things:
1. Give users a better "tour" of the available PEP 484 types.
2. Do a better job of giving users a "heads-up" of common gotchas:
for example, how dynamically typed functions aren't type-checked.
Here's a list of specific changes I made:
1. I combined "Installing mypy" and "Running mypy" into one section.
2. I modified the "Function signatures" section to focus more on the
distinction between dynamic and static typing: I suspect that's
a common tripup new users run into.
I also changed the examples so they'll actually produce a runtime
error if you misuse them.
3. I moved the existing text on annotating no-argument functions or
functions with default arguments into a separate "More function
signatures" to try and keep the new "Function signatures and and
dynamic vs static typing" section focused.
4. I expanded the section about using the "typing" module to be more
thorough. In particular, I wanted to expose the user to the concept
of concrete generic types (List), abstract generic types/protocols
(Iterable), and to more non-conventional types like Union.
I think these three examples are broadly representative of the
different "flavors" of PEP 484 types and so should help new users
be a little more aware of the kinds of things they can do with types.
The main thing that's missing is an introduction to custom generic
classes and functions: that's probably too complex of a topic to
belong in this page.
5. I added a section on local type inference: it's a new concept for
people who are more used to languages like Java or C# so felt like
it was worth mentioning.
This section also covers the final stumbling block I think new users
are likely to run into: the "Need type annotation for 'variable'"
error message.
6. I added a section on customizing mypy via the command line flags.
I don't think enough users are aware that you can do this, despite
how useful the flags can be.