unifi-network-maps 1.4.3__tar.gz → 1.4.5__tar.gz

{unifi_network_maps-1.4.3 → unifi_network_maps-1.4.5}/CHANGELOG.md

@@ -2,8 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
-## v1.4.3 - (unreleased)
-- planned: POC for HA integration
+
+## 1.4.5 - (2026-01-11)
+- Refactored CLI orchestration into focused CLI/render/runtime modules.
+- Extracted MkDocs rendering and sidebar asset output into dedicated modules.
+- Moved mock generation into the model layer with a thin IO facade.
+- Centralized legend rendering helpers and shared markdown table utilities.
+- Added Jinja2 templating for MkDocs output, Mermaid legend blocks, and Markdown sections.
+- Moved MkDocs sidebar assets and legend HTML blocks into reusable templates.
+- Enabled Jinja2 autoescaping for HTML templates and marked trusted HTML blocks safe.
+
+## v1.4.4 - (2026-01-10)
+- Improved dark theme Mermaid readability (labels + link borders).
+- Fixed MkDocs sidebar legend duplication with dual-theme output.
+- Added smoke tests for dual-theme MkDocs sidebar legend output.
 
 ## v1.4.2 - 2026-01-10
 - Added static code analysis and stricter type-checking

{unifi_network_maps-1.4.3 → unifi_network_maps-1.4.5}/CONTRIBUTING.md

@@ -43,6 +43,7 @@ Notes:
 - Contract tests use fixtures in `tests/test_contract_unifi.py` and run in CI.
 - Live contract tests require `UNIFI_CONTRACT_LIVE=1` plus UniFi env vars.
 - BDD tests live in `features/` and run via `behave` (included in `make ci`).
+- Render helper structure is documented in `src/unifi_network_maps/render/README.md`.
 
 ## Release
 
@@ -86,4 +87,4 @@ See `LICENSES.md` for third-party license info.
   - A clean render pipeline that can power multiple export targets.
 
   So we’re not duplicating a packaged workflow; we’re combining data + topology modeling + diagram output + documentation/export in a way I haven’t seen in one place.
-  
+  

{unifi_network_maps-1.4.3 → unifi_network_maps-1.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unifi-network-maps
-Version: 1.4.3
+Version: 1.4.5
 Summary: Dynamic UniFi -> network maps in mermaid or svg
 Author: Merlijn
 License-Expression: MIT
@@ -23,6 +23,7 @@ License-File: LICENSE
 Requires-Dist: unifi-controller-api==0.3.2
 Requires-Dist: python-dotenv==1.2.1
 Requires-Dist: PyYAML==6.0.3
+Requires-Dist: Jinja2==3.1.6
 Provides-Extra: dev
 Requires-Dist: Faker==40.1.0; extra == "dev"
 Requires-Dist: behave==1.3.3; extra == "dev"

{unifi_network_maps-1.4.3 → unifi_network_maps-1.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unifi-network-maps"
-version = "1.4.3"
+version = "1.4.5"
 description = "Dynamic UniFi -> network maps in mermaid or svg"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -26,6 +26,7 @@ dependencies = [
   "unifi-controller-api==0.3.2",
   "python-dotenv==1.2.1",
   "PyYAML==6.0.3",
+  "Jinja2==3.1.6",
 ]
 
 [project.urls]
@@ -96,6 +97,7 @@ package-dir = {"" = "src"}
   "assets/icons/*.svg",
   "assets/icons/isometric/*.svg",
   "assets/icons/isometric/ISOPACKS_LICENSE",
+  "render/templates/*.j2",
 ]
 
 [tool.setuptools.packages.find]

unifi_network_maps-1.4.5/src/unifi_network_maps/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.4.5"

{unifi_network_maps-1.4.3 → unifi_network_maps-1.4.5}/src/unifi_network_maps/assets/themes/dark.yaml

@@ -15,8 +15,8 @@ mermaid:
     other:
       fill: "#2a2a2a"
       stroke: "#9e9e9e"
-  node_text: "#111111"
-  edge_label_border: "#111111"
+  node_text: "#f5f5f5"
+  edge_label_border: "#e6e6e6"
   edge_label_border_width: 2
   poe_link: "#64b5f6"
   poe_link_width: 2

unifi_network_maps-1.4.5/src/unifi_network_maps/cli/__init__.py

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

unifi_network_maps-1.4.5/src/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-1.4.5/src/unifi_network_maps/cli/main.py

@@ -0,0 +1,130 @@
+"""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
+    mermaid_theme, svg_theme = resolve_themes(args.theme_file)
+
+    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-1.4.5/src/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