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
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
# 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."""
|
