File size: 10,907 Bytes
7885a28 |
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 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 |
"""Utilities to allow inserting docstring fragments for common
parameters into function and method docstrings."""
from collections.abc import Callable, Iterable, Mapping
from typing import Protocol, TypeVar
import sys
__all__ = [
"docformat",
"inherit_docstring_from",
"indentcount_lines",
"filldoc",
"unindent_dict",
"unindent_string",
"extend_notes_in_docstring",
"replace_notes_in_docstring",
"doc_replace",
]
_F = TypeVar("_F", bound=Callable[..., object])
class Decorator(Protocol):
"""A decorator of a function."""
def __call__(self, func: _F, /) -> _F: ...
def docformat(docstring: str, docdict: Mapping[str, str] | None = None) -> str:
"""Fill a function docstring from variables in dictionary.
Adapt the indent of the inserted docs
Parameters
----------
docstring : str
A docstring from a function, possibly with dict formatting strings.
docdict : dict[str, str], optional
A dictionary with keys that match the dict formatting strings
and values that are docstring fragments to be inserted. The
indentation of the inserted docstrings is set to match the
minimum indentation of the ``docstring`` by adding this
indentation to all lines of the inserted string, except the
first.
Returns
-------
docstring : str
string with requested ``docdict`` strings inserted.
Examples
--------
>>> docformat(' Test string with %(value)s', {'value':'inserted value'})
' Test string with inserted value'
>>> docstring = 'First line\\n Second line\\n %(value)s'
>>> inserted_string = "indented\\nstring"
>>> docdict = {'value': inserted_string}
>>> docformat(docstring, docdict)
'First line\\n Second line\\n indented\\n string'
"""
if not docstring:
return docstring
if docdict is None:
docdict = {}
if not docdict:
return docstring
lines = docstring.expandtabs().splitlines()
# Find the minimum indent of the main docstring, after first line
if len(lines) < 2:
icount = 0
else:
icount = indentcount_lines(lines[1:])
indent = " " * icount
# Insert this indent to dictionary docstrings
indented = {}
for name, dstr in docdict.items():
lines = dstr.expandtabs().splitlines()
try:
newlines = [lines[0]]
for line in lines[1:]:
newlines.append(indent + line)
indented[name] = "\n".join(newlines)
except IndexError:
indented[name] = dstr
return docstring % indented
def inherit_docstring_from(cls: object) -> Decorator:
"""This decorator modifies the decorated function's docstring by
replacing occurrences of '%(super)s' with the docstring of the
method of the same name from the class `cls`.
If the decorated method has no docstring, it is simply given the
docstring of `cls`s method.
Parameters
----------
cls : type or object
A class with a method with the same name as the decorated method.
The docstring of the method in this class replaces '%(super)s' in the
docstring of the decorated method.
Returns
-------
decfunc : function
The decorator function that modifies the __doc__ attribute
of its argument.
Examples
--------
In the following, the docstring for Bar.func created using the
docstring of `Foo.func`.
>>> class Foo:
... def func(self):
... '''Do something useful.'''
... return
...
>>> class Bar(Foo):
... @inherit_docstring_from(Foo)
... def func(self):
... '''%(super)s
... Do it fast.
... '''
... return
...
>>> b = Bar()
>>> b.func.__doc__
'Do something useful.\n Do it fast.\n '
"""
def _doc(func: _F) -> _F:
cls_docstring = getattr(cls, func.__name__).__doc__
func_docstring = func.__doc__
if func_docstring is None:
func.__doc__ = cls_docstring
else:
new_docstring = func_docstring % dict(super=cls_docstring)
func.__doc__ = new_docstring
return func
return _doc
def extend_notes_in_docstring(cls: object, notes: str) -> Decorator:
"""This decorator replaces the decorated function's docstring
with the docstring from corresponding method in `cls`.
It extends the 'Notes' section of that docstring to include
the given `notes`.
Parameters
----------
cls : type or object
A class with a method with the same name as the decorated method.
The docstring of the method in this class replaces the docstring of the
decorated method.
notes : str
Additional notes to append to the 'Notes' section of the docstring.
Returns
-------
decfunc : function
The decorator function that modifies the __doc__ attribute
of its argument.
"""
def _doc(func: _F) -> _F:
cls_docstring = getattr(cls, func.__name__).__doc__
# If python is called with -OO option,
# there is no docstring
if cls_docstring is None:
return func
end_of_notes = cls_docstring.find(" References\n")
if end_of_notes == -1:
end_of_notes = cls_docstring.find(" Examples\n")
if end_of_notes == -1:
end_of_notes = len(cls_docstring)
func.__doc__ = (
cls_docstring[:end_of_notes] + notes + cls_docstring[end_of_notes:]
)
return func
return _doc
def replace_notes_in_docstring(cls: object, notes: str) -> Decorator:
"""This decorator replaces the decorated function's docstring
with the docstring from corresponding method in `cls`.
It replaces the 'Notes' section of that docstring with
the given `notes`.
Parameters
----------
cls : type or object
A class with a method with the same name as the decorated method.
The docstring of the method in this class replaces the docstring of the
decorated method.
notes : str
The notes to replace the existing 'Notes' section with.
Returns
-------
decfunc : function
The decorator function that modifies the __doc__ attribute
of its argument.
"""
def _doc(func: _F) -> _F:
cls_docstring = getattr(cls, func.__name__).__doc__
notes_header = " Notes\n -----\n"
# If python is called with -OO option,
# there is no docstring
if cls_docstring is None:
return func
start_of_notes = cls_docstring.find(notes_header)
end_of_notes = cls_docstring.find(" References\n")
if end_of_notes == -1:
end_of_notes = cls_docstring.find(" Examples\n")
if end_of_notes == -1:
end_of_notes = len(cls_docstring)
func.__doc__ = (
cls_docstring[: start_of_notes + len(notes_header)]
+ notes
+ cls_docstring[end_of_notes:]
)
return func
return _doc
def indentcount_lines(lines: Iterable[str]) -> int:
"""Minimum indent for all lines in line list
Parameters
----------
lines : Iterable[str]
The lines to find the minimum indent of.
Returns
-------
indent : int
The minimum indent.
Examples
--------
>>> lines = [' one', ' two', ' three']
>>> indentcount_lines(lines)
1
>>> lines = []
>>> indentcount_lines(lines)
0
>>> lines = [' one']
>>> indentcount_lines(lines)
1
>>> indentcount_lines([' '])
0
"""
indentno = sys.maxsize
for line in lines:
stripped = line.lstrip()
if stripped:
indentno = min(indentno, len(line) - len(stripped))
if indentno == sys.maxsize:
return 0
return indentno
def filldoc(docdict: Mapping[str, str], unindent_params: bool = True) -> Decorator:
"""Return docstring decorator using docdict variable dictionary.
Parameters
----------
docdict : dict[str, str]
A dictionary containing name, docstring fragment pairs.
unindent_params : bool, optional
If True, strip common indentation from all parameters in docdict.
Default is False.
Returns
-------
decfunc : function
The decorator function that applies dictionary to its
argument's __doc__ attribute.
"""
if unindent_params:
docdict = unindent_dict(docdict)
def decorate(func: _F) -> _F:
# __doc__ may be None for optimized Python (-OO)
doc = func.__doc__ or ""
func.__doc__ = docformat(doc, docdict)
return func
return decorate
def unindent_dict(docdict: Mapping[str, str]) -> dict[str, str]:
"""Unindent all strings in a docdict.
Parameters
----------
docdict : dict[str, str]
A dictionary with string values to unindent.
Returns
-------
docdict : dict[str, str]
The `docdict` dictionary but each of its string values are unindented.
"""
can_dict: dict[str, str] = {}
for name, dstr in docdict.items():
can_dict[name] = unindent_string(dstr)
return can_dict
def unindent_string(docstring: str) -> str:
"""Set docstring to minimum indent for all lines, including first.
Parameters
----------
docstring : str
The input docstring to unindent.
Returns
-------
docstring : str
The unindented docstring.
Examples
--------
>>> unindent_string(' two')
'two'
>>> unindent_string(' two\\n three')
'two\\n three'
"""
lines = docstring.expandtabs().splitlines()
icount = indentcount_lines(lines)
if icount == 0:
return docstring
return "\n".join([line[icount:] for line in lines])
def doc_replace(obj: object, oldval: str, newval: str) -> Decorator:
"""Decorator to take the docstring from obj, with oldval replaced by newval
Equivalent to ``func.__doc__ = obj.__doc__.replace(oldval, newval)``
Parameters
----------
obj : object
A class or object whose docstring will be used as the basis for the
replacement operation.
oldval : str
The string to search for in the docstring.
newval : str
The string to replace `oldval` with in the docstring.
Returns
-------
decfunc : function
A decorator function that replaces occurrences of `oldval` with `newval`
in the docstring of the decorated function.
"""
# __doc__ may be None for optimized Python (-OO)
doc = (obj.__doc__ or "").replace(oldval, newval)
def inner(func: _F) -> _F:
func.__doc__ = doc
return func
return inner
|