Skip to content

[3.12] gh-112194: Convert more examples to doctests in typing.py (GH-112195) #112208

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 17, 2023
Merged

[3.12] gh-112194: Convert more examples to doctests in typing.py (GH-112195) #112208

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 43 additions & 31 deletions Lib/typing.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,8 +218,12 @@ def _should_unflatten_callable_args(typ, args):

For example::

assert collections.abc.Callable[[int, int], str].__args__ == (int, int, str)
assert collections.abc.Callable[ParamSpec, str].__args__ == (ParamSpec, str)
>>> import collections.abc
>>> P = ParamSpec('P')
>>> collections.abc.Callable[[int, int], str].__args__ == (int, int, str)
True
>>> collections.abc.Callable[P, str].__args__ == (P, str)
True

As a result, if we need to reconstruct the Callable from its __args__,
we need to unflatten it.
Expand Down Expand Up @@ -261,7 +265,10 @@ def _collect_parameters(args):

For example::

assert _collect_parameters((T, Callable[P, T])) == (T, P)
>>> P = ParamSpec('P')
>>> T = TypeVar('T')
>>> _collect_parameters((T, Callable[P, T]))
(~T, ~P)
"""
parameters = []
for t in args:
Expand Down Expand Up @@ -2268,14 +2275,15 @@ def get_origin(tp):

Examples::

assert get_origin(Literal[42]) is Literal
assert get_origin(int) is None
assert get_origin(ClassVar[int]) is ClassVar
assert get_origin(Generic) is Generic
assert get_origin(Generic[T]) is Generic
assert get_origin(Union[T, int]) is Union
assert get_origin(List[Tuple[T, T]][int]) is list
assert get_origin(P.args) is P
>>> P = ParamSpec('P')
>>> assert get_origin(Literal[42]) is Literal
>>> assert get_origin(int) is None
>>> assert get_origin(ClassVar[int]) is ClassVar
>>> assert get_origin(Generic) is Generic
>>> assert get_origin(Generic[T]) is Generic
>>> assert get_origin(Union[T, int]) is Union
>>> assert get_origin(List[Tuple[T, T]][int]) is list
>>> assert get_origin(P.args) is P
"""
if isinstance(tp, _AnnotatedAlias):
return Annotated
Expand All @@ -2296,11 +2304,12 @@ def get_args(tp):

Examples::

assert get_args(Dict[str, int]) == (str, int)
assert get_args(int) == ()
assert get_args(Union[int, Union[T, int], str][int]) == (int, str)
assert get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int])
assert get_args(Callable[[], T][int]) == ([], int)
>>> T = TypeVar('T')
>>> assert get_args(Dict[str, int]) == (str, int)
>>> assert get_args(int) == ()
>>> assert get_args(Union[int, Union[T, int], str][int]) == (int, str)
>>> assert get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int])
>>> assert get_args(Callable[[], T][int]) == ([], int)
"""
if isinstance(tp, _AnnotatedAlias):
return (tp.__origin__,) + tp.__metadata__
Expand All @@ -2319,12 +2328,15 @@ def is_typeddict(tp):

For example::

class Film(TypedDict):
title: str
year: int

is_typeddict(Film) # => True
is_typeddict(Union[list, str]) # => False
>>> from typing import TypedDict
>>> class Film(TypedDict):
... title: str
... year: int
...
>>> is_typeddict(Film)
True
>>> is_typeddict(dict)
False
"""
return isinstance(tp, _TypedDictMeta)

Expand Down Expand Up @@ -2881,15 +2893,15 @@ def TypedDict(typename, fields=None, /, *, total=True, **kwargs):

Usage::

class Point2D(TypedDict):
x: int
y: int
label: str

a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK
b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check

assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
>>> class Point2D(TypedDict):
... x: int
... y: int
... label: str
...
>>> a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK
>>> b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check
>>> Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')
True

The type info can be accessed via the Point2D.__annotations__ dict, and
the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets.
Expand Down