misc.doccer

Utilities to allow inserting docstring fragments for common parameters into function and method docstrings

Module Contents

Functions

docformat(docstring,docdict=None) Fill a function docstring from variables in dictionary
inherit_docstring_from(cls) This decorator modifies the decorated function’s docstring by
indentcount_lines(lines) Minimum indent for all lines in line list
filldoc(docdict,unindent_params=True) Return docstring decorator using docdict variable dictionary
unindent_dict(docdict) Unindent all strings in a docdict
unindent_string(docstring) Set docstring to minimum indent for all lines, including first
docformat(docstring, docdict=None)

Fill a function docstring from variables in dictionary

Adapt the indent of the inserted docs

docstring : string
docstring from function, possibly with dict formatting strings
docdict : dict, optional
dictionary with keys that match the dict formatting strings and values that are docstring fragments to be inserted. The indentation of the inserted docstrings is set to match the minimum indentation of the docstring by adding this indentation to all lines of the inserted string, except the first
outstring : string
string with requested docdict strings inserted
>>> docformat(' Test string with %(value)s', {'value':'inserted value'})
' Test string with inserted value'
>>> docstring = 'First line\\n    Second line\\n    %(value)s'
>>> inserted_string = "indented\\nstring"
>>> docdict = {'value': inserted_string}
>>> docformat(docstring, docdict)
'First line\\n    Second line\\n    indented\\n    string'
inherit_docstring_from(cls)

This decorator modifies the decorated function’s docstring by replacing occurrences of ‘%(super)s’ with the docstring of the method of the same name from the class cls.

If the decorated method has no docstring, it is simply given the docstring of `cls`s method.

cls : Python class or instance
A class with a method with the same name as the decorated method. The docstring of the method in this class replaces ‘%(super)s’ in the docstring of the decorated method.
f : function
The decorator function that modifies the __doc__ attribute of its argument.

In the following, the docstring for Bar.func created using the docstring of Foo.func.

>>> class Foo(object):
...     def func(self):
...         Do something useful.
...         return
...
>>> class Bar(Foo):
...     @inherit_docstring_from(Foo)
...     def func(self):
...         %(super)s
...         Do it fast.
...
...         return
...
>>> b = Bar()
>>> b.func.__doc__
'Do something useful.\n        Do it fast.\n        '
indentcount_lines(lines)

Minimum indent for all lines in line list

>>> lines = [' one', '  two', '   three']
>>> indentcount_lines(lines)
1
>>> lines = []
>>> indentcount_lines(lines)
0
>>> lines = [' one']
>>> indentcount_lines(lines)
1
>>> indentcount_lines(['    '])
0
filldoc(docdict, unindent_params=True)

Return docstring decorator using docdict variable dictionary

docdict : dictionary
dictionary containing name, docstring fragment pairs
unindent_params : {False, True}, boolean, optional
If True, strip common indentation from all parameters in docdict
decfunc : function
decorator that applies dictionary to input function docstring
unindent_dict(docdict)

Unindent all strings in a docdict

unindent_string(docstring)

Set docstring to minimum indent for all lines, including first

>>> unindent_string(' two')
'two'
>>> unindent_string('  two\\n   three')
'two\\n three'