From 07a6713a4cc0dfda1fd2a3d33b7b64b1b4148069 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Wed, 7 Jun 2023 01:21:16 +0100 Subject: [PATCH 1/2] [3.11] gh-105286: Further improvements to `typing.py` docstrings (GH-105363). (cherry picked from commit 9a89f1bf1e7bb819fe7240be779c99a84f47ea46) Co-authored-by: Alex Waygood --- Lib/typing.py | 66 ++++++++++++++++++++++++++++++++------------------- 1 file changed, 42 insertions(+), 24 deletions(-) diff --git a/Lib/typing.py b/Lib/typing.py index e6ef344ef43a2b..ab31fd1a0974d9 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 @@ -207,10 +207,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. @@ -339,8 +341,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): cached = functools.lru_cache(typed=typed)(func) @@ -614,10 +617,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. @@ -741,7 +746,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] @@ -754,8 +761,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:: @@ -1713,8 +1720,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] @@ -1736,7 +1744,7 @@ class Bar(Generic[*Ts]): ... 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,)) @@ -2007,7 +2015,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: @@ -2184,7 +2194,7 @@ class Annotated: Annotated[*Ts, Ann1] # NOT valid - This would be equivalent to + This would be equivalent to:: Annotated[T1, T2, T3, ..., Ann1] @@ -2402,8 +2412,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 @@ -2562,7 +2574,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: ... @@ -2573,7 +2587,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: ... @@ -3073,7 +3087,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] @@ -3115,7 +3131,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) From 1c0fdc8e16c1b4aacca0e8b6e61dc336c6a0e697 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Wed, 7 Jun 2023 06:08:21 -0700 Subject: [PATCH 2/2] Update Lib/typing.py Co-authored-by: Alex Waygood --- Lib/typing.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Lib/typing.py b/Lib/typing.py index ab31fd1a0974d9..419d53463edbfa 100644 --- a/Lib/typing.py +++ b/Lib/typing.py @@ -1744,7 +1744,7 @@ class Bar(Generic[*Ts]): ... 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 PEPs 646 and 692. + For more information, see PEP 646. """ item = _type_check(parameters, f'{self} accepts only single type.') return _UnpackGenericAlias(origin=self, args=(item,))