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

Expand "getting started" docs to discuss type hints in more detail #6226

Merged
merged 5 commits into from Feb 1, 2019

Commits on Jan 20, 2019

  1. Expand "getting started" docs to discuss type hints in more detail

    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.
    Michael0x2a committed Jan 20, 2019
    Copy the full SHA
    d835b30 View commit details
    Browse the repository at this point in the history
  2. Apply suggestions from code review

    Co-Authored-By: Michael0x2a <michael.lee.0x2a@gmail.com>
    bluetech and Michael0x2a committed Jan 20, 2019
    Copy the full SHA
    aecc4d2 View commit details
    Browse the repository at this point in the history
  3. Fix small typo

    Michael0x2a committed Jan 20, 2019
    Copy the full SHA
    02aac6f View commit details
    Browse the repository at this point in the history

Commits on Jan 22, 2019

  1. Respond to Ivan and Jukka's code reviews

    - Fix small suggestions made
    - Simplify the `*args` and `**kwargs` example (or rather, just give up
      on constructing an example altogether)
    - Sneak in an example of `Tuple[...]` when discussing `*args`
    - Discuss `Optional[...]` -- and also sneak in an example of mypy
      understanding `x is None` checks.
    Michael0x2a committed Jan 22, 2019
    Copy the full SHA
    4118201 View commit details
    Browse the repository at this point in the history

Commits on Feb 1, 2019

  1. Respond to code review

    Michael0x2a committed Feb 1, 2019
    Copy the full SHA
    142ddb3 View commit details
    Browse the repository at this point in the history