unifi-network-maps 1.2.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

unifi_network_maps/__init__.py

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

unifi_network_maps/adapters/__init__.py

@@ -0,0 +1 @@
+"""Package module."""

{unifi_mermaid → unifi_network_maps/adapters}/config.py

@@ -26,7 +26,13 @@ class Config:
     verify_ssl: bool
 
     @classmethod
-    def from_env(cls) -> Config:
+    def from_env(cls, *, env_file: str | None = None) -> Config:
+        if env_file:
+            try:
+                from dotenv import load_dotenv
+            except ImportError:
+                raise ValueError("python-dotenv required for --env-file") from None
+            load_dotenv(dotenv_path=env_file)
         url = os.environ.get("UNIFI_URL", "").strip()
         site = os.environ.get("UNIFI_SITE", "default").strip()
         user = os.environ.get("UNIFI_USER", "").strip()

{unifi_mermaid → unifi_network_maps/adapters}/unifi.py

@@ -20,7 +20,7 @@ logger = logging.getLogger(__name__)
 
 
 def _cache_dir() -> Path:
-    return Path(os.environ.get("UNIFI_CACHE_DIR", ".cache/unifi_mermaid"))
+    return Path(os.environ.get("UNIFI_CACHE_DIR", ".cache/unifi_network_maps"))
 
 
 def _cache_ttl_seconds() -> int:

unifi_network_maps/assets/themes/dark.yaml

@@ -0,0 +1,47 @@
+mermaid:
+  nodes:
+    gateway:
+      fill: "#5c3b00"
+      stroke: "#ffb347"
+    switch:
+      fill: "#0f2b3d"
+      stroke: "#5dade2"
+    ap:
+      fill: "#0f3b2d"
+      stroke: "#2ecc71"
+    client:
+      fill: "#2b1f3b"
+      stroke: "#b084ff"
+    other:
+      fill: "#2a2a2a"
+      stroke: "#9e9e9e"
+  poe_link: "#64b5f6"
+  poe_link_width: 2
+  poe_link_arrow: "none"
+  standard_link: "#66bb6a"
+  standard_link_width: 2
+  standard_link_arrow: "none"
+svg:
+  links:
+    standard:
+      from: "#66bb6a"
+      to: "#2e7d32"
+    poe:
+      from: "#64b5f6"
+      to: "#1e88e5"
+  nodes:
+    gateway:
+      from: "#5c3b00"
+      to: "#3e2a00"
+    switch:
+      from: "#0f2b3d"
+      to: "#0a1f2c"
+    ap:
+      from: "#0f3b2d"
+      to: "#0b2a20"
+    client:
+      from: "#2b1f3b"
+      to: "#20162b"
+    other:
+      from: "#2a2a2a"
+      to: "#1f1f1f"

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,41 @@
+"""CLI package facade."""
+
+from .main import (
+    Config,
+    SvgOptions,
+    build_client_edges,
+    build_device_index,
+    build_node_type_map,
+    build_topology,
+    debug_dump_devices,
+    fetch_clients,
+    fetch_devices,
+    group_devices_by_type,
+    main,
+    normalize_devices,
+    render_legend,
+    render_mermaid,
+    render_svg,
+    resolve_themes,
+    write_output,
+)
+
+__all__ = [
+    "Config",
+    "SvgOptions",
+    "build_client_edges",
+    "build_device_index",
+    "build_node_type_map",
+    "build_topology",
+    "debug_dump_devices",
+    "fetch_clients",
+    "fetch_devices",
+    "group_devices_by_type",
+    "main",
+    "normalize_devices",
+    "render_legend",
+    "render_mermaid",
+    "render_svg",
+    "resolve_themes",
+    "write_output",
+]

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/main.py

