Diagramming

The labtech.diagram module provides the following functions for automatically generating a diagram to visualise your tasks, their parameters, and their dependency relationships.

labtech.diagram.build_task_diagram(tasks: Sequence[Task], *, direction: str = 'BT') -> str

Returns a Mermaid diagram representing the task types and dependencies of the given tasks.

Each task type lists its parameters (with their return types) and its run method (with its return type).

Arrows between task types point from a dependency task type to the task type that depends on it, and are labelled with the dependent task's parameter that references the dependency task type.

Parameters:

• tasks (Sequence[Task]) –

  A collection of tasks to diagram.

• direction (str, default: 'BT' ) –

  Direction that task types should be laid out, from dependent tasks to their dependencies. One of:

  • 'BT' (bottom-to-top)
  • 'TB' (top-to-bottom)
  • 'RL' (right-to-left)
  • 'LR' (left-to-right)

Source code in labtech/diagram.py

def build_task_diagram(tasks: Sequence[Task], *, direction: str = 'BT') -> str:
    """Returns a [Mermaid diagram](https://mermaid.js.org/syntax/classDiagram.html)
    representing the task types and dependencies of the given tasks.

    Each task type lists its parameters (with their return types) and
    its run method (with its return type).

    Arrows between task types point from a dependency task type to the
    task type that depends on it, and are labelled with the dependent
    task's parameter that references the dependency task type.

    Args:
        tasks: A collection of tasks to diagram.
        direction: Direction that task types should be laid out, from dependent
            tasks to their dependencies. One of:

            * `'BT'` (bottom-to-top)
            * `'TB'` (top-to-bottom)
            * `'RL'` (right-to-left)
            * `'LR'` (left-to-right)

    """
    return diagram_task_structure(
        TaskStructure.build(tasks),
        direction=direction,
    )

labtech.diagram.display_task_diagram(tasks: Sequence[Task], **kwargs) -> None

Displays a Mermaid diagram representing the task types and dependencies of the given tasks.

If IPython is available (e.g. the code is being run from a Jupyter notebook), the diagram will be displayed as a Markdown mermaid code block, which will be rendered as a Mermaid diagram from JupyterLab 4.1 and Notebook 7.1.

Because Markdown may render arbitrary HTML, you should only diagram tasks that you trust.

Accepts the same arguments as build_task_diagram.

Source code in labtech/diagram.py

def display_task_diagram(tasks: Sequence[Task], **kwargs) -> None:
    """Displays a [Mermaid diagram](https://mermaid.js.org/syntax/classDiagram.html)
    representing the task types and dependencies of the given tasks.

    If IPython is available (e.g. the code is being run from a Jupyter
    notebook), the diagram will be displayed as a Markdown `mermaid`
    code block, which will be rendered as a Mermaid diagram from
    [JupyterLab 4.1 and Notebook 7.1](https://blog.jupyter.org/jupyterlab-4-1-and-notebook-7-1-are-here-20bfc3c10217).

    Because Markdown may render arbitrary HTML, you should only
    diagram tasks that you trust.

    Accepts the same arguments as
    [build_task_diagram][labtech.diagram.build_task_diagram].

    """
    diagram = build_task_diagram(tasks, **kwargs)
    if is_ipython():
        from IPython.display import Markdown, display
        display(Markdown(f'```mermaid\n{diagram}\n```'))
    else:
        print(diagram)