PEP 585: Type Hinting Generics In Standard Collections
list[str]
Read in the browser: https://www.python.org/dev/peps/pep-0585/ https://www.python.org/dev/peps/pep-0585/
Read the source: https://raw.githubusercontent.com/python/peps/master/pep-0585.rst https://raw.githubusercontent.com/python/peps/master/pep-0585.rst
The following PEP has been discussed on typing-sig already and a prototype implementation exists for it. I'm extending it now for wider feedback on python-dev, with the intent to present the final version for the Steering Council's consideration by mid-March.
PEP: 585
Title: Type Hinting Generics In Standard Collections
Author: Łukasz Langa
tuple[int, ...] tuple[int, ...] ChainMap[str, list[str]]
collections.ChainMap[str, list[str]] This is implemented using a thin proxy type that forwards all method calls and attribute accesses to the bare origin type with the following exceptions:
the __repr__ shows the parametrized type; the __origin__ attribute points at the non-parametrized generic class; the __args__ attribute is a tuple (possibly of length 1) of generic types passed to the original __class_getitem__; the __parameters__ attribute is a lazily computed tuple (possibly empty) of unique type variables found in __args__; the __getitem__ raises an exception to disallow mistakes like dict[str][str]. However it allows e.g. dict[str, T][int] and in that case returns dict[str, int]. This design means that it is possible to create instances of parametrized collections, like:
l = list[str]() [] list is list[str] False list == list[str] False list[str] == list[str] True list[str] == list[int] False isinstance([1, 2, 3], list[str]) TypeError: isinstance() arg 2 cannot be a parametrized generic issubclass(list, list[str]) TypeError: issubclass() arg 2 cannot be a parametrized generic isinstance(list[str], types.GenericAlias) True Objects created with bare types and parametrized types are exactly the same. The generic parameters are not preserved in instances created with parametrized types, in other words generic types erase type parameters during object creation.
One important consequence of this is that the interpreter does not attempt to type check operations on the collection created with a parametrized type. This provides symmetry between: l: list[str] = [] and: l = list[str]() For accessing the proxy type from Python code, it will be exported from the types module as GenericAlias. Pickling or (shallow- or deep-) copying a GenericAlias instance will preserve the type, origin, attributes and parameters. Forward compatibility Future standard collections must implement the same behavior. Reference implementation A proof-of-concept or prototype implementation https://bugs.python.org/issue39481 exists. Rejected alternatives Do nothing Keeping the status quo forces Python programmers to perform book-keeping of imports from the typing module for standard collections, making all but the simplest annotations cumbersome to maintain. The existence of parallel types is confusing to newcomers (why is there both list and List?). The above problems also don't exist in user-built generic classes which share runtime functionality and the ability to use them as generic type annotations. Making standard collections harder to use in type hinting from user classes hindered typing adoption and usability. Generics erasure It would be easier to implement __class_getitem__ on the listed standard collections in a way that doesn't preserve the generic type, in other words:
list[str]
tuple[int, ...] collections.ChainMap[str, list[str]] This is problematic as it breaks backwards compatibility: current equivalents of those types in the typing module do preserve the generic type:
from typing import List, Tuple, ChainMap List[str] typing.List[str] Tuple[int, ...] typing.Tuple[int, ...] ChainMap[str, List[str]] typing.ChainMap[str, typing.List[str]] As mentioned in the "Implementation" section, preserving the generic type at runtime enables runtime introspection of the type which can be used for API generation or runtime type checking. Such usage is already present in the wild.
Additionally, implementing subscripts as identity functions would make Python less friendly to beginners. Say, if a user is mistakenly passing a list type instead of a list object to a function, and that function is indexing the received object, the code would no longer raise an error. Today:
l = list l[-1] TypeError: 'type' object is not subscriptable With __class_getitem__ as an identity function:
l = list l[-1] list The indexing being successful here would likely end up raising an exception at a distance, confusing the user.
Disallowing instantiation of parametrized types Given that the proxy type which preserves __origin__ and __args__ is mostly useful for runtime introspection purposes, we might have disallowed instantiation of parametrized types. In fact, forbidding instantiation of parametrized types is what the typing module does today for types which parallel builtin collections (instantiation of other parametrized types is allowed). The original reason for this decision was to discourage spurious parametrization which made object creation up to two orders of magnitude slower compared to the special syntax available for those builtin collections. This rationale is not strong enough to allow the exceptional treatment of builtins. All other parametrized types can be instantiated, including parallels of collections in the standard library. Moreover, Python allows for instantiation of lists using list() and some builtin collections don't provide special syntax for instantiation. Making isinstance(obj, list[str]) perform a check ignoring generics An earlier version of this PEP suggested treating parametrized generics like list[str] as equivalent to their non-parametrized variants like list for purposes of isinstance() and issubclass(). This would be symmetrical to how list[str]() creates a regular list. This design was rejected because isinstance() and issubclass() checks with parametrized generics would read like element-by-element runtime type checks. The result of those checks would be surprising, for example:
isinstance([1, 2, 3], list[str]) True Note the object doesn't match the provided generic type but isinstance() still returns True because it only checks whether the object is a list.
If a library is faced with a parametrized generic and would like to perform an isinstance() check using the base type, that type can be retrieved using the __origin__ attribute on the parametrized generic. Making isinstance(obj, list[str]) perform a runtime type check This functionality requires iterating over the collection which is a destructive operation in some of them. This functionality would have been useful, however implementing the type checker within Python that would deal with complex types, nested type checking, type variables, string forward references, and so on is out of scope for this PEP. Note on the initial draft An early version of this PEP discussed matters beyond generics in standard collections. Those unrelated topics were removed for clarity. Copyright This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.
participants (7)
-
Batuhan Taskaya
-
Ethan Smith
-
Guido van Rossum
-
Jonathan Goble
-
Nick Coghlan
-
Stephen J. Turnbull
-
Łukasz Langa