unifi-network-maps 1.4.1__py3-none-any.whl → 1.4.2__py3-none-any.whl

unifi_network_maps/cli/main.py

@@ -4,6 +4,9 @@ from __future__ import annotations
 
 import argparse
 import logging
+from datetime import datetime
+from pathlib import Path
+from zoneinfo import ZoneInfo
 
 from ..adapters.config import Config
 from ..adapters.unifi import fetch_clients, fetch_devices
@@ -14,6 +17,7 @@ from ..model.topology import (
     ClientPortMap,
     Device,
     PortMap,
+    TopologyResult,
     build_client_edges,
     build_client_port_map,
     build_device_index,
@@ -29,7 +33,7 @@ from ..render.mermaid import render_legend, render_legend_compact, render_mermai
 from ..render.mermaid_theme import MermaidTheme
 from ..render.svg import SvgOptions, render_svg
 from ..render.svg_theme import SvgTheme
-from ..render.theme import resolve_themes
+from ..render.theme import load_theme, resolve_themes
 
 logger = logging.getLogger(__name__)
 
@@ -120,6 +124,11 @@ def _add_functional_args(parser: argparse._ArgumentGroup) -> None:
     parser.add_argument(
         "--only-unifi", action="store_true", help="Only include neighbors that are UniFi devices"
     )
+    parser.add_argument(
+        "--no-cache",
+        action="store_true",
+        help="Disable UniFi API cache reads and writes",
+    )
 
 
 def _add_mermaid_args(parser: argparse._ArgumentGroup) -> None:
@@ -173,6 +182,16 @@ def _add_general_render_args(parser: argparse._ArgumentGroup) -> None:
         action="store_true",
         help="For mkdocs output, write sidebar legend assets next to the output file",
     )
+    parser.add_argument(
+        "--mkdocs-dual-theme",
+        action="store_true",
+        help="Render light/dark Mermaid blocks for MkDocs Material theme switching",
+    )
+    parser.add_argument(
+        "--mkdocs-timestamp-zone",
+        default="Europe/Amsterdam",
+        help="Timezone for mkdocs generated timestamp (use 'off' to disable)",
+    )
 
 
 def _add_debug_args(parser: argparse._ArgumentGroup) -> None:
@@ -236,7 +255,9 @@ def _load_devices_data(
     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))
