Fill and share documentation (docfiller)

Functions:

`indent_docstring`(docstring[, prefix])	Create indented docstring
`doc_decorate`(*docstrings[, _prepend])	A decorator take docstring templates, concatenate them and perform string substitution on it.
`dedent_recursive`(data)	Dedent nested mapping of strings.

Classes:

`TParameter`(name, type, desc)	Interface to Parameters namedtuple in docscrape
`DocFiller`([params])	Class to handle doc filling.

module_utilities.docfiller.indent_docstring(docstring, prefix='+ ')[source]#: Create indented docstring

module_utilities.docfiller.doc_decorate(*docstrings, _prepend=False, **params)[source]#

A decorator take docstring templates, concatenate them and perform string substitution on it.

This decorator will add a variable “_docstring_components” to the wrapped callable to keep track the original docstring template for potential usage. If it should be consider as a template, it will be saved as a string. Otherwise, it will be saved as callable, and later user __doc__ and dedent to get docstring

Parameters:

*docstrings (str or callable()) – The string / docstring / docstring template to be appended in order after default docstring under callable.
_prepend (bool, default False) – If True, prepend decorated function docstring. Otherwise, append to end.
**params – The string which would be used to format docstring template.

Notes

Doc filling can be turned off by setting the environment variable DOCFILLER_SUB to one of 0, f, false.

Examples

>>> @doc_decorate(type_='int')
... def func0(x, y):
...     '''
...     Parameters
...     ----------
...     x : {type_}
...         x parameter.
...     y : {type_}
...         y parameter.
...     Returns
...     -------
...     output : {type_}
...     '''
...     pass
>>> print(indent_docstring(func0))
+  Parameters
+  ----------
+  x : int
+      x parameter.
+  y : int
+      y parameter.
+  Returns
+  -------
+  output : int

To inherit from a function/docstring, pass it:

>>> @doc_decorate(func0, type_='float')
... def func1(x, y):
...     pass
>>> print(indent_docstring(func1))
+  Parameters
+  ----------
+  x : float
+      x parameter.
+  y : float
+      y parameter.
+  Returns
+  -------
+  output : float

class module_utilities.docfiller.TParameter(name, type, desc)[source]#

Bases: NamedTuple

Interface to Parameters namedtuple in docscrape

Attributes:

`name`	Alias for field number 0
`type`	Alias for field number 1
`desc`	Alias for field number 2

name#: Alias for field number 0

type#: Alias for field number 1

desc#: Alias for field number 2

module_utilities.docfiller.dedent_recursive(data)[source]#

Dedent nested mapping of strings.

Parameters:: data (dict)
Returns:: output (object) – Same type of data, with dedented values

Examples

>>> data = {
...     'a': {'value' : '''
...      a : int
...          A thing
...      '''}}
>>> print(data['a']['value'])

     a : int
         A thing

>>> data = dedent_recursive(data)
>>> print(data['a']['value'])
a : int
    A thing

class module_utilities.docfiller.DocFiller(params=None)[source]#

Bases: object

Class to handle doc filling.

Parameters:

func_or_doc (callable() or str) – Docstring to parse. If callable, extract from function signature.
key_char (str, default '|') – Optional string to split name into key/name pair.

Examples

>>> d = DocFiller.from_docstring(
...     '''
...     Parameters
...     ----------
...     x : int
...         x param
...     y : int
...         y param
...     z0 | z : int
...         z int param
...     z1 | z : float
...         z float param
...
...     Returns
...     -------
...     output0 | output : int
...         Integer output.
...     output1 | output : float
...         Float output
...     ''',
...     combine_keys='parameters'
... )
...
>>> print(d.keys()[-4:])
['x', 'y', 'z0', 'z1']
>>> @d.decorate
... def func(x, y, z):
...     '''
...     Parameters
...     ----------
...     {x}
...     {y}
...     {z0}
...     Returns
...     --------
...     {returns.output0}
...     '''
...     return x + y + z
...
>>> print(indent_docstring(func))
+  Parameters
+  ----------
+  x : int
+      x param
+  y : int
+      y param
+  z : int
+      z int param
+  Returns
+  --------
+  output : int
+      Integer output.

Methods:

`new_like`([data])	Create new object with optional data.
`dedent`()	Recursively dedent params
`keys`()	List of keys
`assign_combined_key`(new_key, keys)	Combine multiple keys into single key
`assign_keys`(**kwargs)	Create new key from other keys.
`assign_param`(name[, ptype, desc, key])	Add in a new parameter
`concat`(args, *kwargs)	Create new object from multiple DocFiller or dict objects.
`append`(args, *kwargs)	Calls `concat` method with `self` as first argument.
`insert_level`(name)	Insert a level/namespace.
`levels_to_top`(*names)	Make a level top level accessible
`rename_levels`(**kws)	Rename a keys at top level.
`update`(args, *kwargs)	Update parameters
`assign`(**kwargs)	Assign new key/value pairs
`decorate`(func)	Default decorator.
`__call__`(*templates[, _prepend])	Factory function to create docfiller decorator.
`inherit`(template[, _prepend])	Factor function to create decorator.
`factory_from_parent`(cls)	Interface to docinherit.factory_docfiller_from_parent.
`factory_inherit_from_parent`(cls)	Interface to docinherit.factory_docfiller_inherit_from_parent.
`from_dict`(params[, namespace, combine_keys, ...])	Create a Docfiller instance from a dictionary.
`from_docstring`(func_or_doc[, namespace, ...])	Create a Docfiller instance from a function or docstring.

Attributes:

params

An AttributeDict view of parameters.

new_like(data=None)[source]#: Create new object with optional data.

dedent()[source]#: Recursively dedent params

keys()[source]#: List of keys

