Tutorial document

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.

issue 中没有指定 tutorial 文件、入口点或测试。首先定位现有的 tutorial 文档，并将其与提议的基础主题和高级主题列表进行比较。完成的标准是就 tutorial 的范围、Python 版本指导、包含的 typing 主题和排除项达成一致，然后记录这些决定。