2.3.16. vacumm.misc.docstrings – Docstrings processing

2.3.16.1. Overview

Attributes:
  • docfiller
  • docfiller_verbose
Classes:

2.3.16.2. Content

Docstring refomatting utilities for VACUMM help

Warning

This module requires python 2.7+ to work.

class DocFiller(*objs, **aobjs)[source]

Bases: object

Scan objects and return a dictionary whose key are their (formatted) name, and value are a dictionary of their attributes description

If the object is a method like Map.contour, the associated key is Map_contour. Therefore, classe names are supposed to not have any underscore inside.

Parameter description are indented with 12 spaces for methods and 8 spaces for other objects.

Example:
>>> df = DocFiller(MyClass1.my_method, MyClass2, myfync1)

@df.docfill
def myfunc2(para, parb, parc, pard)
    """My description

    :Params:

        {MyClass1_my_method[para]}
        {MyClass2[parb]}
        {MyClass2[parc]}
        {myfync1[pard]}
docfill(obj)[source]

Fill docstring of an object with collected parameter descriptions

It is typically used to format function docstrings using a decorator.

Warning

It cannot be applied to methods and classes.

formatted(indent)[source]

Format all parameter descriptions

Params:
  • indent, optional: Indentation string for all but the first line.
    • String: Used as is.
    • Integer: ident times the space char.
    • False: ''.
    • Class method: 12 spaces.
    • Other object: 8 spaces.
scan(*objs, **aobjs)[source]
class Docstring2Params(obj, select=None, prefix=None, sections=['param'])[source]

Bases: dict

Scan the docstring of an object to load parameters names and descriptions and reformat them.

The docstring must follow this example:

'''Description

Some text

:Section: text

:Params:

    - **arg**: text
      text
    - **opt**, optional: text

Some text or sections.

'''

In particular:

  • Parameters are described as in this example, on one or more lines.
  • They must be inside a section whose name contains “param”.
Params:
  • obj: Typically a function, method or class.
  • select, optional: A single or a list of parameter names to restrict scan.
Example:
>>> dsp = Docstring2Params(myfunc)
>>> dsp.format('firstparam')
>>> params = dsp.asdict(select=['secondpar', 'thirdpar'], indent=8)
RE_INDENT_MATCH()

match(string[, pos[, endpos]]) –> match object or None. Matches zero or more characters at the beginning of the string

RE_PARAM = <_sre.SRE_Pattern object>
RE_SECTION_MATCH()

match(string[, pos[, endpos]]) –> match object or None. Matches zero or more characters at the beginning of the string

asfmtdict(indent=8, select=None)[source]

Get parameters as a dictionary of formatted descriptions

format(select=None, indent=4)[source]

Reformat one or several parameters

Params:
  • indent, optional: Indentation string for all but the first line.
    • String: Used as is.
    • Integer: ident times the space char.
    • False: ''.
    • Class method: 12 spaces.
    • Other object: 8 spaces.
  • select, optional: List of parameter names to format. If None, all available parameters are used.