Examples¤
Simple¤
simple
Python module
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."""
simple ¤
Classes:
-
OtherParameters
–Keyword arguments of
simple.other_parameters
.
Functions:
-
generator
–Showing off generators.
-
iterator
–Showing off iterators.
-
other_parameters
–Showing off other parameters.
-
parameters
–Showing off parameters.
-
return_tuple
–Showing off tuples as yield/receive/return values.
-
return_value
–Showing off return values.
Attributes:
-
ATTRIBUTE
(Annotated[str, Doc('Showing off attributes.\n\n Supporting multiple lines.\n ')]
) –Showing off attributes.
ATTRIBUTE module-attribute
¤
Showing off attributes.
Supporting multiple lines.
OtherParameters ¤
Bases: TypedDict
Keyword arguments of simple.other_parameters
.
Attributes:
-
param1
(Annotated[NotRequired[str], Doc('Description of param1.')]
) –Description of param1.
-
param2
(Annotated[NotRequired[str], Doc('Description of param2.')]
) –Description of param2.
param1 instance-attribute
¤
param1: Annotated[
NotRequired[str], Doc("Description of param1.")
]
Description of param1.
param2 instance-attribute
¤
param2: Annotated[
NotRequired[str], Doc("Description of param2.")
]
Description of param2.
generator ¤
generator() -> Generator[
Annotated[int, Doc("Yielded integers.")],
Annotated[int, Doc("Received integers.")],
Annotated[int, Doc("Final returned value.")],
]
Showing off generators.
Yields:
Receives:
Returns:
Source code in docs/examples/simple.py
50 51 52 53 54 55 |
|
iterator ¤
other_parameters ¤
other_parameters(
**kwargs: Annotated[
Unpack[OtherParameters],
Doc("See other parameters."),
],
) -> None
Showing off other parameters.
Parameters:
-
**kwargs
(Annotated[Unpack[OtherParameters], Doc('See other parameters.')]
, default:{}
) –See other parameters.
Other Parameters:
-
param1
(Annotated[NotRequired[str], Doc('Description of param1.')]
) –Description of param1.
-
param2
(Annotated[NotRequired[str], Doc('Description of param2.')]
) –Description of param2.
Source code in docs/examples/simple.py
37 38 39 40 |
|
parameters ¤
return_tuple ¤
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.
Yields:
-
Annotated[int, Doc('First element of the yielded value.')]
–First element of the yielded value.
-
Annotated[float, Doc('Second element of the yielded value.')]
–Second element of the yielded value.
Receives:
-
Annotated[int, Doc('First element of the received value.')]
–First element of the received value.
-
Annotated[float, Doc('Second element of the received value.')]
–Second element of the received value.
Returns:
-
Annotated[int, Doc('First element of the returned value.')]
–First element of the returned value.
-
Annotated[float, Doc('Second element of the returned value.')]
–Second element of the returned value.
Source code in docs/examples/simple.py
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 |
|
return_value ¤
Enhanced¤
Non-standard features
The "enhanced" features are not part of PEP 727. They just serve as an example to show what would be possible if the PEP was enhanced to account for more use-cases.
enhanced
Python module
# This gist shows how we could get rid of docstrings micro-syntax
# like Google-style and Numpydoc-style pseudo-standards,
# using an enhanced version of PEP 727.
# The goal is to replace the following sections:
# deprecated
# Parameters
# Other Parameters
# Raises
# Warns
# Yields
# Receives
# Returns
from __future__ import annotations
from typing import (
Annotated,
Generator,
deprecated,
Doc,
Name,
Raises,
Warns,
)
# Documenting deprecations, replacing Deprecated sections:
DEPRECATED: Annotated[
int,
deprecated(
"""Deprecated since v2.
Please stop using this deprecated attribute, thanks!
"""
),
Doc("Showing off deprecated attributes."),
]
# For functions, maybe add the information to the return value annotation:
def deprecated1() -> Annotated[None, deprecated("Deprecated since v2.")]:
"""Showing off deprecated functions."""
# For parameters:
def deprecated2(param1: Annotated[int, deprecated("Deprecated since v2."), Doc("Description of param1.")] = 0):
"""Showing off deprecated parameters."""
# Documenting exceptions, replacing Raises sections,
# maybe add the information to the return value annotation:
def exceptions() -> (
Annotated[
None,
Raises(ValueError, "When something goes wrong."),
Raises(TypeError, "When something goes even wronger."),
]
):
"""Showing off raised exceptions."""
# Documenting warnings, replacing Warns sections,
# maybe add the information to the return value annotation:
def warnings() -> (
Annotated[
None,
Warns(FutureWarning, "Hello users."),
Warns(DeprecationWarning, "Hello developers."),
]
):
"""Showing off emitted warnings."""
# Advanced use-case: documenting multiple yielded/received/returned values:
def return_tuple() -> (
Generator[
tuple[
Annotated[int, Name("python"), Doc("First element of the yielded value.")],
Annotated[float, Name("cobra"), Doc("Second element of the yielded value.")],
],
tuple[
Annotated[int, Name("beep"), Doc("First element of the received value.")],
Annotated[float, Name("boop"), Doc("Second element of the received value.")],
],
tuple[
Annotated[int, Name("super"), Doc("First element of the returned value.")],
Annotated[float, Name("hyper"), Doc("Second element of the returned value.")],
],
]
):
"""Showing off tuples as yield/receive/return values."""
enhanced ¤
Functions:
-
deprecated1
–Showing off deprecated functions.
-
deprecated2
–Showing off deprecated parameters.
-
exceptions
–Showing off raised exceptions.
-
return_tuple
–Showing off tuples as yield/receive/return values.
-
warnings
–Showing off emitted warnings.
Attributes:
-
DEPRECATED
(Annotated[int, deprecated('Deprecated since v2.\n\n Please stop using this deprecated attribute, thanks!\n '), Doc('Showing off deprecated attributes.')]
) –Showing off deprecated attributes.
DEPRECATED module-attribute
¤
DEPRECATED: Annotated[
int,
deprecated(
"Deprecated since v2.\n\n Please stop using this deprecated attribute, thanks!\n "
),
Doc("Showing off deprecated attributes."),
]
Deprecated since v2.
Please stop using this deprecated attribute, thanks!
Showing off deprecated attributes.
deprecated1 ¤
deprecated1() -> (
Annotated[None, deprecated("Deprecated since v2.")]
)
Deprecated since v2.
Showing off deprecated functions.
Source code in docs/examples/enhanced.py
43 44 |
|
deprecated2 ¤
deprecated2(
param1: Annotated[
int,
deprecated("Deprecated since v2."),
Doc("Description of param1."),
] = 0,
)
Showing off deprecated parameters.
Parameters:
-
param1
(Annotated[int, deprecated('Deprecated since v2.'), Doc('Description of param1.')]
, default:0
) –Deprecated since v2. Description of param1.
Source code in docs/examples/enhanced.py
48 49 |
|
exceptions ¤
exceptions() -> Annotated[
None,
Raises(ValueError, "When something goes wrong."),
Raises(TypeError, "When something goes even wronger."),
]
Showing off raised exceptions.
Raises:
-
ValueError
–When something goes wrong.
-
TypeError
–When something goes even wronger.
Source code in docs/examples/enhanced.py
54 55 56 57 58 59 60 61 |
|
return_tuple ¤
return_tuple() -> Generator[
tuple[
Annotated[
int,
Name("python"),
Doc("First element of the yielded value."),
],
Annotated[
float,
Name("cobra"),
Doc("Second element of the yielded value."),
],
],
tuple[
Annotated[
int,
Name("beep"),
Doc("First element of the received value."),
],
Annotated[
float,
Name("boop"),
Doc("Second element of the received value."),
],
],
tuple[
Annotated[
int,
Name("super"),
Doc("First element of the returned value."),
],
Annotated[
float,
Name("hyper"),
Doc("Second element of the returned value."),
],
],
]
Showing off tuples as yield/receive/return values.
Yields:
-
python
(Annotated[int, Name('python'), Doc('First element of the yielded value.')]
) –First element of the yielded value.
-
cobra
(Annotated[float, Name('cobra'), Doc('Second element of the yielded value.')]
) –Second element of the yielded value.
Receives:
-
beep
(Annotated[int, Name('beep'), Doc('First element of the received value.')]
) –First element of the received value.
-
boop
(Annotated[float, Name('boop'), Doc('Second element of the received value.')]
) –Second element of the received value.
Returns:
-
super
(Annotated[int, Name('super'), Doc('First element of the returned value.')]
) –First element of the returned value.
-
hyper
(Annotated[float, Name('hyper'), Doc('Second element of the returned value.')]
) –Second element of the returned value.
Source code in docs/examples/enhanced.py
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 |
|
warnings ¤
warnings() -> Annotated[
None,
Warns(FutureWarning, "Hello users."),
Warns(DeprecationWarning, "Hello developers."),
]
Showing off emitted warnings.
Warns:
-
FutureWarning
–Hello users.
-
DeprecationWarning
–Hello developers.
Source code in docs/examples/enhanced.py
66 67 68 69 70 71 72 73 |
|