viz

This module provides utilities for converting an Abstract Syntax Tree (AST) to Mermaid for inline display in Jupyter (Lab ≥4.1 / NB ≥7.1) and to ASCII via the mermaid-ascii CLI.

Functions:

• ast_to_mermaid –
• ast_to_mermaid_ascii –
• visualize_ascii –
• visualize_image –

ast_to_mermaid

ast_to_mermaid(
    ast: ReprStruct, direction: Direction = "TD"
) -> str

Source code in packages/astx/src/astx/viz.py

def ast_to_mermaid(ast: ReprStruct, direction: Direction = "TD") -> str:
    """
    title: Mermaid for Jupyter/image (uses named items).
    parameters:
      ast:
        type: ReprStruct
      direction:
        type: Direction
    returns:
      type: str
    """
    return _traverse_ast_to_mermaid(ast, direction=direction, named_items=True)

ast_to_mermaid_ascii

ast_to_mermaid_ascii(
    ast: ReprStruct, direction: Direction = "TD"
) -> str

-

Mermaid tailored for mermaid-ascii, no named items, pipe edge labels.

Source code in packages/astx/src/astx/viz.py

def ast_to_mermaid_ascii(ast: ReprStruct, direction: Direction = "TD") -> str:
    """
    title: >-
      Mermaid tailored for mermaid-ascii, no named items, pipe edge labels.
    parameters:
      ast:
        type: ReprStruct
      direction:
        type: Direction
    returns:
      type: str
    """
    return _traverse_ast_to_mermaid(
        ast, direction=direction, named_items=False
    )

visualize_ascii

visualize_ascii(
    ast: ReprStruct,
    timeout: int = 10,
    direction: Direction = "TD",
    width: Optional[int] = None,
    border_padding: Optional[int] = 0,
    padding_x: Optional[int] = 3,
    padding_y: Optional[int] = 3,
    ascii_only: bool = False,
) -> str

For maximum compatibility, this uses an ASCII-friendly Mermaid form: - no named items (node text is the identifier) - pipe-labeled edges (--> |label| ...) parameters: ast: type: ReprStruct timeout: type: int direction: type: Direction width: type: Optional[int] border_padding: type: Optional[int] padding_x: type: Optional[int] padding_y: type: Optional[int] ascii_only: type: bool returns: type: str

Source code in packages/astx/src/astx/viz.py

def visualize_ascii(
    ast: ReprStruct,
    timeout: int = 10,
    direction: Direction = "TD",
    width: Optional[int] = None,
    border_padding: Optional[int] = 0,
    padding_x: Optional[int] = 3,
    padding_y: Optional[int] = 3,
    ascii_only: bool = False,
) -> str:
    """
    title: Render the AST to ASCII using the `mermaid-ascii` CLI.
    summary: |-

      For maximum compatibility, this uses an ASCII-friendly Mermaid form:
      - no named items (node text is the identifier)
      - pipe-labeled edges (--> |label| ...)
    parameters:
      ast:
        type: ReprStruct
      timeout:
        type: int
      direction:
        type: Direction
      width:
        type: Optional[int]
      border_padding:
        type: Optional[int]
      padding_x:
        type: Optional[int]
      padding_y:
        type: Optional[int]
      ascii_only:
        type: bool
    returns:
      type: str
    """
    exe = _find_mermaid_ascii()
    if exe is None:
        import yaml

        return str(yaml.dump(ast, sort_keys=False))

    src = ast_to_mermaid_ascii(ast, direction=direction)

    cmd = [exe]
    if width is not None:
        cmd += ["-x", str(width)]
    if border_padding is not None:
        cmd += ["--borderPadding", str(border_padding)]
    if padding_x is not None:
        cmd += ["--paddingX", str(padding_x)]
    if padding_y is not None:
        cmd += ["--paddingY", str(padding_y)]
    if ascii_only:
        cmd += ["--ascii"]

    proc = subprocess.run(
        cmd,
        input=src,
        text=True,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        timeout=timeout,
        check=False,
    )

    if proc.returncode != 0:
        first = src.splitlines()[0].strip() if src else ""
        hint = ""
        if "first line should define the graph" in (proc.stderr or ""):
            hint = f" (first line is {first!r}; try 'graph TD' or 'graph LR')"
        raise RuntimeError((proc.stderr or "mermaid-ascii failed.") + hint)

    if proc.stderr:
        raise RuntimeError(proc.stderr.strip())

    return proc.stdout

visualize_image

visualize_image(
    ast: ReprStruct, direction: Direction = "TD"
) -> None

Source code in packages/astx/src/astx/viz.py

def visualize_image(ast: ReprStruct, direction: Direction = "TD") -> None:
    """
    title: Display the AST as Mermaid inline in Jupyter (Lab ≥4.1 / NB ≥7.1).
    parameters:
      ast:
        type: ReprStruct
      direction:
        type: Direction
    """
    _display(  # type: ignore
        {"text/vnd.mermaid": ast_to_mermaid(ast, direction=direction)},
        raw=True,
    )