dataclass_documenter package

Submodules

dataclass_documenter.dataclass_documenter module

Generate documented YAML files from documented dataclasses.

class dataclass_documenter.dataclass_documenter.DataclassDocumenter(datacls, name=None, width=120, indent_unit='  ')

Bases: object

Generate markdown and YAML documentation from documented dataclasses.

__init__(datacls, name=None, width=120, indent_unit='  ')

Parameters:

• datacls – The dataclass to document.

• name – The name to use for this class in the documentation. If None, the name of the dataclass will be used.

• width – The target output width for wrapped comments.

• indent_unit – The string to repeat at the start of each line for each level of indentation.

property docstring

The parsed docstring.

property fields

The fields of the dataclass.

get_markdown(level=0)

Get a markdown description of the dataclass that contains a commented example YAML input file.

Parameters:

level – Markdown header level.

Returns:

The markdown string.

get_param_desc(param, default=None, warn=False)

Get the description of a parameter.

Parameters:

• param – The parameter name.

• default – The default value to return if the parameter lacks a description.

• warn – If True, log a warning when the description is missing.

Returns:

The parameter description.

get_param_type(param)

Get the type of a parameter.

Parameters:

param – The parameter name.

Returns:

The parameter type.

get_yaml(level=0, commented=False)

Get commented YAML input for the dataclass.

Parameters:

• level – Markdown header level.

• commented – If True, comment all lines.

get_yaml_blocks(level=0, header=None, commented=False, origin=None)

Get commented YAML input for the dataclass.

Parameters:

• level – The indentation level.

• header – An optional header to emit as a comment at the start of the output.

• commented – If True, comment all fields.

• origin – The optional container type for this object, either dict, list or None.

Returns:

A generator over blocks of YAML.

property params

The dict mapping parameter names to DocstrignParam values.

dataclass_documenter.main module

Command-line utility for generating dataclass documentation.

exception dataclass_documenter.main.DataclassLoaderError

Bases: Exception

Custom exception.

dataclass_documenter.main.import_dcls_from_file(path, name)

Import a dataclass from a filepath.

Parameters:

• path – The path to the file containing the definition of the dataclass, as a pathlib.Path object.

• name – The name of the dataclass.

Returns:

The dataclass.

dataclass_documenter.main.import_dcls_from_module(module, name)

Import a dataclass from a module.

Parameters:

• module – The module name. It must be importable.

• name – The name of the dataclass.

Returns:

The dataclass.

dataclass_documenter.main.main(args=None)

Generate Markdown or YAML for a dataclass.

Note that this will load the module containing the target dataclass and thus execute any top-level code within that module.

dataclass_documenter.main.run_main(args=None)

Wrapper to run main().

dataclass_documenter.typing module

Typing functions.

dataclass_documenter.typing.get_type_name(typ)

Get the name of a type.

Returns:

The name as a string.

dataclass_documenter.typing.is_optional(typ)

Check if a type is Optional.

Parameters:

typ – The type to check.

Returns:

True if the type is optional, False otherwise.

dataclass_documenter.typing.strip_optional(typ)

Strip outer optional types.

Parameters:

typ – The type to strip.

Returns:

The first non-optional type within the type.

dataclass_documenter.typing.type_to_string(typ)

Get a string representation of a type. Optional types are stripped down to their underlying type.

Parameters:

typ – The type to represent.

Returns:

The string representing the type.

Module contents

Package stub.

class dataclass_documenter.DataclassDocumenter(datacls, name=None, width=120, indent_unit='  ')

Bases: object

Generate markdown and YAML documentation from documented dataclasses.

__init__(datacls, name=None, width=120, indent_unit='  ')

Parameters:

• datacls – The dataclass to document.

• name – The name to use for this class in the documentation. If None, the name of the dataclass will be used.

• width – The target output width for wrapped comments.

• indent_unit – The string to repeat at the start of each line for each level of indentation.

property docstring

The parsed docstring.

property fields

The fields of the dataclass.

get_markdown(level=0)

Get a markdown description of the dataclass that contains a commented example YAML input file.

Parameters:

level – Markdown header level.

Returns:

The markdown string.

get_param_desc(param, default=None, warn=False)

Get the description of a parameter.

Parameters:

• param – The parameter name.

• default – The default value to return if the parameter lacks a description.

• warn – If True, log a warning when the description is missing.

Returns:

The parameter description.

get_param_type(param)

Get the type of a parameter.

Parameters:

param – The parameter name.

Returns:

The parameter type.

get_yaml(level=0, commented=False)

Get commented YAML input for the dataclass.

Parameters:

• level – Markdown header level.

• commented – If True, comment all lines.

get_yaml_blocks(level=0, header=None, commented=False, origin=None)

Get commented YAML input for the dataclass.

Parameters:

• level – The indentation level.

• header – An optional header to emit as a comment at the start of the output.

• commented – If True, comment all fields.

• origin – The optional container type for this object, either dict, list or None.

Returns:

A generator over blocks of YAML.

property params

The dict mapping parameter names to DocstrignParam values.