1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
|
from __future__ import annotations
from typing import (
Annotated,
Generator,
Iterator,
NotRequired,
TypedDict,
Unpack,
Doc,
)
# Documenting module/class attributes, replacing Attributes sections:
ATTRIBUTE: Annotated[
str,
Doc(
"""Showing off attributes.
Supporting multiple lines.
"""
)
]
# Documenting parameters, replacing Parameters sections:
def parameters(param1: Annotated[str, Doc("Description of param1.")] = "default"):
"""Showing off parameters."""
# Documenting other parameters (keyword arguments), replacing Other Parameters sections:
class OtherParameters(TypedDict, total=False):
"""Keyword arguments of [`simple.other_parameters`][]."""
param1: Annotated[NotRequired[str], Doc("Description of param1.")]
param2: Annotated[NotRequired[str], Doc("Description of param2.")]
def other_parameters(
**kwargs: Annotated[Unpack[OtherParameters], Doc("See other parameters.")], # noqa: ARG001
) -> None:
"""Showing off other parameters."""
# Documenting returned values, replacing Returns sections:
def return_value() -> Annotated[int, Doc("Returned integer.")]:
"""Showing off return values."""
return 0
# Documenting yielded and received values, replacing Yields and Receives sections:
def generator() -> Generator[
Annotated[int, Doc("Yielded integers.")],
Annotated[int, Doc("Received integers.")],
Annotated[int, Doc("Final returned value.")],
]:
"""Showing off generators."""
# Same thing with Iterator instead of Generator:
def iterator() -> Iterator[Annotated[int, Doc("Yielded integers.")]]:
"""Showing off iterators."""
# Advanced use-case: documenting multiple yielded/received/returned values:
def return_tuple() -> Generator[
tuple[
Annotated[int, Doc("First element of the yielded value.")],
Annotated[float, Doc("Second element of the yielded value.")],
],
tuple[
Annotated[int, Doc("First element of the received value.")],
Annotated[float, Doc("Second element of the received value.")],
],
tuple[
Annotated[int, Doc("First element of the returned value.")],
Annotated[float, Doc("Second element of the returned value.")],
],
]:
"""Showing off tuples as yield/receive/return values."""
|