assign_combined_key(new_key, keys)[source]#: Combine multiple keys into single key

assign_keys(**kwargs)[source]#

Create new key from other keys.

Parameters:: **kwargs – new_key=old_key or new_key=[old_key0, old_key1, …] Note that dot notation is accepted.

Examples

>>> d = DocFiller({'a0': 'a0', 'a1': 'a1', 'b': 'b'})
>>> dn = d.assign_keys(a='a0', c=['a0','b']).data
>>> print(dn['a'])
a0

>>> print(dn['c'])
a0
b

assign_param(name, ptype='', desc=None, key=None)[source]#

Add in a new parameter

Parameters:

name (str) – Parameters name
key (str, optional) – Optional key for placement in self. This is like using key | name.
ptype (str, default '') – Optional type.
desc (str or list of str, default '') – Parameter description.

Returns:

output (DocFiller) – New DocFiller instance.

Examples

>>> d = DocFiller()
>>> dn = d.assign_param(
...     name='x',
...     ptype='float',
...     desc='''
...     A parameter
...     with multiple levels
...     ''',
... )
>>> print(dn['x'])
x : float
    A parameter
    with multiple levels

classmethod concat(*args, **kwargs)[source]#

Create new object from multiple DocFiller or dict objects.

Parameters:

*args – dict or Docfiller
**kwargs – dict or Docfiller objects The passed name will be used as the top level.

Returns:

DocFiller – combined DocFiller object.

Notes

Use unnamed args to pass in underlying data. Use names kwargs to add namespace.

append(*args, **kwargs)[source]#: Calls concat method with self as first argument.

insert_level(name)[source]#: Insert a level/namespace.

levels_to_top(*names)[source]#: Make a level top level accessible

rename_levels(**kws)[source]#: Rename a keys at top level.

params[source]#: An AttributeDict view of parameters.

update(*args, **kwargs)[source]#: Update parameters

assign(**kwargs)[source]#: Assign new key/value pairs

decorate(func)[source]#

Default decorator.

This uses self.params and the decorated function docstring as a template. If need to pass parameters, use self.__call__

See also

__call__

__call__(*templates, _prepend=False, **params)[source]#

Factory function to create docfiller decorator.

This should always be used in a callable manner.

If want to call without any parameter use decorate()

Parameters:

*templates (callable()) – docstrings to be used as templates.
_prepend (bool, default False) – If True, then prepend templates with docstring of decorated function. Otherwise, append to end.
**params – Extra parameters to be substituted.

Example

Using the default decorator

>>> d = DocFiller({"x": "hello", "y": "there"})
>>> @d.decorate
... def func():
...     '''
...     A function with  x={x} and y={y}
...     '''
...     pass
>>> print(indent_docstring(func))
+  A function with  x=hello and y=there

Using call without args

>>> @d()
... def func1():
...     '''
...     A new function with x={x} and y={y}
...     '''
...     pass
>>> print(indent_docstring(func1))
+  A new function with x=hello and y=there

Using call with args. This inherits from passed template

>>> @d(func, x="new_x")
... def func2():
...     pass
>>> print(indent_docstring(func2))
+  A function with  x=new_x and y=there

inherit(template, _prepend=False, **params)[source]#

Factor function to create decorator.

Use combination of docstring_inheritance.inherit_numpy_docstring and DocFiller.

Parameters:

template (callable()) – Template method to inherit from.
_prepend (bool, default False) – Prepend parameter.
**params – Extra parameter specificiations.

Returns:

decorator (callable()) – Decorator

See also

doc_inherit

factory_from_parent(cls)[source]#

Interface to docinherit.factory_docfiller_from_parent.

Parameters:: cls (type) – Class to inherit from.

See also

factory_docfiller_from_parent

factory_inherit_from_parent(cls)[source]#

Interface to docinherit.factory_docfiller_inherit_from_parent.

Parameters:: cls (type) – Class to inherit from

See also

factory_docfiller_inherit_from_parent

classmethod from_dict(params, namespace=None, combine_keys=None, keep_keys=True, key_map=None)[source]#

Create a Docfiller instance from a dictionary.

Parameters:

params (mapping)
namespace (str, optional) – Top level namespace for DocFiller.
combine_keys (str, sequence of str, mapping, optional) – If str or sequence of str, Keys of params to at the top level. If mapping, should be of form {namespace: key(s)}
keep_keys (str, sequence of str, bool) – If False, then don’t keep any keys at top level. This is useful with the combine_keys parameter. If True, keep all keys, regardless of combine_keys. If str or sequence of str, keep these keys in output.
key_map (mapping or callable()) – Function or mapping to new keys in resulting dict.

Returns:

DocFiller

classmethod from_docstring(func_or_doc, namespace=None, combine_keys=None, key_char='|', keep_keys=True, key_map=None)[source]#

Create a Docfiller instance from a function or docstring.

Parameters:

func_or_doc (str or callable()) – Docstring to parse to get parameters.
namespace (str, optional) – Top level namespace for DocFiller.
combine_keys (str, sequence of str, mapping, optional) – If str or sequence of str, Keys of params to at the top level. If mapping, should be of form {namespace: key(s)}
key_char (str, default "|") – Character to split names. By default, for parameters, the key will be parsed from The docstring. If you want to override this, you can use key | name : …. in the definition (where ‘|’ is the value of key_char).
keep_keys (str, sequence of str, bool) – If False, then don’t keep any keys at top level. This is useful with the combine_keys parameter. If True, keep all keys, regardless of combine_keys. If str or sequence of str, keep these keys in output.
key_map (mapping or callable()) – Function or mapping to new keys in resulting dict.

Returns:

DocFiller

Fill and share documentation (docfiller)

Contents

Fill and share documentation (docfiller)#

Fill and share documentation (`docfiller`)#