simplebench.doc_utils module🔗

Documentation utilities.

simplebench.doc_utils.format_docstring(
cls_or_func: None = None,
/,
**kwargs,
) → Callable[[T], T][source]🔗
simplebench.doc_utils.format_docstring(
cls_or_func: T,
/,
) → T

A decorator to format the docstring of a class or function.

Can be used with or without arguments on both classes and functions. It closely scopes the formatting to only the decorated object and to only the passed key-value pairs. It looks for {{key}} placeholders in the docstring and replaces them with the corresponding values from kwargs.

Note

  • If used without arguments, the decorator will not modify the docstring.

  • {} Placeholders in the docstring that do not have corresponding keys in kwargs will remain unchanged. This means that if the docstring contains code examples or other text with braces, those will not be affected.

  • Changes will probably NOT be reflected in IDE tooltips. They are intended for runtime documentation access (e.g., via help() or .__doc__ access) or for generating external documentation. Tools that read docstrings statically from source code will not see the changes.

    Therefore, this decorator is best suited for adding dynamic information such as version numbers, author names, or configuration-dependent details to docstrings, rather than for altering the fundamental description of the class or function. It should be used carefully with awareness that it may appear either with or without the changes so to avoid confusion either way.

Examples:

@format_docstring(version="1.2.3")
class MyClass:
    '''My class, version {version}'''
    pass

@format_docstring(author="Me")
def my_function():
    '''A function by {author}'''
    pass
Parameters:

  • cls_or_func (Optional[Callable[..., Any]]) – The class or function to decorate. If None, the decorator is being called with arguments.

  • kwargs – Key-value pairs to format the docstring.

Returns:

The decorated class or function. If called with keyword arguments, returns a decorator function that is then applied to the target object.

Return type:

T | Callable[[T], T]