pyfcstm.entry.visualize

Visualization CLI integration for rendered state machine diagrams.

This module adds a visualize subcommand to the main CLI. The command reads an FCSTM DSL file, reuses the existing PlantUML generation pipeline, renders an image through the Python plantumlcli library, and optionally opens the rendered file with the operating system’s default viewer.

The implementation keeps runtime dependencies minimal by delegating rendering and display to tools that are commonly available in the target environment instead of embedding a GUI toolkit in the CLI process.

Example:

>>> import click
>>> from pyfcstm.entry.visualize import _add_visualize_subcommand
>>> cli = click.Group()
>>> _add_visualize_subcommand(cli)  
<...Group...>

get_visualize_cache_dir

pyfcstm.entry.visualize.get_visualize_cache_dir() → Path[source]

Get the cache directory used for auto-generated diagram outputs.

The location follows platform conventions to keep rendered preview files in a stable place long enough for external viewers to open them successfully.

Returns:

Cache directory path.

Return type:

pathlib.Path

resolve_visualize_output_path

pyfcstm.entry.visualize.resolve_visualize_output_path(input_code_file: str, output_file: str | None, render_type: str) → Path[source]

Resolve the final rendered output path.

Parameters:

  • input_code_file (str) – Input DSL file path.

  • output_file (str or None) – User-specified output path, or None to use the cache directory.

  • render_type (str) – Rendered file type.

Returns:

Absolute output path.

Return type:

pathlib.Path

Raises:

pyfcstm.entry.base.ClickErrorException – If the output suffix conflicts with render_type.

load_plantumlcli_classes

pyfcstm.entry.visualize.load_plantumlcli_classes()[source]

Load Python API classes from plantumlcli.

Returns:

Two-tuple of (LocalPlantuml, RemotePlantuml) classes.

Return type:

Tuple[type, type]

Raises:

pyfcstm.entry.base.ClickErrorException – If the package is not available.

create_local_plantuml_backend

pyfcstm.entry.visualize.create_local_plantuml_backend(java: str | None = None, plantuml_jar: str | None = None)[source]

Create a local PlantUML backend from plantumlcli.

Parameters:

  • java (str or None) – Optional Java executable path.

  • plantuml_jar (str or None) – Optional PlantUML jar path.

Returns:

Local backend object.

Return type:

Any

create_remote_plantuml_backend

pyfcstm.entry.visualize.create_remote_plantuml_backend(remote_host: str | None = None)[source]

Create a remote PlantUML backend from plantumlcli.

Parameters:

remote_host (str or None) – Optional remote host URL.

Returns:

Remote backend object.

Return type:

Any

run_plantumlcli_builtin_check

pyfcstm.entry.visualize.run_plantumlcli_builtin_check(renderer: str, java: str | None = None, plantuml_jar: str | None = None, remote_host: str | None = None) → Dict[str, Tuple[bool, str]][source]

Run plantumlcli’s built-in check flow and return availability status.

This uses the same Python entry logic behind plantumlcli -c rather than reimplementing the checks locally.

Parameters:

  • renderer (str) – Requested renderer mode.

  • java (str or None) – Optional Java executable path for local rendering.

  • plantuml_jar (str or None) – Optional PlantUML jar path for local rendering.

  • remote_host (str or None) – Optional remote PlantUML host URL.

Returns:

Mapping from renderer name to (available, message).

Return type:

Dict[str, Tuple[bool, str]]

resolve_renderer_backend

pyfcstm.entry.visualize.resolve_renderer_backend(renderer: str, java: str | None = None, plantuml_jar: str | None = None, remote_host: str | None = None) → Tuple[str, Any][source]

Resolve the effective renderer backend object.

Parameters:

  • renderer (str) – Requested renderer mode.

  • java (str or None) – Optional Java executable path for local rendering.

  • plantuml_jar (str or None) – Optional PlantUML jar path for local rendering.

  • remote_host (str or None) – Optional remote PlantUML host URL.

Returns:

Two-tuple of (renderer_name, backend_object).

Return type:

Tuple[str, Any]

Raises:

pyfcstm.entry.base.ClickErrorException – If no usable backend is available for the requested mode.

render_plantuml_diagram

pyfcstm.entry.visualize.render_plantuml_diagram(plantuml_output: str, output_file: Path, render_type: str, renderer: str, java: str | None = None, plantuml_jar: str | None = None, remote_host: str | None = None) → str[source]

Render PlantUML text into a diagram file through plantumlcli.

Parameters:

  • plantuml_output (str) – PlantUML source text.

  • output_file (pathlib.Path) – Target output file path.

  • render_type (str) – Rendered file type.

  • renderer (str) – Requested renderer mode.

  • java (str or None) – Optional Java executable path for local rendering.

  • plantuml_jar (str or None) – Optional PlantUML jar path for local rendering.

  • remote_host (str or None) – Optional remote PlantUML host URL.

Returns:

Effective renderer mode used for the render.

Return type:

str

Raises:

pyfcstm.entry.base.ClickErrorException – If rendering fails.

detect_headless_environment

pyfcstm.entry.visualize.detect_headless_environment() → Tuple[bool, str | None][source]

Detect whether the current process should avoid GUI operations.

Returns:

Two-tuple of (is_headless, reason).

Return type:

Tuple[bool, Optional[str]]

open_diagram_with_default_app

pyfcstm.entry.visualize.open_diagram_with_default_app(file_path: Path) → Tuple[bool, str][source]

Open a rendered diagram file with the operating system’s default viewer.

Parameters:

file_path (pathlib.Path) – Rendered diagram path.

Returns:

Two-tuple of (opened, reason).

Return type:

Tuple[bool, str]