unifi-network-maps 1.4.11__py3-none-any.whl

unifi_network_maps/assets/themes/default.yaml

@@ -0,0 +1,47 @@
+mermaid:
+  nodes:
+    gateway:
+      fill: "#ffe3b3"
+      stroke: "#d98300"
+    switch:
+      fill: "#d6ecff"
+      stroke: "#3a7bd5"
+    ap:
+      fill: "#d7f5e7"
+      stroke: "#27ae60"
+    client:
+      fill: "#f2e5ff"
+      stroke: "#7f3fbf"
+    other:
+      fill: "#eeeeee"
+      stroke: "#8f8f8f"
+  poe_link: "#1e88e5"
+  poe_link_width: 2
+  poe_link_arrow: "none"
+  standard_link: "#2ecc71"
+  standard_link_width: 2
+  standard_link_arrow: "none"
+svg:
+  links:
+    standard:
+      from: "#2ecc71"
+      to: "#1b8f4a"
+    poe:
+      from: "#1e88e5"
+      to: "#0d47a1"
+  nodes:
+    gateway:
+      from: "#ffe3b3"
+      to: "#f7c77b"
+    switch:
+      from: "#d6ecff"
+      to: "#b6dcff"
+    ap:
+      from: "#d7f5e7"
+      to: "#b8f0d2"
+    client:
+      from: "#f2e5ff"
+      to: "#e0c9ff"
+    other:
+      from: "#eeeeee"
+      to: "#d7d7d7"

