keep_params#

Docorator.keep_params(base_key, *params)#

Keep only specific parameters from a parameter documentation.

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

The new docstring with the selected parts will be accessible as base_key + '.' + '|'.join(params), e.g. 'original_key.param1|param2'

Parameters:

  • base_key (str) – key in the params dictionary

  • *params – str. Parameter identifier of which the documentations shall be in the new section

See also

keep_types, delete_params

Examples

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

>>> from docrep import DocstringProcessor
>>> d = DocstringProcessor()
>>> @d.get_sections(base='do_something')
... def do_something(a=1, b=2, c=3):
...     '''
...     That's %(doc_key)s
...
...     Parameters
...     ----------
...     a: int, optional
...         A dummy parameter description
...     b: int, optional
...         A second dummy parameter that will be excluded
...     c: float, optional
...         A third parameter'''
...     print(a)

>>> d.keep_params('do_something.parameters', 'a', 'c')

>>> @d.dedent
... def do_less(a=1, c=4):
...     '''
...     My second function with only `a` and `c`
...
...     Parameters
...     ----------
...     %(do_something.parameters.a|c)s'''
...     pass

>>> print(do_less.__doc__)
My second function with only `a` and `c`

Parameters
----------
a: int, optional
    A dummy parameter description
c: float, optional
    A third parameter

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

>>> d.delete_params('do_something.parameters', 'b')

>>> @d.dedent
... def do_less(a=1, c=4):
...     '''
...     My second function with only `a` and `c`
...
...     Parameters
...     ----------
...     %(do_something.parameters.no_b)s'''
...     pass
On this page