From 84133c56f334dca2a1d9fe640fdbafc584d44839 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Tue, 6 Jun 2023 17:51:16 -0700 Subject: [PATCH] [3.12] gh-105286: Further improvements to `typing.py` docstrings (GH-105363) (#105416) gh-105286: Further improvements to `typing.py` docstrings (GH-105363) (cherry picked from commit 9a89f1bf1e7bb819fe7240be779c99a84f47ea46) Co-authored-by: Alex Waygood --- Lib/typing.py | 68 ++++++++++++++++++++++++++++++++------------------- 1 file changed, 43 insertions(+), 25 deletions(-) diff --git a/Lib/typing.py b/Lib/typing.py index f9a8ea601e793e..3dda940b07accb 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. @@ -17,6 +14,9 @@ * Special types: NewType, NamedTuple, TypedDict. * Deprecated wrapper submodules for re and io related types. * 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 @@ -214,10 +214,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. @@ -351,8 +353,9 @@ def _flatten_literal_params(parameters): 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 @@ -633,10 +636,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. @@ -769,7 +774,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] @@ -782,8 +789,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:: @@ -1599,8 +1606,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] @@ -1625,7 +1633,7 @@ class Bar(Generic[*Ts]): ... 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 @@ -1638,7 +1646,7 @@ def foo(**kwargs: Unpack[Movie]): ... 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,)) @@ -1886,7 +1894,9 @@ def meth(self) -> int: ... 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: @@ -2043,7 +2053,7 @@ class Annotated: Annotated[*Ts, Ann1] # NOT valid - This would be equivalent to + This would be equivalent to:: Annotated[T1, T2, T3, ..., Ann1] @@ -2261,8 +2271,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 @@ -2421,7 +2433,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: ... @@ -2432,7 +2446,7 @@ def utf8(value: str) -> bytes: ... 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: ... @@ -2942,7 +2956,9 @@ class Point2D(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] @@ -2984,7 +3000,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)