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.decorators.LogRuntimeHook

class brainprep.decorators.LogRuntimeHook(title=None, bunched=True)[source]

Bases: Hook

Decorator that logs runtime metadata and input/output details of a function call.

This decorator uses an RSTReport instance to record metadata about the execution of the decorated function, including its module, docstring, inputs, outputs, and runtime statistics such as execution time and system information.

Log runtime metadata and input/output details of a function call.

This hook uses an RSTReport instance to record metadata about the execution of the decorated function. It captures the follwoing informations:

  • the function’s name, module, and docstring

  • the input arguments passed to the function

  • the returned output value

  • runtime statistics (e.g., execution time)

  • system information relevant to reproducibility

The collected metadata is appended to the report, allowing the workflow engine to generate detailed execution summaries suitable for provenance tracking, debugging, or documentation.

Parameters:
titlestr | None

A title to display. Default None.

bunchedbool

Return a bunch object with a default ‘outputs’ key. Default True.

Notes

  • The report is created using RSTReport(reloadable=True), which allows tracking multiple decorated steps.

  • Inputs are captured using inspect.getcallargs.

  • Runtime metadata includes start and end timestamps, execution duration in hours, platform details, and hostname.

  • Current configuration is also captured.

Examples

>>> from brainprep.reporting import RSTReport
>>> from brainprep.decorators import step, LogRuntimeHook

>>> @step(
...     hooks=[LogRuntimeHook()]
... )
... def add(a, b):
...     '''Adds two numbers.'''
...     return a + b

>>> report = RSTReport()
>>> result = add(3, 5)
>>> print(report)
Bunch(
  step1: Bunch(
    module: '...add'
    description: 'Adds two numbers.'
    inputs: Bunch(
      a: 3
      b: 5
    )
    outputs: Bunch(
      outputs: 8
    )
    runtime: Bunch(
      start: '...'
      end: '...'
      execution_time: ...
      brainprep_version: '...'
      platform: '...'
      hostname: '...'
    )
    config: Bunch(
      ...
    )
)
__init__(title=None, bunched=True)[source]
after_call(outputs)[source]

Transform and inspect outputs after the function call.

before_call(func, inputs)[source]

Transform and inspect inputs before the function call.

Parameters:
funcCallable

The function to be decorated.

inputsdict[str, Any]

Positional and keyword arguments passed to func. If a report_file keyword argument is passed, the logged runtime metada are saved in this file.

Returns:
inputsdict[str, Any]

Positional and keyword arguments passed to func where arguments annotated as File or Directory are converted to pathlib.Path objects, and list-typed arguments are coerced from comma-separated strings into lists.

Examples using brainprep.decorators.LogRuntimeHook

RST reporting

RST reporting