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:
Returns:

the decorated object with annotated doc string