docstripy.parse_doc#

docstripy.parse_doc.main_parser#

Global docstring parsing functions.

parse_docstring(lines, *, add_missing=True)#

Docstring parser.

Parameters:

  • lines (List[str]) – Lines of the file.

  • add_missing (bool, optional) – Whether to add missing docstrings, by default True.

Return type:

Tuple[List[List[int]], List[dict], List[bool]]

Returns:

  • ranges_docstr (List[List[int]]) – Ranges of the docstrings.

  • sections_list (List[Dict]) – Parsed sections.

  • to_insert (List[bool]) – Whether to insert a new docstring or overwrite the existing one.

parse_all(lines_docstr)#

Parse the whole docstring.

Parameters:

lines_docstr (List[str]) – Lines of the docstring.

Returns:

sections – Parsed sections. Can contain the following keys:

  • _title (List[str])

  • _parameters (List[Dict])

  • _returns (List[Dict])

  • _attributes (List[Dict])

  • _raises (List[Dict])

  • any other section name found in the docstring (List[str])

Return type:

Dict

Examples

One can parse a docstring as follows:

{
    '_title': ['This is a title\n', '\n', 'This is a description\n'],
    '_parameters': [
        {
            'name': 'param1',
            'type': 'int',
            'optional': False,
            'description': ['Description of param1\n'],
        },
        {
            'name': 'param2',
            'type': 'str',
            'optional': True,
            'description': ['Description of param2\n'],
            'default': '""',
        },
    ],
    '_returns': [
        {
            'type': 'int',
            'description': ['Description of the return\n'],
        },
    ],
    'Example': ['Example of a section\n'],
}
clean_empty_param_section(sections)#

Clean empty param dict.

Return type:

List[dict]

clean_empty_sections(sections_list)#

Clean empty param section.

Return type:

None

docstripy.parse_doc.parse_params#

Parameter section parsing functions.

parse_params_all(lines, style, section_name='param')#

Parse parameters, raises, returns, yields and attributes section.

Parameters:

  • lines (List[str]) – Lines of the docstring containing parameters descriptions.

  • style (str) – Format style of the docstring (one of ‘numpy’, ‘google’ or ‘rest’).

  • section_name (str, optional) – Name of the section to parse. One of “param”, “return”, “yield”, “attribute”, “raises”. By default, “param”.

Returns:

params_dict – Parameters dictionary with the following keys:

typedict

Dictionary of parameter names and their types.

optionaldict

Dictionary of parameter names and whether they are optional.

descriptiondict

Dictionary of parameter names and their descriptions.

defaultdict

Dictionary of parameter names and their default values.

Return type:

dict

Example

One can parse a docstring as follows:

[
    {
        'name': 'param1',
        'type': 'int',
        'optional': False,
        'description': ['Description of param1\n'],
    },
    {
        'name': 'param2',
        'type': 'str',
        'optional': True,
        'description': ['Description of param2\n'],
        'default': '""',
    },
],
extract_default_value(lines)#

Extract default value from description.

Return type:

Tuple[List[str], str]

docstripy.parse_doc.parse_signature#

Parse def lines (function signatures).

parse_signature(lines)#

Parse function signature (“def …”).

Return type:

tuple[str, List[str], List[dict]]

parse_signature_args(split)#

Parse function arguments on signature line.

Return type:

dict

split_comma(line)#

Parse by comma.

Return type:

List[str]

docstripy.parse_doc.postprocessing#

Postprocessing functions for some sections.

postprocess_title_parse(lines)#

Post-process the title section.

Return type:

List[str]

postprocess_description(lines)#

Post process description.

Return type:

List[str]

postprocess_default_val(default)#

Post process default value string.

Return type:

str

docstripy.parse_doc.section_ranges#

Parse sections.

parse_sections_ranges(lines)#

Parse sections of a docstring and detect docstring style.

Parameters:

lines (List[str]) – Lines of the docstring.

Return type:

Tuple[Dict, str]

Returns:

  • sec_ranges (Dict) – Section ranges. Example: {‘_title’: [0, 2], ‘_parameters’: [3, 5], “Note”: [6, 9]}.

  • style (str) – Style of the docstring (one of ‘numpy’, ‘google’ or ‘rest’).

clean_section_ranges(ranges)#

Clean section ranges.

If a section is empty, remove it.

Return type:

Dict

delimit_section_ranges(ranges, last_ind)#

Delimit section ranges.

Determine the end of each section if not already found.

Return type:

Dict

docstripy.parse_doc.signature#

Signature related functions.

merge_docstr_signature(sections_docstr, lines_signature)#

Merge docstring and definition ranges.

Return type:

dict

find_range_matching(ranges_def, ranges_docstr, lines=None)#

Find the ranges in ranges_docstr that matches ranges_def.

Parameters:

  • ranges_def (List[List[int]]) – Range of signature lines.

  • ranges_docstr (List[List[int]]) – Ranges of all the docstrings of the file.

  • lines (Optional[List[str]], optional) – Lines of the whole file. Only used to find class docstrings. By default, not specified (None).

Returns:

corresp_ranges_docstr – Ranges of the docstrings that matches the ranges in ranges_def.

Return type:

List[List[int]]

are_lines_class_head(lines)#

Return if the lines are the head of a class.

Return type:

bool

make_title_from_func_name(fn_name)#

Make title from function name.

Return type:

List[str]