.inherit_kwargs()#

alfred3._helper.inherit_kwargs(_klass=None, *, from_: typing.Optional[list] = None, not_from_: typing.Optional[list] = None, include: typing.Optional[list] = None, exclude: typing.Optional[list] = None, sort_kwargs: bool = True, build_function: callable = <function build_kwargs>, **kwargs)[source]#

Decorator for easier docstring sharing, used for displaying documentation of inherited keyword arguments.

Parameters

  • from_ – List of classes to inherit argument documentation from.

  • not_from_ – List of classes not to inherit argument documentation from. Useful, if you want to include some specific parent or grandparent.

  • include – List of keyword argument names to include

  • exclude – List of keyword argument names to exclude

  • sort_kwargs – If True, the keyword arguments will be arranged in alphabetical order. Defaults to True.

  • build_function – A function that, as a minimmum, takes an argument of docs, which is the dictionary of arguments and their documentation. It must return a string. Its output is inserted in the decorated class’ docstring. The kwargs will be passed on to the build_function.

  • **kwargs – Further keyword arguments. These will be passed on to the build_function.

Notes

Replaces the placeholder {kwargs} in the docstring of the decorated object with argument documentation extracted from the parent classes.

Further notes:

  1. The decorator can deal with classes that inherit from more than one class.

  2. It is possible to use a different formatting by supplying a different build function.

  3. Arguments that are already part of the decorated class’ docstring will be filtered out.

  4. By using the from_ argument, you can inherit from a completely different class that is not part of the decorated class’ hierarchy.

  5. If you are using curly braces ({{}}) anywhere in your docstrings, you have to escape them to let inherit_kwargs know that they are not a placeholder. Otherwise you will receive a somewhat cryptic error message (“IndexError: Replacement index 0 out of range for positional args tuple”).

Examples

A simple example:

from alfred3._helper import inherit_kwargs

class Parent:
    '''
    Parent docstring.

    Args:
        arg1: Description
        arg2: Description
    '''

    def __init__(self, arg1, arg2):
        pass


@inherit_kwargs
class Child(Parent):
    '''
    Child docstring.

    Args:
        arg3: Description
        {kwargs}
    '''

    def __init__(self, arg3, **kwargs):
        super().__init__(**kwargs)