@@ -0,0 +1,281 @@
+"""CLI entry point."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+
+from ..adapters.config import Config
+from ..adapters.unifi import fetch_clients, fetch_devices
+from ..io.debug import debug_dump_devices
+from ..io.export import write_output
+from ..model.topology import (
+    Device,
+    build_client_edges,
+    build_device_index,
+    build_node_type_map,
+    build_topology,
+    group_devices_by_type,
+    normalize_devices,
+)
+from ..render.mermaid import render_legend, render_mermaid
+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
+
+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 _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_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)",
+    )
+
+
+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(
+        "--only-unifi", action="store_true", help="Only include neighbors that are UniFi devices"
+    )
+
+
+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-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"],
+        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")
+
+
+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)",
+    )
+
+
+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 _render_legend_only(args: argparse.Namespace, mermaid_theme: MermaidTheme) -> str:
+    content = render_legend(theme=mermaid_theme)
+    if args.markdown:
+        content = f"""```mermaid
+{content}```
+"""
+    return content
+
+
+def _build_topology_data(
+    args: argparse.Namespace, config: Config, site: str
+) -> tuple[list[Device], list[str], object]:
+    raw_devices = list(fetch_devices(config, site=site, detailed=True))
+    devices = normalize_devices(raw_devices)
+    if args.debug_dump:
+        debug_dump_devices(raw_devices, devices, sample_count=max(0, args.debug_sample))
+    groups_for_rank = group_devices_by_type(devices)
+    gateways = groups_for_rank.get("gateway", [])
+    topology = build_topology(
+        devices,
+        include_ports=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,
+    site: str,
+) -> tuple[list, list | None]:
+    clients = None
+    if args.include_clients:
+        clients = list(fetch_clients(config, site=site))
+        device_index = build_device_index(devices)
+        edges = edges + build_client_edges(clients, device_index, include_ports=args.include_ports)
+    return edges, clients
+
+
+def _select_edges(topology: object) -> 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 _render_mermaid_output(
+    args: argparse.Namespace,
+    devices: list[Device],
+    topology: object,
+    config: Config,
+    site: str,
+    mermaid_theme: MermaidTheme,
+) -> str:
+    edges, _has_tree = _select_edges(topology)
+    edges, clients = _build_edges_with_clients(args, edges, devices, config, site)
+    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),
+        theme=mermaid_theme,
+    )
+    if args.markdown:
+        content = f"""```mermaid
+{content}```
+"""
+    return content
+
+
+def _render_svg_output(
+    args: argparse.Namespace,
+    devices: list[Device],
+    topology: object,
+    config: Config,
+    site: str,
+    svg_theme: SvgTheme,
+) -> str:
+    edges, _has_tree = _select_edges(topology)
+    edges, clients = _build_edges_with_clients(args, edges, devices, config, site)
+    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),
+            options=options,
+            theme=svg_theme,
+        )
+    return render_svg(
+        edges,
+        node_types=build_node_type_map(devices, clients),
+        options=options,
+        theme=svg_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)
+    config = _load_config(args)
+    if config is None:
+        return 2
+    site = _resolve_site(args, config)
+    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
+
+    try:
+        devices, _gateways, topology = _build_topology_data(args, config, site)
+    except Exception as exc:
+        logging.error("Failed to build topology: %s", exc)
+        return 1
+
+    if args.format == "mermaid":
+        content = _render_mermaid_output(args, devices, topology, config, site, mermaid_theme)
+    elif args.format in {"svg", "svg-iso"}:
+        content = _render_svg_output(args, devices, topology, config, site, svg_theme)
+    else:
+        logging.error("Unsupported format: %s", args.format)
+        return 2
+
+    write_output(content, output_path=args.output, stdout=args.stdout)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

unifi_network_maps/io/__init__.py

@@ -0,0 +1 @@
+"""Package module."""

{unifi_mermaid → unifi_network_maps/io}/debug.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import json
 import logging
 
-from .topology import group_devices_by_type
+from ..model.topology import group_devices_by_type
 
 logger = logging.getLogger(__name__)
 

unifi_network_maps/model/__init__.py

@@ -0,0 +1 @@
+"""Package module."""

unifi_network_maps/model/labels.py

@@ -0,0 +1,35 @@
+"""Edge label helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+
+def compose_port_label(left: str, right: str, port_map: dict[tuple[str, str], str]) -> str | None:
+    left_label = port_map.get((left, right))
+    right_label = port_map.get((right, left))
+    if left_label and right_label:
+        return f"{left}: {left_label} <-> {right}: {right_label}"
+    if left_label:
+        return f"{left}: {left_label} <-> {right}: ?"
+    if right_label:
+        return f"{left}: ? <-> {right}: {right_label}"
+    return None
+
+
+def order_edge_names(
+    left: str,
+    right: str,
+    port_map: dict[tuple[str, str], str],
+    rank_for_name: Callable[[str], int],
+) -> tuple[str, str]:
+    left_label = port_map.get((left, right))
+    right_label = port_map.get((right, left))
+    if left_label is None and right_label is not None:
+        return (right, left)
+    if left_label and right_label:
+        left_rank = rank_for_name(left)
+        right_rank = rank_for_name(right)
+        if (left_rank, left.lower()) > (right_rank, right.lower()):
+            return (right, left)
+    return (left, right)

