docrep: Docstring Repetition

0.3.2 · active · verified Thu Apr 16

docrep is a Python library designed for intelligent reuse of docstrings, following the 'Don't Repeat Yourself' (DRY) principle. It helps developers manage documentation in complex and nested Python APIs by providing tools to analyze, update, and repeat sections of docstrings, particularly those adhering to NumPy conventions. The latest stable version is 0.3.2, released in February 2021, indicating a slower release cadence.

Common errors

```
AttributeError: 'DocstringProcessor' object has no attribute 'dedents'
```
cause You are attempting to use the `dedents` method on `DocstringProcessor`, which was deprecated in version 0.3.0 and scheduled for removal in 0.4.

fix Update your code to use `docstrings.dedent` instead of `docstrings.dedents`.
```
AttributeError: 'DocstringProcessor' object has no attribute 'with_indents'
```
cause You are attempting to use the `with_indents` method on `DocstringProcessor`, which was deprecated in version 0.3.0 and scheduled for removal in 0.4.

fix Update your code to use `docstrings.with_indent` instead of `docstrings.with_indents`.

Warnings

breaking In version 0.3.0, several methods of the `DocstringProcessor` API were deprecated and unified. The old methods (`dedents`, `with_indents`) will be removed in version 0.4.
Fix: Replace `DocstringProcessor.dedents` with `DocstringProcessor.dedent` and `DocstringProcessor.with_indents` with `DocstringProcessor.with_indent`.
deprecated The standalone function `docrep.dedents` was deprecated in version 0.2.6 in favor of `inspect.cleandoc` and later superseded by `DocstringProcessor.dedent`.
Fix: Use `DocstringProcessor().dedent` or `inspect.cleandoc` instead.
gotcha Docrep expects docstrings to follow NumPy conventions, typically parsed by the Sphinx Napoleon extension. Deviations from this format might lead to unexpected parsing or replacement behavior.
Fix: Ensure your docstrings strictly adhere to the NumPy docstring format for reliable operation.
gotcha In Python 2.7 (now End-of-Life), class `__doc__` attributes are not writable by default. Docrep's decorators for classes would not have an effect unless `DocstringProcessor.python2_classes` was explicitly adjusted.
Fix: For modern Python versions (3+), this is not an issue. If maintaining legacy Python 2.7 code, consider refactoring or explicitly setting `DocstringProcessor.python2_classes`.

Install

pip install docrep Install with pip

Imports

DocstringProcessor
```
from docrep import DocstringProcessor
```

Quickstart

Initialise `DocstringProcessor` and use its decorators to extract and reuse sections of docstrings, for example, the parameters and returns from a base function's NumPy-style docstring.

from docrep import DocstringProcessor

docstrings = DocstringProcessor()

@docstrings.get_sections
def my_base_function(param_a: int, param_b: str):
    """
    This is a base function.

    Parameters
    ----------
    param_a : int
        The first parameter.
    param_b : str
        The second parameter.

    Returns
    -------
    bool
        True if the operation was successful.
    """
    print(f"Base function called with {param_a}, {param_b}")
    return True

@docstrings.dedent
def my_derived_function(param_a: int, param_b: str, param_c: float):
    """
    This is a derived function that reuses docstrings.

    Parameters
    ----------
    %(my_base_function.parameters)s
    param_c : float
        A third, specific parameter.

    Returns
    -------
    %(my_base_function.returns)s
    """
    print(f"Derived function called with {param_a}, {param_b}, {param_c}")
    return my_base_function(param_a, param_b)

if __name__ == "__main__":
    print("--- Docstring for my_derived_function ---")
    print(my_derived_function.__doc__)
    print("\n--- Calling my_derived_function ---")
    result = my_derived_function(1, "hello", 3.14)
    print(f"Result: {result}")

view raw JSON →