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

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

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

unifi_network_maps/io/debug.py

@@ -0,0 +1,60 @@
+"""Debug helpers for dumping device data."""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Iterable, Sequence
+
+from ..model.topology import Device, group_devices_by_type
+
+logger = logging.getLogger(__name__)
+
+
+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: Sequence[object],
+    normalized: Iterable[Device],
+    *,
+    sample_count: int,
+) -> None:
+    name_to_device: dict[str, object] = {}
+    for device in raw_devices:
+        name = getattr(device, "name", None)
+        if name:
+            name_to_device[name] = device
+
+    groups = group_devices_by_type(normalized)
+    gateways = groups.get("gateway", [])
+    samples: list[str] = []
+    for group in ("switch", "ap", "other"):
+        for name in groups.get(group, []):
+            if name not in gateways:
+                samples.append(name)
+            if len(samples) >= sample_count:
+                break
+        if len(samples) >= sample_count:
+            break
+
+    selected_names = gateways[:1] + samples
+    payload = []
+    for name in selected_names:
+        device = name_to_device.get(name)
+        if device is None:
+            continue
+        payload.append({"name": name, "data": device_to_dict(device)})
+
+    logger.info("Debug dump devices: %s", json.dumps(payload, indent=2, sort_keys=True))

unifi_network_maps/io/export.py

@@ -0,0 +1,32 @@
+"""Output helpers for files and stdout."""
+
+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:
+        _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)

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",
+    )

unifi_network_maps/io/mock_data.py

@@ -0,0 +1,23 @@
+"""Load mock UniFi data from JSON fixtures."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def _as_list(value: object, name: str) -> list[object]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    raise ValueError(f"Mock data field '{name}' must be a list")
+
+
+def load_mock_data(path: str) -> tuple[list[object], list[object]]:
+    payload = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError("Mock data must be a JSON object")
+    devices = _as_list(payload.get("devices"), "devices")
+    clients = _as_list(payload.get("clients"), "clients")
+    return devices, clients

unifi_network_maps/io/mock_generate.py

@@ -0,0 +1,7 @@
+"""Generate mock UniFi data using Faker."""
+
+from __future__ import annotations
+
+from ..model.mock import MockOptions, generate_mock_payload, mock_payload_json
+
+__all__ = ["MockOptions", "generate_mock_payload", "mock_payload_json"]

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_network_maps/model/lldp.py

@@ -0,0 +1,99 @@
+"""LLDP parsing and port label helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .ports import extract_port_number, normalize_port_label
+
+
+@dataclass(frozen=True)
+class LLDPEntry:
+    chassis_id: str
+    port_id: str
+    port_desc: str | None = None
+    local_port_name: str | None = None
+    local_port_idx: int | None = None
+
+
+def coerce_lldp(entry: object) -> LLDPEntry:
+    if isinstance(entry, dict):
+        chassis_id = entry.get("chassis_id") or entry.get("chassisId")
+        port_id = entry.get("port_id") or entry.get("portId")
+        port_desc = (
+            entry.get("port_desc")
+            or entry.get("portDesc")
+            or entry.get("port_descr")
+            or entry.get("portDescr")
+        )
+        local_port_name = entry.get("local_port_name") or entry.get("localPortName")
+        local_port_idx = entry.get("local_port_idx") or entry.get("localPortIdx")
+    else:
+        chassis_id = getattr(entry, "chassis_id", None) or getattr(entry, "chassisId", None)
+        port_id = getattr(entry, "port_id", None) or getattr(entry, "portId", None)
+        port_desc = (
+            getattr(entry, "port_desc", None)
+            or getattr(entry, "portDesc", None)
+            or getattr(entry, "port_descr", None)
+            or getattr(entry, "portDescr", None)
+        )
+        local_port_name = getattr(entry, "local_port_name", None) or getattr(
+            entry, "localPortName", None
+        )
+        local_port_idx = getattr(entry, "local_port_idx", None) or getattr(
+            entry, "localPortIdx", None
+        )
+    if not chassis_id or not port_id:
+        raise ValueError("LLDP entry missing chassis_id or port_id")
+    return LLDPEntry(
+        chassis_id=str(chassis_id),
+        port_id=str(port_id),
+        port_desc=str(port_desc) if port_desc else None,
+        local_port_name=str(local_port_name) if local_port_name else None,
+        local_port_idx=int(local_port_idx) if local_port_idx is not None else None,
+    )
+
+
+def _looks_like_mac(value: str | None) -> bool:
+    if not value:
+        return False
+    cleaned = value.strip().lower()
+    if cleaned.count(":") == 5:
+        return all(
+            len(part) == 2 and all(ch in "0123456789abcdef" for ch in part)
+            for part in cleaned.split(":")
+        )
+    return False
+
+
+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
+    )
+
+    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)
+    if number is None:
+        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:
+        return f"Port {number}"
+    if name:
+        return name
+    if desc:
+        return desc
+    return None