Skip to content

Commit 9ffb7ca

Browse files
authored
Expand "getting started" docs to discuss type hints in more detail (#6226)
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.
1 parent b1c8e66 commit 9ffb7ca

File tree

4 files changed

+253
-71
lines changed

4 files changed

+253
-71
lines changed

docs/source/command_line.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -336,7 +336,7 @@ potentially problematic or redundant in some way.
336336
a ``# type: ignore`` comment on a line that is not actually
337337
generating an error message.
338338

339-
This flag, along with the ``--warn-unsued-casts`` flag, are both
339+
This flag, along with the ``--warn-unused-casts`` flag, are both
340340
particularly useful when you are upgrading mypy. Previously,
341341
you may have needed to add casts or ``# type: ignore`` annotations
342342
to work around bugs in mypy or missing stubs for 3rd party libraries.

0 commit comments

Comments
 (0)