diff options
Diffstat (limited to 'Lib/typing.py')
| -rw-r--r-- | Lib/typing.py | 68 |
1 files changed, 43 insertions, 25 deletions
diff --git a/Lib/typing.py b/Lib/typing.py index dc61f0b1..b6c8d8a 100644 --- a/Lib/typing.py +++ b/Lib/typing.py @@ -1,9 +1,6 @@ """ The typing module: Support for gradual typing as defined by PEP 484 and subsequent PEPs. -Any name not present in __all__ is an implementation detail -that may be changed without notice. Use at your own risk! - Among other things, the module includes the following: * Generic, Protocol, and internal machinery to support generic aliases. All subscripted types like X[int], Union[int, str] are generic aliases. @@ -16,6 +13,9 @@ Among other things, the module includes the following: SupportsFloat, SupportsIndex, SupportsAbs, and others. * Special types: NewType, NamedTuple, TypedDict. * Deprecated aliases for builtin types and collections.abc ABCs. + +Any name not present in __all__ is an implementation detail +that may be changed without notice. Use at your own risk! """ from abc import abstractmethod, ABCMeta @@ -208,10 +208,12 @@ def _should_unflatten_callable_args(typ, args): """Internal helper for munging collections.abc.Callable's __args__. The canonical representation for a Callable's __args__ flattens the - argument types, see https://bugs.python.org/issue42195. For example:: + argument types, see https://github.com/python/cpython/issues/86361. - collections.abc.Callable[[int, int], str].__args__ == (int, int, str) - collections.abc.Callable[ParamSpec, str].__args__ == (ParamSpec, str) + For example:: + + assert collections.abc.Callable[[int, int], str].__args__ == (int, int, str) + assert collections.abc.Callable[ParamSpec, str].__args__ == (ParamSpec, str) As a result, if we need to reconstruct the Callable from its __args__, we need to unflatten it. @@ -345,8 +347,9 @@ _caches = {} def _tp_cache(func=None, /, *, typed=False): - """Internal wrapper caching __getitem__ of generic types with a fallback to - original function for non-hashable arguments. + """Internal wrapper caching __getitem__ of generic types. + + For non-hashable arguments, the original function is used as a fallback. """ def decorator(func): # The callback 'inner' references the newly created lru_cache @@ -627,10 +630,12 @@ def ClassVar(self, parameters): An annotation wrapped in ClassVar indicates that a given attribute is intended to be used as a class variable and - should not be set on instances of that class. Usage:: + should not be set on instances of that class. + + Usage:: class Starship: - stats: ClassVar[Dict[str, int]] = {} # class variable + stats: ClassVar[dict[str, int]] = {} # class variable damage: int = 10 # instance variable ClassVar accepts only types and cannot be further subscribed. @@ -763,7 +768,9 @@ def TypeAlias(self, parameters): Use TypeAlias to indicate that an assignment should be recognized as a proper type alias definition by type - checkers. For example:: + checkers. + + For example:: Predicate: TypeAlias = Callable[..., bool] @@ -776,8 +783,8 @@ def TypeAlias(self, parameters): def Concatenate(self, parameters): """Special form for annotating higher-order functions. - ``Concatenate`` can be sed in conjunction with ``ParamSpec`` and - ``Callable`` to represent a higher order function which adds, removes or + ``Concatenate`` can be used in conjunction with ``ParamSpec`` and + ``Callable`` to represent a higher-order function which adds, removes or transforms the parameters of a callable. For example:: @@ -1593,8 +1600,9 @@ def Unpack(self, parameters): """Type unpack operator. The type unpack operator takes the child types from some container type, - such as `tuple[int, str]` or a `TypeVarTuple`, and 'pulls them out'. For - example:: + such as `tuple[int, str]` or a `TypeVarTuple`, and 'pulls them out'. + + For example:: # For some generic class `Foo`: Foo[Unpack[tuple[int, str]]] # Equivalent to Foo[int, str] @@ -1619,7 +1627,7 @@ def Unpack(self, parameters): class Bar[*Ts]: ... The operator can also be used along with a `TypedDict` to annotate - `**kwargs` in a function signature. For instance:: + `**kwargs` in a function signature:: class Movie(TypedDict): name: str @@ -1632,7 +1640,7 @@ def Unpack(self, parameters): Note that there is only some runtime checking of this operator. Not everything the runtime allows may be accepted by static type checkers. - For more information, see PEP 646. + For more information, see PEPs 646 and 692. """ item = _type_check(parameters, f'{self} accepts only single type.') return _UnpackGenericAlias(origin=self, args=(item,)) @@ -1880,7 +1888,9 @@ class Protocol(Generic, metaclass=_ProtocolMeta): ... Such classes are primarily used with static type checkers that recognize - structural subtyping (static duck-typing), for example:: + structural subtyping (static duck-typing). + + For example:: class C: def meth(self) -> int: @@ -2037,7 +2047,7 @@ class Annotated: Annotated[*Ts, Ann1] # NOT valid - This would be equivalent to + This would be equivalent to:: Annotated[T1, T2, T3, ..., Ann1] @@ -2255,8 +2265,10 @@ def _strip_annotations(t): def get_origin(tp): """Get the unsubscripted version of a type. - This supports generic types, Callable, Tuple, Union, Literal, Final, ClassVar - Annotated, and others. Return None for unsupported types. Examples:: + This supports generic types, Callable, Tuple, Union, Literal, Final, ClassVar, + Annotated, and others. Return None for unsupported types. + + Examples:: assert get_origin(Literal[42]) is Literal assert get_origin(int) is None @@ -2415,7 +2427,9 @@ def overload(func): """Decorator for overloaded functions/methods. In a stub file, place two or more stub definitions for the same - function in a row, each decorated with @overload. For example:: + function in a row, each decorated with @overload. + + For example:: @overload def utf8(value: None) -> None: ... @@ -2426,7 +2440,7 @@ def overload(func): In a non-stub file (i.e. a regular .py file), do the same but follow it with an implementation. The implementation should *not* - be decorated with @overload. For example:: + be decorated with @overload:: @overload def utf8(value: None) -> None: ... @@ -2925,7 +2939,9 @@ TypedDict.__mro_entries__ = lambda bases: (_TypedDict,) def Required(self, parameters): """Special typing construct to mark a TypedDict key as required. - This is mainly useful for total=False TypedDicts. For example:: + This is mainly useful for total=False TypedDicts. + + For example:: class Movie(TypedDict, total=False): title: Required[str] @@ -2967,7 +2983,9 @@ class NewType: NewType(name, tp) is considered a subtype of tp by static type checkers. At runtime, NewType(name, tp) returns - a dummy callable that simply returns its argument. Usage:: + a dummy callable that simply returns its argument. + + Usage:: UserId = NewType('UserId', int) |