Tutorial document

[srittau]

Thoughts on the tutorial document.

Basic Topics

• Set up a basic venv with a pinned mypy version. (For compatibility reasons.) Should add a note about using a current version in production.
• Annotating variables.
• Annotating functions and methods.
• Unions, using | None
• Any
• cast() and # type: ignore
• Using generics, variance
• Built-in collections
• Type aliases
• int/float
• NoReturn (not strictly necessary, but a fairly easy topic)
• Installing third-party stubs

Advanced Topics

The are fairly complicated topics, but basically required when typing a non-trivial code base:

• Callable
• Writing generics
• Protocols
• type[...]
• typing.TYPE_CHECKING and circular imports
• TypeVar and AnyStr
• overloads
• Literal

What not to include

• # type annotations (except # type: ignore)

The following topics could arguably be included, but for simplicity's sake, I'd suggest to skip them in this basic tutorial:

• NewType
• ClassVar
• Final
• Annotated
• NamedTuple
• TypedDict

Other Thoughts

• We can use a newer version of Python (e.g. 3.8+) for simplicity and add a note that not all features are available in older Python versions.
• We should probably just use from __future__ import annotations and skip the whole forward references/quoting types problem.

[hmc-cs-mdrissi]

from __future__ import annotations covers a lot of quoting type situations, but does miss a common one for when you define type alias. Example code,

from __future__ import annotations
FlagList = List["str | bool"]

Quotes being required there in 3.8. Other thing is even though most of the time you don't need it quotes, it's a very reasonable question to ask why that works as it seems fairly weird for not yet defined class to be usable. I'd lean towards either leave import annotation to advanced section or explain what it does instead of hand wave it away.

Otherwise the topic list seems reasonable to me. Only advanced topic I find fairly common is Literal to handle boolean overloads or to restrict input for a string parameter. While a string enum could be used for the latter case, a lot of libraries end up just using strings directly over enums. I'd lean towards having advanced topics be a separate page though, so people start off with basic section and then read advanced sections later as needed. I'm supportive of leaving literal out of the basic section. One topic I'm unsure where included is variance. Do you want that covered with generics? The main weirdness for a beginner is List/Dict invariance, but it's also a topic needed to explain how to use List properly. Other small topic int/float relationship and writing your own stub files. Making your own stub files can fall in advanced but useful especially if you want stubs for some library you don't develop yourself.

Is | None expected to replace Optional style wise?

[srittau]

@hmc-cs-mdrissi That's a good point about type aliases and quotes. A brief explanation of the future import makes sense. I think that this explanations (as well as explanation about using newer Python versions etc.) are a perfect fit for call out boxes.

I flip-flopped on literals, but you are right, it's useful enough to include it. I also added "variance" to the generics topic to make clear that it needs to be discussed. Good point about int/float, I included it.

I also agree that it could make sense to split the basic and advanced tutorials. We could also add a third tutorial for the "expert" stuff that's in the "What not to include" section. Writing your own stub files should be a separate tutorial (see #845).

The typeshed style guide recommends to use | over Union and Optional (where possible). I'd expect us to recommend it for typing in general if we ever write a general style guide.