unifi_network_maps/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI package facade."""
+
+from .main import main
+
+__all__ = ["main"]

unifi_network_maps/cli/__main__.py

@@ -0,0 +1,8 @@
+"""CLI module entry point."""
+
+from __future__ import annotations
+
+from .main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

unifi_network_maps/cli/args.py

@@ -0,0 +1,166 @@
+"""CLI argument definitions."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Generate network maps from UniFi LLDP data, as mermaid or SVG"
+    )
+    add_source_args(parser.add_argument_group("Source"))
+    add_mock_args(parser.add_argument_group("Mock"))
+    add_functional_args(parser.add_argument_group("Functional"))
+    add_mermaid_args(parser.add_argument_group("Mermaid"))
+    add_svg_args(parser.add_argument_group("SVG"))
+    add_general_render_args(parser.add_argument_group("Output"))
+    add_debug_args(parser.add_argument_group("Debug"))
+    return parser
+
+
+def add_source_args(parser: argparse._ArgumentGroup) -> None:
+    parser.add_argument("--site", default=None, help="UniFi site name (overrides UNIFI_SITE)")
+    parser.add_argument(
+        "--env-file",
+        default=None,
+        help="Path to .env file (overrides default .env discovery)",
+    )
+    parser.add_argument(
+        "--mock-data",
+        default=None,
+        help="Path to mock data JSON (skips UniFi API calls)",
+    )
+
+
+def add_mock_args(parser: argparse._ArgumentGroup) -> None:
+    parser.add_argument(
+        "--generate-mock",
+        default=None,
+        help="Write mock data JSON to the given path and exit",
+    )
+    parser.add_argument("--mock-seed", type=int, default=1337, help="Seed for mock generation")
+    parser.add_argument(
+        "--mock-switches",
+        type=int,
+        default=1,
+        help="Number of switches to generate (default: 1)",
+    )
+    parser.add_argument(
+        "--mock-aps",
+        type=int,
+        default=2,
+        help="Number of access points to generate (default: 2)",
+    )
+    parser.add_argument(
+        "--mock-wired-clients",
+        type=int,
+        default=2,
+        help="Number of wired clients to generate (default: 2)",
+    )
+    parser.add_argument(
+        "--mock-wireless-clients",
+        type=int,
+        default=2,
+        help="Number of wireless clients to generate (default: 2)",
+    )
+
+
+def add_functional_args(parser: argparse._ArgumentGroup) -> None:
+    parser.add_argument("--include-ports", action="store_true", help="Include port labels in edges")
+    parser.add_argument(
+        "--include-clients",
+        action="store_true",
+        help="Include active clients as leaf nodes",
+    )
+    parser.add_argument(
+        "--client-scope",
+        choices=["wired", "wireless", "all"],
+        default="wired",
+        help="Client types to include (default: wired)",
+    )
+    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:
+    parser.add_argument("--direction", default="TB", choices=["LR", "TB"], help="Mermaid direction")
+    parser.add_argument(
+        "--group-by-type",
+        action="store_true",
+        help="Group nodes by gateway/switch/ap in Mermaid subgraphs",
+    )
+    parser.add_argument(
+        "--legend-scale",
+        type=float,
+        default=1.0,
+        help="Scale legend font/link sizes for Mermaid output (default: 1.0)",
+    )
+    parser.add_argument(
+        "--legend-style",
+        default="auto",
+        choices=["auto", "compact", "diagram"],
+        help="Legend style (auto uses compact for mkdocs, diagram otherwise)",
+    )
+    parser.add_argument(
+        "--legend-only",
+        action="store_true",
+        help="Render only the legend as a separate Mermaid graph",
+    )
+
+
+def add_svg_args(parser: argparse._ArgumentGroup) -> None:
+    parser.add_argument("--svg-width", type=int, default=None, help="SVG width override")
+    parser.add_argument("--svg-height", type=int, default=None, help="SVG height override")
+    parser.add_argument("--theme-file", default=None, help="Path to theme YAML file")
+
+
+def add_general_render_args(parser: argparse._ArgumentGroup) -> None:
+    parser.add_argument(
+        "--format",
+        default="mermaid",
+        choices=["mermaid", "svg", "svg-iso", "lldp-md", "mkdocs"],
+        help="Output format",
+    )
+    parser.add_argument(
+        "--markdown",
+        action="store_true",
+        help="Wrap output in a Markdown mermaid code fence for notes tools like Obsidian",
+    )
+    parser.add_argument("--output", default=None, help="Output file path")
+    parser.add_argument("--stdout", action="store_true", help="Write output to stdout")
+    parser.add_argument(
+        "--mkdocs-sidebar-legend",
+        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:
+    parser.add_argument(
+        "--debug-dump",
+        action="store_true",
+        help="Dump gateway and sample device data to stderr for debugging",
+    )
+    parser.add_argument(
+        "--debug-sample",
+        type=int,
+        default=2,
+        help="Number of non-gateway devices to include in debug dump (default: 2)",
+    )

unifi_network_maps/cli/main.py

@@ -0,0 +1,134 @@
+"""CLI entry point."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+
+from ..adapters.config import Config
+from ..io.export import write_output
+from ..io.mock_data import load_mock_data
+from ..render.legend import render_legend_only, resolve_legend_style
+from ..render.theme import resolve_themes
+from .args import build_parser
+from .render import render_lldp_format, render_standard_format
+
+logger = logging.getLogger(__name__)
+
+
+def _load_dotenv(env_file: str | None = None) -> None:
+    try:
+        from dotenv import load_dotenv
+    except ImportError:
+        logger.info("python-dotenv not installed; skipping .env loading")
+        return
+    load_dotenv(dotenv_path=env_file) if env_file else load_dotenv()
+
+
+def _parse_args(argv: list[str] | None) -> argparse.Namespace:
+    parser = build_parser()
+    return parser.parse_args(argv)
+
+
+def _load_config(args: argparse.Namespace) -> Config | None:
+    try:
+        _load_dotenv(args.env_file)
+        return Config.from_env(env_file=args.env_file)
+    except ValueError as exc:
+        logging.error(str(exc))
+        return None
+
+
+def _resolve_site(args: argparse.Namespace, config: Config) -> str:
+    return args.site or config.site
+
+
+def _handle_generate_mock(args: argparse.Namespace) -> int | None:
+    if not args.generate_mock:
+        return None
+    try:
+        from ..model.mock 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
+            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
+
+
+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
+    try:
+        mermaid_theme, svg_theme = resolve_themes(args.theme_file)
+    except Exception as exc:  # noqa: BLE001
+        logging.error("Failed to load theme file: %s", exc)
+        return 2
+
+    if args.legend_only:
+        legend_style = resolve_legend_style(
+            format_name=args.format,
+            legend_style=args.legend_style,
+        )
+        content = render_legend_only(
+            legend_style=legend_style,
+            legend_scale=args.legend_scale,
+            markdown=args.markdown,
+            theme=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/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