Proposed initial typing spec

Typing
6

Thanks for the initial cut at this spec, Jelle. This is great progress!

I agree with many of the other comments already posted. The current draft reads as though it’s a bunch of documents pasted together — because that’s what it is :slight_smile: .

I think that the order of the topics will need to change and the sections will need to become more fine-grained over time. We could either attempt to do that upfront or do it as a second pass. My (slight) preference is to do it upfront, but I’m OK with either approach. I’ve taken a stab at a finer-grained organizational structure, which I’ve included below. I’ve attempted to order the sections such that they build on each other. My proposed organization includes some bullet items and sections that are not currently covered in any PEP but should probably be added over time to make the typing spec complete. We could leave these as placeholders in the initial draft if we adopt my proposal.

I think we should break it into multiple documents, It’s already unwieldy, and I think it’s going to grow (perhaps significantly) over time as we add clarifications and document new typing features. My thought is that each section (chapter?) should be a separate document. This will make it easier to use as a reference. It will also facilitate PR reviews as the spec is updated. We could solve the searchability problem by adding a simple search mechanism on the documentation website. Links will also facilitate navigation between sections.

Here’s my proposed organization:

The Python Type System

  • What is a type system?
  • Static (vs runtime) type checking
  • Goals & non-goals
  • Purpose and organization of this spec
  • Definition of terms

Type System Concepts

  • Type declarations
  • Type evaluation & inference
  • Subtype relationships
  • Unions
  • Gradual typing
  • Nominal vs. structural typing

Type Annotations

  • Meaning of annotations
  • Valid type expression forms
  • Forward references
  • Scoping of annotations
  • Runtime evaluation of annotations
  • Function & variable annotations
  • Generator functions and awaitables

Special Types in Annotations

  • Any
  • None
  • Callable
  • tuple
  • float and complex (special-case type promotions)
  • NoReturn & Never

Metaclasses

  • Class objects vs. class instances
  • Metaclass hierarchy and type

Generics

  • Type parameters
  • Type parameter scoping
  • Generic class definitions
  • Generic function definitions
  • Specialization
  • Constraint solving
  • Variance
  • TypeVar
  • Upper bounds
  • Constrained TypeVars
  • ParamSpec & Concatenate
  • TypeVarTuple & Unpack
  • Self
  • Variance inference

Type Qualifiers

  • final
  • Final
  • Annotated

Class Type Compatibility

  • Liskov substitution principle & LSP exemptions
  • Override checks
  • Abstract classes & methods
  • Multiple inheritance
  • Class-scoped variables & ClassVar
  • override

Type Aliases

  • Runtime evaluation of type aliases
  • TypeAlias
  • type statements
  • Generic type aliases
  • Recursive type aliases
  • NewType

Literals

  • Literal expressions
  • Literal
  • LiteralString

Protocols

  • Overview of protocols & Protocol
  • Default implementations in protocols
  • Protocol matching for classes, types, and modules

Callables

  • Positional-only parameters
  • Keyword-only parameters
  • Argument defaults
  • Annotating *args and **kwargs
  • Callable
  • Callback protocols
  • TypeVarTuple and *args
  • Callable subtyping rules

Overloads

  • overload
  • Overload matching for calls

Methods

  • Instance, class, and static methods
  • Binding a class or type to a method
  • Class constructors

Descriptors

  • Descriptors
  • Properties
  • Asymmetric descriptors

Dataclasses

  • dataclass and type checking
  • dataclass_transform

Typed Dictionaries

  • TypedDict and type checking
  • Required and NotRequired

Enum

  • Enum and type checking

NamedTuple

  • NamedTuple and type checking

Type Narrowing

  • Narrowing on assignment
  • Narrowing rules for Any
  • Built-in type guards
  • TypeGuard

Type Checker Directives

  • assert_type
  • reveal_type
  • # type: ignore comments
  • cast
  • TYPE_CHECKING
  • no_type_check
  • type_check_only
  • deprecated

Distributing Type Information

  • Stub files
  • Type information in libraries
  • Import Resolution Ordering

Historical & Deprecated Features

  • Capitalized forms of builtins exported form typing module
  • typing_extensions module
  • Optional
  • Union
  • Type comments
13 Likes