leaspy.utils.docs¶

Attributes¶

`T`
`R`
`DEFAULT_INIT_DOC`

Functions¶

`doc_with_`(target, original[, mapping])	Document (in-place) a function/class.
`doc_with`(original[, mapping])	Factory of function/class decorator to use the docstring of original
`doc_with_super`(*[, if_other_signature])	Factory of class decorator that comment (in-place) all of its inherited methods without docstrings + its top docstring

Module Contents¶

T¶

R¶

DEFAULT_INIT_DOC = 'Initialize self. See help(type(self)) for accurate signature.'¶

doc_with_(target, original, mapping=None, **mapping_kwargs)[source]¶

Document (in-place) a function/class.

Low-level version of doc_with() (refer to its documentation) Will set target.__doc__ in-place (not a decorator function).

Parameters:

targetobject: Object to document (e.g. a function, a class, a given class method, …).
originalobject: Object to copy documentation from.
mappingdict: Optional mapping to replace some terms (case-sensitive and word boundary aware) by others from the original docstring.
**mapping_kwargs: Optional keyword arguments passed to _replace_terms() (flags=…).

Returns:

target: The (in-place) modified target object.

Parameters:

target (object)
original (object)
mapping (Dict[str, str])

Return type:

object

doc_with(original, mapping=None, **mapping_kwargs)[source]¶

Factory of function/class decorator to use the docstring of original to document (in-place) the decorated function/class

Parameters:

originaldocumented Python object: The object to extract the docstring from
mappingdict[str, str], optional: Optional mapping to replace some terms (case-sensitive and word boundary aware) by others from the original docstring.
**mapping_kwargs: Optional keyword arguments passed to _replace_terms() (flags=…).

Returns:

Function/class decorator

Parameters:

original (object)
mapping (Dict[str, str])

Return type:

Callable[[object], object]

doc_with_super(*, if_other_signature='raise', **doc_with_kwargs)[source]¶

Factory of class decorator that comment (in-place) all of its inherited methods without docstrings + its top docstring with the ones from its parent class (the first parent class with this method documented if multiple inheritance)

Parameters:

if_other_signaturestr

Behavior if a documented method was found in parent but it has another signature:

'force': patch the method with the found docstring anyway (default)
'warn': patch the method but with a warning regarding signature mismatch
'skip': don’t patch the method with the found docstring
'raise': raise a ValueError

**doc_with_kwargs

Optional keyword arguments passed to doc_with() (mapping=…).

Returns:

Class decorator

Parameters:

if_other_signature (str)

Return type:

Callable[[T], T]