Examples¤

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

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