+        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)
@@ -252,7 +273,7 @@ def _build_topology_data(
     *,
     include_ports: bool | None = None,
     raw_devices_override: list[object] | None = None,
-) -> tuple[list[Device], list[str], object]:
+) -> tuple[list[Device], list[str], TopologyResult]:
     _raw_devices, devices = _load_devices_data(
         args,
         config,
@@ -284,7 +305,7 @@ def _build_edges_with_clients(
         if clients_override is None:
             if config is None:
                 raise ValueError("Config required to fetch clients")
-            clients = list(fetch_clients(config, site=site))
+            clients = list(fetch_clients(config, site=site, use_cache=not args.no_cache))
         else:
             clients = clients_override
         device_index = build_device_index(devices)
@@ -297,7 +318,7 @@ def _build_edges_with_clients(
     return edges, clients
 
 
-def _select_edges(topology: object) -> tuple[list, bool]:
+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.")
@@ -307,7 +328,7 @@ def _select_edges(topology: object) -> tuple[list, bool]:
 def _render_mermaid_output(
     args: argparse.Namespace,
     devices: list[Device],
-    topology: object,
+    topology: TopologyResult,
     config: Config | None,
     site: str,
     mermaid_theme: MermaidTheme,
@@ -346,40 +367,134 @@ def _render_mermaid_output(
 def _render_mkdocs_output(
     args: argparse.Namespace,
     devices: list[Device],
-    topology: object,
-    config: Config,
-    site: str,
+    topology: TopologyResult,
     mermaid_theme: MermaidTheme,
     port_map: PortMap,
     client_ports: ClientPortMap | None,
+    timestamp_zone: str,
+    dark_mermaid_theme: MermaidTheme | None = None,
 ) -> str:
     edges, _has_tree = _select_edges(topology)
     clients = None
+    node_types = build_node_type_map(devices, clients, client_mode=args.client_scope)
     content = render_mermaid(
         edges,
         direction=args.direction,
-        node_types=build_node_type_map(devices, clients, client_mode=args.client_scope),
+        node_types=node_types,
         theme=mermaid_theme,
     )
     legend_style = _resolve_legend_style(args)
+    dual_theme = args.mkdocs_dual_theme and dark_mermaid_theme is not None
+    legend_header = "## Legend\n\n" if legend_style != "compact" else ""
+    if dual_theme and dark_mermaid_theme is not None:
+        dark_content = render_mermaid(
+            edges,
+            direction=args.direction,
+            node_types=node_types,
+            theme=dark_mermaid_theme,
+        )
+        map_block = _mkdocs_dual_mermaid_block(content, dark_content, base_class="unifi-mermaid")
+        legend_block = _mkdocs_dual_legend_block(
+            legend_style,
+            mermaid_theme=mermaid_theme,
+            dark_mermaid_theme=dark_mermaid_theme,
+            legend_scale=args.legend_scale,
+        )
+        dual_style = _mkdocs_dual_theme_style()
+    else:
+        map_block = _mkdocs_mermaid_block(content, class_name="unifi-mermaid")
+        legend_block = _mkdocs_single_legend_block(
+            legend_style,
+            mermaid_theme=mermaid_theme,
+            legend_scale=args.legend_scale,
+        )
+        dual_style = ""
+    timestamp_line = ""
+    if timestamp_zone.strip().lower() not in {"off", "none", "false"}:
+        try:
+            zone = ZoneInfo(timestamp_zone)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("Invalid mkdocs timestamp zone '%s': %s", timestamp_zone, exc)
+        else:
+            generated_at = datetime.now(zone).strftime("%Y-%m-%d %H:%M:%S %Z")
+            timestamp_line = f"Generated: {generated_at}\n\n"
+    return (
+        f"# UniFi network\n\n{timestamp_line}{dual_style}## Map\n\n{map_block}\n\n"
+        f"{legend_header}{legend_block}\n\n"
+        f"{render_device_port_overview(devices, port_map, client_ports=client_ports)}"
+    )
+
+
+def _mkdocs_mermaid_block(content: str, *, class_name: str) -> str:
+    return f'<div class="{class_name}">\n```mermaid\n{content}```\n</div>'
+
+
+def _mkdocs_dual_mermaid_block(
+    light_content: str,
+    dark_content: str,
+    *,
+    base_class: str,
+) -> str:
+    light = _mkdocs_mermaid_block(light_content, class_name=f"{base_class} {base_class}--light")
+    dark = _mkdocs_mermaid_block(dark_content, class_name=f"{base_class} {base_class}--dark")
+    return f"{light}\n{dark}"
+
+
+def _mkdocs_single_legend_block(
+    legend_style: str,
+    *,
+    mermaid_theme: MermaidTheme,
+    legend_scale: float,
+) -> str:
     if legend_style == "compact":
-        legend_block = (
+        return (
             '<div class="unifi-legend" data-unifi-legend>\n'
             + render_legend_compact(theme=mermaid_theme)
             + "</div>"
         )
-        legend_header = ""
-    else:
-        legend_block = (
-            "```mermaid\n"
-            + render_legend(theme=mermaid_theme, legend_scale=args.legend_scale)
-            + "```"
+    return "```mermaid\n" + render_legend(theme=mermaid_theme, legend_scale=legend_scale) + "```"
+
+
+def _mkdocs_dual_legend_block(
+    legend_style: str,
+    *,
+    mermaid_theme: MermaidTheme,
+    dark_mermaid_theme: MermaidTheme,
+    legend_scale: float,
+) -> str:
+    if legend_style == "compact":
+        light = (
+            '<div class="unifi-legend unifi-legend--light" data-unifi-legend>\n'
+            + render_legend_compact(theme=mermaid_theme)
+            + "</div>"
+        )
+        dark = (
+            '<div class="unifi-legend unifi-legend--dark" data-unifi-legend>\n'
+            + render_legend_compact(theme=dark_mermaid_theme)
+            + "</div>"
         )
-        legend_header = "## Legend\n\n"
+        return f"{light}\n{dark}"
+    light = _mkdocs_mermaid_block(
+        render_legend(theme=mermaid_theme, legend_scale=legend_scale),
+        class_name="unifi-legend unifi-legend--light",
+    )
+    dark = _mkdocs_mermaid_block(
+        render_legend(theme=dark_mermaid_theme, legend_scale=legend_scale),
+        class_name="unifi-legend unifi-legend--dark",
+    )
+    return f"{light}\n{dark}"
+
+
+def _mkdocs_dual_theme_style() -> str:
     return (
-        f"# UniFi network\n\n## Map\n\n```mermaid\n{content}```\n\n"
-        f"{legend_header}{legend_block}\n\n"
-        f"{render_device_port_overview(devices, port_map, client_ports=client_ports)}"
+        "<style>\n"
+        ".unifi-mermaid--light,.unifi-legend--light{display:none;}\n"
+        ".unifi-mermaid--dark,.unifi-legend--dark{display:none;}\n"
+        '[data-md-color-scheme="default"] .unifi-mermaid--light{display:block;}\n'
+        '[data-md-color-scheme="default"] .unifi-legend--light{display:block;}\n'
+        '[data-md-color-scheme="slate"] .unifi-mermaid--dark{display:block;}\n'
+        '[data-md-color-scheme="slate"] .unifi-legend--dark{display:block;}\n'
+        "</style>\n\n"
     )
 
 
@@ -446,7 +561,7 @@ def _write_mkdocs_sidebar_assets(output_path: str) -> None:
 def _render_svg_output(
     args: argparse.Namespace,
     devices: list[Device],
-    topology: object,
+    topology: TopologyResult,
     config: Config | None,
     site: str,
     svg_theme: SvgTheme,
@@ -480,87 +595,97 @@ def _render_svg_output(
     )
 
 
-def main(argv: list[str] | None = None) -> int:
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
-    args = _parse_args(argv)
-    if args.generate_mock:
-        try:
-            from ..io.mock_generate import MockOptions, mock_payload_json
-        except ImportError as exc:
-            logging.error("Faker is required for --generate-mock: %s", exc)
-            return 2
-        options = MockOptions(
-            seed=args.mock_seed,
-            switch_count=max(1, args.mock_switches),
-            ap_count=max(0, args.mock_aps),
-            wired_client_count=max(0, args.mock_wired_clients),
-            wireless_client_count=max(0, args.mock_wireless_clients),
-        )
-        content = mock_payload_json(options)
-        write_output(content, output_path=args.generate_mock, stdout=args.stdout)
-        return 0
-    mock_devices = None
-    mock_clients: list[object] | None = None
+def _handle_generate_mock(args: argparse.Namespace) -> int | None:
+    if not args.generate_mock:
+        return None
+    try:
+        from ..io.mock_generate import MockOptions, mock_payload_json
+    except ImportError as exc:
+        logging.error("Faker is required for --generate-mock: %s", exc)
+        return 2
+    options = MockOptions(
+        seed=args.mock_seed,
+        switch_count=max(1, args.mock_switches),
+        ap_count=max(0, args.mock_aps),
+        wired_client_count=max(0, args.mock_wired_clients),
+        wireless_client_count=max(0, args.mock_wireless_clients),
+    )
+    content = mock_payload_json(options)
+    write_output(content, output_path=args.generate_mock, stdout=args.stdout)
+    return 0
+
+
+def _load_runtime_context(
+    args: argparse.Namespace,
+) -> tuple[Config | None, str, list[object] | None, list[object] | None]:
     if args.mock_data:
         try:
             mock_devices, mock_clients = load_mock_data(args.mock_data)
         except Exception as exc:  # noqa: BLE001
-            logging.error("Failed to load mock data: %s", exc)
-            return 2
-        config = None
-        site = "mock"
-    else:
-        config = _load_config(args)
-        if config is None:
-            return 2
-        site = _resolve_site(args, config)
-    mermaid_theme, svg_theme = resolve_themes(args.theme_file)
+            raise ValueError(f"Failed to load mock data: {exc}") from exc
+        return None, "mock", mock_devices, mock_clients
+    config = _load_config(args)
+    if config is None:
+        raise ValueError("Config required to run")
+    site = _resolve_site(args, config)
+    return config, site, None, None
 
-    if args.legend_only:
-        content = _render_legend_only(args, mermaid_theme)
-        write_output(content, output_path=args.output, stdout=args.stdout)
-        return 0
-
-    if args.format == "lldp-md":
-        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_lldp_format(
+    args: argparse.Namespace,
+    *,
+    config: Config | None,
+    site: str,
+    mock_devices: list[object] | None,
+    mock_clients: list[object] | None,
+) -> int:
     try:
-        include_ports = True if args.format == "mkdocs" else None
-        devices, _gateways, topology = _build_topology_data(
+        _raw_devices, devices = _load_devices_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)
+        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(
@@ -573,25 +698,17 @@ def main(argv: list[str] | None = None) -> int:
             clients_override=mock_clients,
         )
     elif args.format == "mkdocs":
-        if args.mkdocs_sidebar_legend and not args.output:
-            logging.error("--mkdocs-sidebar-legend requires --output")
-            return 2
-        if args.mkdocs_sidebar_legend:
-            _write_mkdocs_sidebar_assets(args.output)
-        port_map = build_port_map(devices, only_unifi=args.only_unifi)
-        client_ports = None
-        if args.include_clients:
-            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
-            client_ports = build_client_port_map(devices, clients, client_mode=args.client_scope)
-        content = _render_mkdocs_output(
-            args, devices, topology, config, site, mermaid_theme, port_map, client_ports
+        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,
@@ -610,5 +727,133 @@ def main(argv: list[str] | None = None) -> int:
     return 0
 
 
+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
+
+
+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
+    return _render_mkdocs_output(
+        args,
+        devices,
+        topology,
+        mermaid_theme,
+        port_map,
+        client_ports,
+        args.mkdocs_timestamp_zone,
+        dark_mermaid_theme,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    args = _parse_args(argv)
+    mock_result = _handle_generate_mock(args)
+    if mock_result is not None:
+        return mock_result
+    try:
+        config, site, mock_devices, mock_clients = _load_runtime_context(args)
+    except ValueError as exc:
+        logging.error(str(exc))
+        return 2
+    mermaid_theme, svg_theme = resolve_themes(args.theme_file)
+
+    if args.legend_only:
+        content = _render_legend_only(args, mermaid_theme)
+        write_output(content, output_path=args.output, stdout=args.stdout)
+        return 0
+
+    if args.format == "lldp-md":
+        return _render_lldp_format(
+            args,
+            config=config,
+            site=site,
+            mock_devices=mock_devices,
+            mock_clients=mock_clients,
+        )
+
+    return _render_standard_format(
+        args,
+        config=config,
+        site=site,
+        mock_devices=mock_devices,
+        mock_clients=mock_clients,
+        mermaid_theme=mermaid_theme,
+        svg_theme=svg_theme,
+    )
+
+
 if __name__ == "__main__":
     raise SystemExit(main())

unifi_network_maps/io/debug.py

@@ -4,22 +4,32 @@ from __future__ import annotations
 
 import json
 import logging
+from collections.abc import Iterable, Sequence
 
-from ..model.topology import group_devices_by_type
+from ..model.topology import Device, group_devices_by_type
 
 logger = logging.getLogger(__name__)
 
 
-def device_to_dict(device: object) -> dict:
-    if hasattr(device, "to_dict"):
-        return device.to_dict()
+def device_to_dict(device: object) -> dict[str, object]:
+    to_dict = getattr(device, "to_dict", None)
+    if callable(to_dict):
+        result = to_dict()
+        if isinstance(result, dict):
+            return result
+        return {"repr": repr(result)}
     if hasattr(device, "__dict__"):
         return dict(device.__dict__)
+    if isinstance(device, dict):
+        return dict(device)
     return {"repr": repr(device)}
 
 
 def debug_dump_devices(
-    raw_devices: list[object], normalized: list[object], *, sample_count: int
+    raw_devices: Sequence[object],
+    normalized: Iterable[Device],
+    *,
+    sample_count: int,
 ) -> None:
     name_to_device: dict[str, object] = {}
     for device in raw_devices:

unifi_network_maps/io/export.py

@@ -2,12 +2,31 @@
 
 from __future__ import annotations
 
+import os
 import sys
+import tempfile
 from pathlib import Path
 
 
 def write_output(content: str, *, output_path: str | None, stdout: bool) -> None:
     if output_path:
-        Path(output_path).write_text(content, encoding="utf-8")
+        _write_atomic(Path(output_path), content)
     if stdout or not output_path:
         sys.stdout.write(content)
+
+
+def _write_atomic(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(
+        mode="w",
+        encoding="utf-8",
+        dir=str(path.parent),
+        prefix=f".{path.name}.",
+        suffix=".tmp",
+        delete=False,
+    ) as temp_file:
+        temp_file.write(content)
+        temp_file.flush()
+        os.fsync(temp_file.fileno())
+        tmp_path = Path(temp_file.name)
+    tmp_path.replace(path)