keep_types#

Docorator.keep_types(base_key, out_key, *types)#

Keep only specific parameters from a parameter documentation.

This method extracts the given type from the base_key item in the params dictionary and creates a new item with the original documentation with only the description of the type. This method works for the 'Results' sections.

Parameters:

base_key (str) – key in the params dictionary
out_key (str) – Extension for the base key (the final key will be like '%s.%s' % (base_key, out_key)
*types – str. The type identifier of which the documentations shall be in the new section

See also

delete_types, keep_params

Examples

To extract just two return arguments from a function and reuse their docstrings, you can type:

>>> from docrep import DocstringProcessor
>>> d = DocstringProcessor()
>>> @d.get_sections(base='do_something', sections=['Returns'])
... def do_something():
...     '''
...     That's %(doc_key)s
...
...     Returns
...     -------
...     float
...         A random number
...     int
...         A random integer'''
...     return 1.0, 4

>>> d.keep_types('do_something.returns', 'int_only', 'int')

>>> @d.dedent
... def do_less():
...     '''
...     My second function that only returns an integer
...
...     Returns
...     -------
...     %(do_something.returns.int_only)s'''
...     return do_something()[1]

>>> print(do_less.__doc__)
My second function that only returns an integer

Returns
-------
int
    A random integer

Equivalently, you can use the delete_types() method to remove parameters:

>>> d.delete_types('do_something.returns', 'no_float', 'float')

>>> @d.dedent
... def do_less():
...     '''
...     My second function with only `a` and `c`
...
...     Returns
...     ----------
...     %(do_something.returns.no_float)s'''
...     return do_something()[1]