{unifi_mermaid → unifi_network_maps/model}/lldp.py

@@ -2,9 +2,10 @@
 
 from __future__ import annotations
 
-import re
 from dataclasses import dataclass
 
+from .ports import extract_port_number, normalize_port_label
+
 
 @dataclass(frozen=True)
 class LLDPEntry:
@@ -51,43 +52,28 @@ def _looks_like_mac(value: str | None) -> bool:
     return False
 
 
-def _extract_port_number(label: str | None) -> int | None:
-    if not label:
-        return None
-    match = re.search(r"(?:^|[^0-9])(?:port|eth)\s*([0-9]+)", label.strip(), re.IGNORECASE)
-    if match:
-        return int(match.group(1))
-    return None
-
-
-def _normalize_port_label(label: str) -> str:
-    trimmed = label.strip()
-    number = _extract_port_number(trimmed)
-    if number is not None:
-        return f"Port {number}"
-    return trimmed
-
+def _port_label_parts(entry: LLDPEntry) -> tuple[int | None, str | None, str | None]:
+    number = entry.local_port_idx
+    name = normalize_port_label(entry.local_port_name) if entry.local_port_name else None
+    desc = (
+        entry.port_desc.strip()
+        if entry.port_desc and not _looks_like_mac(entry.port_desc)
+        else None
+    )
 
-def local_port_label(entry: LLDPEntry) -> str | None:
-    number = None
-    name = None
-    desc = None
-
-    if entry.local_port_idx is not None:
-        number = entry.local_port_idx
-    if entry.local_port_name:
-        name = _normalize_port_label(entry.local_port_name)
-    if entry.port_desc and not _looks_like_mac(entry.port_desc):
-        desc = entry.port_desc.strip()
-    if entry.port_id and not _looks_like_mac(entry.port_id):
-        if name is None:
-            name = _normalize_port_label(entry.port_id)
+    if entry.port_id and not _looks_like_mac(entry.port_id) and name is None:
+        name = normalize_port_label(entry.port_id)
 
     if number is None:
-        number = _extract_port_number(name)
+        number = extract_port_number(name)
     if number is None:
-        number = _extract_port_number(desc)
+        number = extract_port_number(desc)
 
+    return number, name, desc
+
+
+def local_port_label(entry: LLDPEntry) -> str | None:
+    number, name, desc = _port_label_parts(entry)
     if number is not None and desc:
         return f"Port {number} ({desc})"
     if number is not None:

unifi_network_maps/model/ports.py

@@ -0,0 +1,23 @@
+"""Port parsing helpers shared across modules."""
+
+from __future__ import annotations
+
+import re
+
+
+def extract_port_number(label: str | None) -> int | None:
+    if not label:
+        return None
+    # Matches: "Port 3", "eth1"; non-matches: "wan", "portX".
+    match = re.search(r"(?:^|[^0-9])(?:port|eth)\s*([0-9]+)", label.strip(), re.IGNORECASE)
+    if match:
+        return int(match.group(1))
+    return None
+
+
+def normalize_port_label(label: str) -> str:
+    trimmed = label.strip()
+    number = extract_port_number(trimmed)
+    if number is not None:
+        return f"Port {number}"
+    return trimmed