Source code for matplotlib.docstring

import inspect

from matplotlib import _api

[docs]class Substitution: """ A decorator that performs %-substitution on an object's docstring. This decorator should be robust even if ``obj.__doc__`` is None (for example, if -OO was passed to the interpreter). Usage: construct a docstring.Substitution with a sequence or dictionary suitable for performing substitution; then decorate a suitable function with the constructed object, e.g.:: sub_author_name = Substitution(author='Jason') @sub_author_name def some_function(x): "%(author)s wrote this function" # note that some_function.__doc__ is now "Jason wrote this function" One can also use positional arguments:: sub_first_last_names = Substitution('Edgar Allen', 'Poe') @sub_first_last_names def some_function(x): "%s %s wrote the Raven" """ def __init__(self, *args, **kwargs): if args and kwargs: raise TypeError("Only positional or keyword args are allowed") self.params = args or kwargs def __call__(self, func): if func.__doc__: func.__doc__ = inspect.cleandoc(func.__doc__) % self.params return func
[docs] def update(self, *args, **kwargs): """ Update ``self.params`` (which must be a dict) with the supplied args. """ self.params.update(*args, **kwargs)
@classmethod @_api.deprecated("3.3", alternative="assign to the params attribute") def from_params(cls, params): """ In the case where the params is a mutable sequence (list or dictionary) and it may change before this class is called, one may explicitly use a reference to the params rather than using *args or **kwargs which will copy the values and not reference them. :meta private: """ result = cls() result.params = params return result
[docs]def copy(source): """Copy a docstring from another source function (if present).""" def do_copy(target): if source.__doc__: target.__doc__ = source.__doc__ return target return do_copy
# Create a decorator that will house the various docstring snippets reused # throughout Matplotlib. interpd = Substitution() dedent_interpd = interpd