Install & Compatibility
Where this runs
tested against v0.3.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 0.037s · 19.4MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 2.5s · import 0.036s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DocstringProcessor
✓ from docrep import DocstringProcessor
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}")
Debug
Known issues
breakingIn 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.fixReplace `DocstringProcessor.dedents` with `DocstringProcessor.dedent` and `DocstringProcessor.with_indents` with `DocstringProcessor.with_indent`.
affects: >=0.3.0
deprecatedThe standalone function `docrep.dedents` was deprecated in version 0.2.6 in favor of `inspect.cleandoc` and later superseded by `DocstringProcessor.dedent`.fixUse `DocstringProcessor().dedent` or `inspect.cleandoc` instead.
affects: >=0.2.6
gotchaDocrep 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.fixEnsure your docstrings strictly adhere to the NumPy docstring format for reliable operation.
affects: All
gotchaIn 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.fixFor modern Python versions (3+), this is not an issue. If maintaining legacy Python 2.7 code, consider refactoring or explicitly setting `DocstringProcessor.python2_classes`.
affects: 0.2.3 - 0.3.2 (Python 2.7 specific)
Errors
Common errors & fixes
AttributeError: 'DocstringProcessor' object has no attribute 'dedents'
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.
fixUpdate your code to use `docstrings.dedent` instead of `docstrings.dedents`.
AttributeError: 'DocstringProcessor' object has no attribute 'with_indents'
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.
fixUpdate your code to use `docstrings.with_indent` instead of `docstrings.with_indents`.
Upgrade
Version history
0.3.2latest on PyPI · released Feb 16, 2021
Audit
Dependencies
No dependency data recorded yet.