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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
"""Utility functions for working with docstrings."""
import typing as T
from collections import ChainMap
from inspect import Signature
from itertools import chain
from .common import (
DocstringMeta,
DocstringParam,
DocstringReturns,
DocstringStyle,
RenderingStyle,
)
from .parser import compose, parse
_Func = T.Callable[..., T.Any]
assert DocstringReturns # used in docstring
def combine_docstrings(
*others: _Func,
exclude: T.Iterable[T.Type[DocstringMeta]] = (),
style: DocstringStyle = DocstringStyle.AUTO,
rendering_style: RenderingStyle = RenderingStyle.COMPACT,
) -> _Func:
"""A function decorator that parses the docstrings from `others`,
programmatically combines them with the parsed docstring of the decorated
function, and replaces the docstring of the decorated function with the
composed result. Only parameters that are part of the decorated functions
signature are included in the combined docstring. When multiple sources for
a parameter or docstring metadata exists then the decorator will first
default to the wrapped function's value (when available) and otherwise use
the rightmost definition from ``others``.
The following example illustrates its usage:
>>> def fun1(a, b, c, d):
... '''short_description: fun1
...
... :param a: fun1
... :param b: fun1
... :return: fun1
... '''
>>> def fun2(b, c, d, e):
... '''short_description: fun2
...
... long_description: fun2
...
... :param b: fun2
... :param c: fun2
... :param e: fun2
... '''
>>> @combine_docstrings(fun1, fun2)
>>> def decorated(a, b, c, d, e, f):
... '''
... :param e: decorated
... :param f: decorated
... '''
>>> print(decorated.__doc__)
short_description: fun2
<BLANKLINE>
long_description: fun2
<BLANKLINE>
:param a: fun1
:param b: fun1
:param c: fun2
:param e: fun2
:param f: decorated
:returns: fun1
>>> @combine_docstrings(fun1, fun2, exclude=[DocstringReturns])
>>> def decorated(a, b, c, d, e, f): pass
>>> print(decorated.__doc__)
short_description: fun2
<BLANKLINE>
long_description: fun2
<BLANKLINE>
:param a: fun1
:param b: fun1
:param c: fun2
:param e: fun2
:param others: callables from which to parse docstrings.
:param exclude: an iterable of ``DocstringMeta`` subclasses to exclude when
combining docstrings.
:param style: style composed docstring. The default will infer the style
from the decorated function.
:param rendering_style: The rendering style used to compose a docstring.
:return: the decorated function with a modified docstring.
"""
def wrapper(func: _Func) -> _Func:
sig = Signature.from_callable(func)
comb_doc = parse(func.__doc__ or "")
docs = [parse(other.__doc__ or "") for other in others] + [comb_doc]
params = dict(
ChainMap(
*(
{param.arg_name: param for param in doc.params}
for doc in docs
)
)
)
for doc in reversed(docs):
if not doc.short_description:
continue
comb_doc.short_description = doc.short_description
comb_doc.blank_after_short_description = (
doc.blank_after_short_description
)
break
for doc in reversed(docs):
if not doc.long_description:
continue
comb_doc.long_description = doc.long_description
comb_doc.blank_after_long_description = (
doc.blank_after_long_description
)
break
combined = {}
for doc in docs:
metas = {}
for meta in doc.meta:
meta_type = type(meta)
if meta_type in exclude:
continue
metas.setdefault(meta_type, []).append(meta)
for (meta_type, meta) in metas.items():
combined[meta_type] = meta
combined[DocstringParam] = [
params[name] for name in sig.parameters if name in params
]
comb_doc.meta = list(chain(*combined.values()))
func.__doc__ = compose(
comb_doc, style=style, rendering_style=rendering_style
)
return func
return wrapper
|
