unifi-network-maps 1.4.3__py3-none-any.whl → 1.4.5__py3-none-any.whl

unifi_network_maps/cli/render.py

@@ -0,0 +1,255 @@
+"""CLI rendering orchestration."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+
+from ..adapters.config import Config
+from ..adapters.unifi import fetch_clients
+from ..io.export import write_output
+from ..io.mkdocs_assets import write_mkdocs_sidebar_assets
+from ..model.topology import (
+    Device,
+    TopologyResult,
+    build_node_type_map,
+    build_port_map,
+    group_devices_by_type,
+)
+from ..render.legend import resolve_legend_style
+from ..render.lldp_md import render_lldp_md
+from ..render.mermaid import render_mermaid
+from ..render.mermaid_theme import MermaidTheme
+from ..render.mkdocs import MkdocsRenderOptions, render_mkdocs
+from ..render.svg import SvgOptions, render_svg
+from ..render.svg_theme import SvgTheme
+from .runtime import (
+    build_edges_with_clients,
+    load_dark_mermaid_theme,
+    load_devices_data,
+    load_topology_for_render,
+    resolve_mkdocs_client_ports,
+    select_edges,
+)
+
+
+def render_mermaid_output(
+    args: argparse.Namespace,
+    devices: list[Device],
+    topology: TopologyResult,
+    config: Config | None,
+    site: str,
+    mermaid_theme: MermaidTheme,
+    *,
+    clients_override: list[object] | None = None,
+) -> str:
+    edges, _has_tree = select_edges(topology)
+    edges, clients = build_edges_with_clients(
+        args,
+        edges,
+        devices,
+        config,
+        site,
+        clients_override=clients_override,
+    )
+    groups = None
+    group_order = None
+    if args.group_by_type:
+        groups = group_devices_by_type(devices)
+        group_order = ["gateway", "switch", "ap", "other"]
+    content = render_mermaid(
+        edges,
+        direction=args.direction,
+        groups=groups,
+        group_order=group_order,
+        node_types=build_node_type_map(devices, clients, client_mode=args.client_scope),
+        theme=mermaid_theme,
+    )
+    if args.markdown:
+        content = f"""```mermaid
+{content}```
+"""
+    return content
+
+
+def render_svg_output(
+    args: argparse.Namespace,
+    devices: list[Device],
+    topology: TopologyResult,
+    config: Config | None,
+    site: str,
+    svg_theme: SvgTheme,
+    *,
+    clients_override: list[object] | None = None,
+) -> str:
+    edges, _has_tree = select_edges(topology)
+    edges, clients = build_edges_with_clients(
+        args,
+        edges,
+        devices,
+        config,
+        site,
+        clients_override=clients_override,
+    )
+    options = SvgOptions(width=args.svg_width, height=args.svg_height)
+    if args.format == "svg-iso":
+        from ..render.svg import render_svg_isometric
+
+        return render_svg_isometric(
+            edges,
+            node_types=build_node_type_map(devices, clients, client_mode=args.client_scope),
+            options=options,
+            theme=svg_theme,
+        )
+    return render_svg(
+        edges,
+        node_types=build_node_type_map(devices, clients, client_mode=args.client_scope),
+        options=options,
+        theme=svg_theme,
+    )
+
+
+def render_mkdocs_format(
+    args: argparse.Namespace,
+    *,
+    devices: list[Device],
+    topology: TopologyResult,
+    config: Config | None,
+    site: str,
+    mermaid_theme: MermaidTheme,
+    mock_clients: list[object] | None,
+) -> str | None:
+    if args.mkdocs_sidebar_legend and not args.output:
+        logging.error("--mkdocs-sidebar-legend requires --output")
+        return None
+    if args.mkdocs_sidebar_legend:
+        write_mkdocs_sidebar_assets(args.output)
+    port_map = build_port_map(devices, only_unifi=args.only_unifi)
+    client_ports, error_code = resolve_mkdocs_client_ports(
+        args,
+        devices,
+        config,
+        site,
+        mock_clients,
+    )
+    if error_code is not None:
+        logging.error("Mock data required for client rendering")
+        return None
+    dark_mermaid_theme = load_dark_mermaid_theme() if args.mkdocs_dual_theme else None
+    edges, _has_tree = select_edges(topology)
+    options = MkdocsRenderOptions(
+        direction=args.direction,
+        legend_style=resolve_legend_style(
+            format_name=args.format,
+            legend_style=args.legend_style,
+        ),
+        legend_scale=args.legend_scale,
+        timestamp_zone=args.mkdocs_timestamp_zone,
+        client_scope=args.client_scope,
+        dual_theme=args.mkdocs_dual_theme,
+    )
+    return render_mkdocs(
+        edges,
+        devices,
+        mermaid_theme=mermaid_theme,
+        port_map=port_map,
+        client_ports=client_ports,
+        options=options,
+        dark_mermaid_theme=dark_mermaid_theme,
+    )
+
+
+def render_lldp_format(
+    args: argparse.Namespace,
+    *,
+    config: Config | None,
+    site: str,
+    mock_devices: list[object] | None,
+    mock_clients: list[object] | None,
+) -> int:
+    try:
+        _raw_devices, devices = load_devices_data(
+            args,
+            config,
+            site,
+            raw_devices_override=mock_devices,
+        )
+    except Exception as exc:
+        logging.error("Failed to load devices: %s", exc)
+        return 1
+    if mock_clients is None:
+        if config is None:
+            logging.error("Mock data required for client rendering")
+            return 2
+        clients = list(fetch_clients(config, site=site))
+    else:
+        clients = mock_clients
+    content = render_lldp_md(
+        devices,
+        clients=clients,
+        include_ports=args.include_ports,
+        show_clients=args.include_clients,
+        client_mode=args.client_scope,
+    )
+    write_output(content, output_path=args.output, stdout=args.stdout)
+    return 0
+
+
+def render_standard_format(
+    args: argparse.Namespace,
+    *,
+    config: Config | None,
+    site: str,
+    mock_devices: list[object] | None,
+    mock_clients: list[object] | None,
+    mermaid_theme: MermaidTheme,
+    svg_theme: SvgTheme,
+) -> int:
+    topology_result = load_topology_for_render(
+        args,
+        config=config,
+        site=site,
+        mock_devices=mock_devices,
+    )
+    if topology_result is None:
+        return 1
+    devices, topology = topology_result
+
+    if args.format == "mermaid":
+        content = render_mermaid_output(
+            args,
+            devices,
+            topology,
+            config,
+            site,
+            mermaid_theme,
+            clients_override=mock_clients,
+        )
+    elif args.format == "mkdocs":
+        content = render_mkdocs_format(
+            args,
+            devices=devices,
+            topology=topology,
+            config=config,
+            site=site,
+            mermaid_theme=mermaid_theme,
+            mock_clients=mock_clients,
+        )
+        if content is None:
+            return 2
+    elif args.format in {"svg", "svg-iso"}:
+        content = render_svg_output(
+            args,
+            devices,
+            topology,
+            config,
+            site,
+            svg_theme,
+            clients_override=mock_clients,
+        )
+    else:
+        logging.error("Unsupported format: %s", args.format)
+        return 2
+
+    write_output(content, output_path=args.output, stdout=args.stdout)
+    return 0

unifi_network_maps/cli/runtime.py

@@ -0,0 +1,157 @@
+"""Runtime data preparation for CLI rendering."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from pathlib import Path
+
+from ..adapters.config import Config
+from ..adapters.unifi import fetch_clients, fetch_devices
+from ..io.debug import debug_dump_devices
+from ..model.topology import (
+    ClientPortMap,
+    Device,
+    TopologyResult,
+    build_client_edges,
+    build_client_port_map,
+    build_device_index,
+    build_topology,
+    group_devices_by_type,
+    normalize_devices,
+)
+from ..render.mermaid_theme import MermaidTheme
+from ..render.theme import load_theme
+
+logger = logging.getLogger(__name__)
+
+
+def load_devices_data(
+    args: argparse.Namespace,
+    config: Config | None,
+    site: str,
+    *,
+    raw_devices_override: list[object] | None = None,
+) -> tuple[list[object], list[Device]]:
+    if raw_devices_override is None:
+        if config is None:
+            raise ValueError("Config required to fetch devices")
+        raw_devices = list(
+            fetch_devices(config, site=site, detailed=True, use_cache=not args.no_cache)
+        )
+    else:
+        raw_devices = raw_devices_override
+    devices = normalize_devices(raw_devices)
+    if args.debug_dump:
+        debug_dump_devices(raw_devices, devices, sample_count=max(0, args.debug_sample))
+    return raw_devices, devices
+
+
+def build_topology_data(
+    args: argparse.Namespace,
+    config: Config | None,
+    site: str,
+    *,
+    include_ports: bool | None = None,
+    raw_devices_override: list[object] | None = None,
+) -> tuple[list[Device], list[str], TopologyResult]:
+    _raw_devices, devices = load_devices_data(
+        args,
+        config,
+        site,
+        raw_devices_override=raw_devices_override,
+    )
+    groups_for_rank = group_devices_by_type(devices)
+    gateways = groups_for_rank.get("gateway", [])
+    topology = build_topology(
+        devices,
+        include_ports=include_ports if include_ports is not None else args.include_ports,
+        only_unifi=args.only_unifi,
+        gateways=gateways,
+    )
+    return devices, gateways, topology
+
+
+def build_edges_with_clients(
+    args: argparse.Namespace,
+    edges: list,
+    devices: list[Device],
+    config: Config | None,
+    site: str,
+    *,
+    clients_override: list[object] | None = None,
+) -> tuple[list, list | None]:
+    clients = None
+    if args.include_clients:
+        if clients_override is None:
+            if config is None:
+                raise ValueError("Config required to fetch clients")
+            clients = list(fetch_clients(config, site=site, use_cache=not args.no_cache))
+        else:
+            clients = clients_override
+        device_index = build_device_index(devices)
+        edges = edges + build_client_edges(
+            clients,
+            device_index,
+            include_ports=args.include_ports,
+            client_mode=args.client_scope,
+        )
+    return edges, clients
+
+
+def select_edges(topology: TopologyResult) -> tuple[list, bool]:
+    if topology.tree_edges:
+        return topology.tree_edges, True
+    logging.warning("No gateway found for hierarchy; rendering raw edges.")
+    return topology.raw_edges, False
+
+
+def load_topology_for_render(
+    args: argparse.Namespace,
+    *,
+    config: Config | None,
+    site: str,
+    mock_devices: list[object] | None,
+) -> tuple[list[Device], TopologyResult] | None:
+    try:
+        include_ports = True if args.format == "mkdocs" else None
+        devices, _gateways, topology = build_topology_data(
+            args,
+            config,
+            site,
+            include_ports=include_ports,
+            raw_devices_override=mock_devices,
+        )
+    except Exception as exc:
+        logging.error("Failed to build topology: %s", exc)
+        return None
+    return devices, topology
+
+
+def load_dark_mermaid_theme() -> MermaidTheme | None:
+    dark_theme_path = Path(__file__).resolve().parents[1] / "assets" / "themes" / "dark.yaml"
+    try:
+        dark_theme, _ = load_theme(dark_theme_path)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Failed to load dark theme: %s", exc)
+        return None
+    return dark_theme
+
+
+def resolve_mkdocs_client_ports(
+    args: argparse.Namespace,
+    devices: list[Device],
+    config: Config | None,
+    site: str,
+    mock_clients: list[object] | None,
+) -> tuple[ClientPortMap | None, int | None]:
+    if not args.include_clients:
+        return None, None
+    if mock_clients is None:
+        if config is None:
+            return None, 2
+        clients = list(fetch_clients(config, site=site))
+    else:
+        clients = mock_clients
+    client_ports = build_client_port_map(devices, clients, client_mode=args.client_scope)
+    return client_ports, None

unifi_network_maps/io/mkdocs_assets.py

@@ -0,0 +1,21 @@
+"""MkDocs asset output helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..render.templating import render_template
+
+
+def write_mkdocs_sidebar_assets(output_path: str) -> None:
+    output_dir = Path(output_path).resolve().parent
+    assets_dir = output_dir / "assets"
+    assets_dir.mkdir(parents=True, exist_ok=True)
+    (assets_dir / "legend.js").write_text(
+        render_template("mkdocs_legend.js.j2"),
+        encoding="utf-8",
+    )
+    (assets_dir / "legend.css").write_text(
+        render_template("mkdocs_legend.css.j2"),
+        encoding="utf-8",
+    )