Skip to content

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:

Functions:

Attributes:

  • ATTRIBUTE (Annotated[str, Doc('Showing off attributes.\n\n Supporting multiple lines.\n ')]) –

    Showing off attributes.

ATTRIBUTE module-attribute ¤

ATTRIBUTE: Annotated[
    str,
    Doc(
        "Showing off attributes.\n\n        Supporting multiple lines.\n        "
    ),
]

Showing off attributes.

Supporting multiple lines.

OtherParameters ¤

Bases: TypedDict

Keyword arguments of simple.other_parameters.

Attributes:

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:

  • Annotated[int, Doc('Yielded integers.')]

    Yielded integers.

Receives:

  • Annotated[int, Doc('Received integers.')]

    Received integers.

Returns:

  • Annotated[int, Doc('Final returned value.')]

    Final returned value.

Source code in docs/examples/simple.py
50
51
52
53
54
55
def generator() -> Generator[
    Annotated[int, Doc("Yielded integers.")],
    Annotated[int, Doc("Received integers.")],
    Annotated[int, Doc("Final returned value.")],
]:
    """Showing off generators."""

iterator ¤

iterator() -> (
    Iterator[Annotated[int, Doc("Yielded integers.")]]
)

Showing off iterators.

Yields:

  • Annotated[int, Doc('Yielded integers.')]

    Yielded integers.

Source code in docs/examples/simple.py
59
60
def iterator() -> Iterator[Annotated[int, Doc("Yielded integers.")]]:
    """Showing off iterators."""

other_parameters ¤

other_parameters(
    **kwargs: Annotated[
        Unpack[OtherParameters],
        Doc("See other parameters."),
    ],
) -> None

Showing off other parameters.

Parameters:

Other Parameters:

Source code in docs/examples/simple.py
37
38
39
40
def other_parameters(
    **kwargs: Annotated[Unpack[OtherParameters], Doc("See other parameters.")],  # noqa: ARG001
) -> None:
    """Showing off other parameters."""

parameters ¤

parameters(
    param1: Annotated[
        str, Doc("Description of param1.")
    ] = "default",
)

Showing off parameters.

Parameters:

  • param1 (Annotated[str, Doc('Description of param1.')], default: 'default' ) –

    Description of param1.

Source code in docs/examples/simple.py
26
27
def parameters(param1: Annotated[str, Doc("Description of param1.")] = "default"):
    """Showing off 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
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."""

return_value ¤

return_value() -> Annotated[int, Doc('Returned integer.')]

Showing off return values.

Returns:

  • Annotated[int, Doc('Returned integer.')]

    Returned integer.

Source code in docs/examples/simple.py
44
45
46
def return_value() -> Annotated[int, Doc("Returned integer.")]:
    """Showing off return values."""
    return 0

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:

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
def deprecated1() -> Annotated[None, deprecated("Deprecated since v2.")]:
    """Showing off deprecated functions."""

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
def deprecated2(param1: Annotated[int, deprecated("Deprecated since v2."), Doc("Description of param1.")] = 0):
    """Showing off deprecated parameters."""

exceptions ¤

exceptions() -> Annotated[
    None,
    Raises(ValueError, "When something goes wrong."),
    Raises(TypeError, "When something goes even wronger."),
]

Showing off raised exceptions.

Raises:

Source code in docs/examples/enhanced.py
54
55
56
57
58
59
60
61
def exceptions() -> (
    Annotated[
        None,
        Raises(ValueError, "When something goes wrong."),
        Raises(TypeError, "When something goes even wronger."),
    ]
):
    """Showing off raised exceptions."""

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
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."""

warnings ¤

warnings() -> Annotated[
    None,
    Warns(FutureWarning, "Hello users."),
    Warns(DeprecationWarning, "Hello developers."),
]

Showing off emitted warnings.

Warns:

Source code in docs/examples/enhanced.py
66
67
68
69
70
71
72
73
def warnings() -> (
    Annotated[
        None,
        Warns(FutureWarning, "Hello users."),
        Warns(DeprecationWarning, "Hello developers."),
    ]
):
    """Showing off emitted warnings."""