momotor.shared.doc¶
This appendix documents a helper for package authors. Most users of this package do not need it.
annotate_docstring() is a decorator that fills
placeholders in a docstring with values from the code. Momotor packages use
it to name the exact logger a class writes to, without repeating the logger
name as a string that can go stale:
from logging import getLogger
from momotor.shared.doc import annotate_docstring
logger = getLogger('some.logger')
@annotate_docstring(logger=logger)
class SomeClass:
"""This class does some logging on the "{logger.name}" logger."""
After decoration, the docstring reads: This class does some logging on the “some.logger” logger.
API reference¶
- momotor.shared.doc.annotate_docstring(*args, **kwargs)¶
Decorator to help write better docstrings.
The arguments of the decorator are applied using
str.format()to the __doc__ of the class or method decorated.Example:
logger = getLogger('some.logger') @annotate_docstring(logger=logger) class SomeClass: """ This class does some logging on the "{logger.name}" logger """
In the example above, the docstring will read:
This class does some logging on the "some.logger" logger
- Parameters:
args – the arguments for
str.format()kwargs – the keyword arguments for
str.format()
- Returns:
the decorated object with annotated doc string