leaspy.utils.docs module
- doc_with(original: object, mapping: Dict[str, str] | None = None, **mapping_kwargs) Callable[[object], object]
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
- doc_with_(target: object, original: object, mapping: Dict[str, str] | None = None, **mapping_kwargs) object
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.
- doc_with_super(*, if_other_signature: str = 'raise', **doc_with_kwargs) Callable[[T], T]
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