[Python-checkins] gh-105286: Further improvements to `typing.py` docstrings (#105363)
JelleZijlstra
webhook-mailer at python.org
Tue Jun 6 20:21:23 EDT 2023
https://github.com/python/cpython/commit/9a89f1bf1e7bb819fe7240be779c99a84f47ea46
commit: 9a89f1bf1e7bb819fe7240be779c99a84f47ea46
branch: main
author: Alex Waygood <Alex.Waygood at Gmail.com>
committer: JelleZijlstra <jelle.zijlstra at gmail.com>
date: 2023-06-06T17:21:16-07:00
summary:
gh-105286: Further improvements to `typing.py` docstrings (#105363)
files:
M Lib/typing.py
diff --git a/Lib/typing.py b/Lib/typing.py
index dc61f0b1201c..b6c8d8a4febd 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 @@
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 @@ 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
@@ -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 @@ 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
@@ -1632,7 +1640,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,))
@@ -1880,7 +1888,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:
@@ -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 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: ...
@@ -2925,7 +2939,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]
@@ -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)
More information about the Python-checkins
mailing list