Note

This page is a reference documentation. It only explains the class signature, and not how to use it. Please refer to the user guide for the big picture.

brainprep.reporting.rst_reporting.RSTReport

class brainprep.reporting.rst_reporting.RSTReport(*args, **kwargs)

Bases: object

Render structured report content using reStructuredText (RST) format.

This class collects and organizes data using Bunch objects and renders them as RST-formatted text. It supports registering multiple data entries under unique identifiers and exporting the report to a .rst file.

The class uses a singleton pattern via SingletonReport, ensuring only one instance exists.

Different renderings are possible:

• print the object to get the Bunch content.

• use save_as_rst to save it as a rst file.

To add a new data entry to the report under a given identifier and name use the register method.

Parameters:

reloadablebool

If False, the report content is automatically reset upon instantiation. Default False.

incrementbool

If False, the inner step counter is not incremented upon instantiation. Default False.

Attributes:

_registryBunch

Internal storage for all registered report data.

_str_fieldstuple[str]

Allowed string fields.

Notes

Supported data types for registration include: - str for metadata fields “module” “trace” and “description”. - Bunch for other structured data blocks.

Examples

>>> report = RSTReport()
>>> report.register("step1", "module", "my_module.my_function")
>>> report.register("step1", "description",
...                 "This function adds two numbers.")
>>> report.register("step1", "inputs", Bunch(a=3, b=5))
>>> print(report)
Bunch(
  step1: Bunch(
    module: 'my_module.my_function'
    description: 'This function adds two numbers.'
    inputs: Bunch(
      a: 3
      b: 5
    )
  )
)
>>> report.save_as_rst("/tmp/report.rst")

__init__(reloadable=False, increment=False)

register(identifier, name, data)

Add a new data entry to the report under a given identifier and name.

Two data types are supported: - string for the ‘module’, ‘trace’ and ‘description’ data elements. - Bunch otherwise.

Parameters:

identifier: str

A unique data identifier.

name: str

A unique data element name.

data: str | Bunch

The data.

Raises:

ValueError

If duplicated name found or input data are invalid types.

save_as_rst(file_name)

Save the report content to a reStructuredText (.rst) file.

Parameters:

file_name: File

Path to the RST file used for saving.