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

unifi_network_maps/render/lldp_md.py

@@ -0,0 +1,352 @@
+"""Render LLDP data as Markdown tables."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from ..model.lldp import LLDPEntry, local_port_label
+from ..model.ports import extract_port_number
+from ..model.topology import Device, build_client_port_map, build_device_index, build_port_map
+from .device_ports_md import render_device_port_details
+from .markdown_tables import markdown_table_lines
+from .templating import render_template
+
+
+def _normalize_mac(value: str) -> str:
+    return value.strip().lower()
+
+
+def _client_field(client: object, name: str) -> object | None:
+    if isinstance(client, dict):
+        return client.get(name)
+    return getattr(client, name, None)
+
+
+def _client_display_name(client: object) -> str | None:
+    for key in ("name", "hostname", "mac"):
+        value = _client_field(client, key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def _client_uplink_mac(client: object) -> str | None:
+    for key in ("ap_mac", "sw_mac", "uplink_mac", "uplink_device_mac", "last_uplink_mac"):
+        value = _client_field(client, key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    for key in ("uplink", "last_uplink"):
+        nested = _client_field(client, key)
+        if isinstance(nested, dict):
+            value = nested.get("uplink_mac") or nested.get("uplink_device_mac")
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+    return None
+
+
+def _client_uplink_port(client: object) -> int | None:
+    for value in _client_port_values(client):
+        parsed = _parse_port_value(value)
+        if parsed is not None:
+            return parsed
+    return None
+
+
+def _client_port_values(client: object) -> Iterable[object | None]:
+    for key in ("uplink_remote_port", "sw_port", "ap_port", "port_idx"):
+        yield _client_field(client, key)
+    for key in ("uplink", "last_uplink"):
+        nested = _client_field(client, key)
+        if isinstance(nested, dict):
+            for nested_key in ("uplink_remote_port", "port_idx"):
+                yield nested.get(nested_key)
+
+
+def _parse_port_value(value: object | None) -> int | None:
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        stripped = value.strip()
+        if stripped.isdigit():
+            return int(stripped)
+        return extract_port_number(stripped)
+    return None
+
+
+def _client_is_wired(client: object) -> bool:
+    return bool(_client_field(client, "is_wired"))
+
+
+def _client_matches_mode(client: object, mode: str) -> bool:
+    wired = _client_is_wired(client)
+    if mode == "all":
+        return True
+    if mode == "wireless":
+        return not wired
+    return wired
+
+
+def _lldp_sort_key(entry: LLDPEntry) -> tuple[int, str, str]:
+    port_label = local_port_label(entry) or ""
+    port_number = "".join(ch for ch in port_label if ch.isdigit())
+    return (int(port_number or 0), port_label, entry.port_id)
+
+
+def _port_summary(device: Device) -> str:
+    ports = [port for port in device.port_table if port.port_idx is not None]
+    if not ports:
+        return "-"
+    total_ports = len(ports)
+    poe_capable = sum(1 for port in ports if port.port_poe or port.poe_enable)
+    poe_active = sum(1 for port in ports if device.poe_ports.get(port.port_idx or -1))
+    total_power = sum(port.poe_power or 0.0 for port in ports)
+    summary = f"Total {total_ports}, PoE {poe_capable} (active {poe_active})"
+    if total_power > 0:
+        summary = f"{summary}, {total_power:.2f}W"
+    return summary
+
+
+def _poe_summary(device: Device) -> str:
+    ports = [port for port in device.port_table if port.port_idx is not None]
+    if not ports:
+        return "-"
+    poe_capable = sum(1 for port in ports if port.port_poe or port.poe_enable)
+    poe_active = sum(1 for port in ports if (port.poe_power or 0.0) > 0 or port.poe_good)
+    total_power = sum(port.poe_power or 0.0 for port in ports)
+    summary = f"{poe_capable} capable, {poe_active} active"
+    if total_power > 0:
+        summary = f"{summary}, {total_power:.2f}W"
+    return summary
+
+
+def _uplink_summary(device: Device) -> str:
+    uplink = device.uplink or device.last_uplink
+    if not uplink:
+        return "-"
+    name = uplink.name or uplink.mac or "Unknown"
+    if uplink.port is not None:
+        return f"{name} (Port {uplink.port})"
+    return name
+
+
+def _client_summary(
+    device: Device, client_rows: dict[str, list[tuple[str, str | None]]]
+) -> tuple[str, str]:
+    rows = client_rows.get(device.name)
+    if rows is None:
+        return "-", "-"
+    count = len(rows)
+    names = [name for name, _port in rows]
+    sample = ", ".join(names[:3])
+    if len(names) > 3:
+        sample = f"{sample}, ..."
+    return str(count), sample or "-"
+
+
+def _details_table_lines(
+    device: Device,
+    client_rows: dict[str, list[tuple[str, str | None]]],
+    client_mode: str,
+) -> list[str]:
+    wired_count, client_sample = _client_summary(device, client_rows)
+    client_label = f"Clients ({client_mode})"
+    rows = [
+        ["Model", _escape_cell(device.model_name or device.type or "-")],
+        ["Type", _escape_cell(device.type or "-")],
+        ["IP", _escape_cell(device.ip or "-")],
+        ["MAC", _escape_cell(device.mac or "-")],
+        ["Firmware", _escape_cell(device.version or "-")],
+        ["Uplink", _escape_cell(_uplink_summary(device))],
+        ["Ports", _escape_cell(_port_summary(device))],
+        ["PoE", _escape_cell(_poe_summary(device))],
+        [client_label, _escape_cell(wired_count)],
+        ["Client examples", _escape_cell(client_sample)],
+    ]
+    lines = ["### Details", ""]
+    lines.extend(markdown_table_lines(["Field", "Value"], rows))
+    return lines
+
+
+def _lldp_rows(
+    entries: Iterable[LLDPEntry],
+    device_index: dict[str, str],
+) -> list[list[str]]:
+    rows: list[list[str]] = []
+    for entry in sorted(entries, key=_lldp_sort_key):
+        local_label = local_port_label(entry) or "?"
+        peer_name = device_index.get(_normalize_mac(entry.chassis_id), "")
+        peer_port = entry.port_id or "?"
+        port_desc = entry.port_desc or ""
+        rows.append(
+            [
+                local_label,
+                peer_name or "-",
+                peer_port,
+                entry.chassis_id,
+                port_desc or "-",
+            ]
+        )
+    return rows
+
+
+def _escape_cell(value: str) -> str:
+    return value.replace("|", "\\|")
+
+
+def _client_rows(
+    clients: Iterable[object],
+    device_index: dict[str, str],
+    *,
+    include_ports: bool,
+    client_mode: str,
+) -> dict[str, list[tuple[str, str | None]]]:
+    rows_by_device: dict[str, list[tuple[str, str | None]]] = {}
+    for client in clients:
+        if not _client_matches_mode(client, client_mode):
+            continue
+        name = _client_display_name(client)
+        uplink_mac = _client_uplink_mac(client)
+        if not name or not uplink_mac:
+            continue
+        device_name = device_index.get(_normalize_mac(uplink_mac))
+        if not device_name:
+            continue
+        port_label = None
+        if include_ports:
+            uplink_port = _client_uplink_port(client)
+            if uplink_port is not None:
+                port_label = f"Port {uplink_port}"
+        rows_by_device.setdefault(device_name, []).append((name, port_label))
+    return rows_by_device
+
+
+def _prepare_lldp_maps(
+    devices: list[Device],
+    *,
+    clients: Iterable[object] | None,
+    include_ports: bool,
+    show_clients: bool,
+    client_mode: str,
+) -> tuple[
+    dict[tuple[str, str], str],
+    dict[str, list[tuple[int, str]]] | None,
+    dict[str, list[tuple[str, str | None]]],
+]:
+    device_index = build_device_index(devices)
+    client_rows = (
+        _client_rows(clients, device_index, include_ports=include_ports, client_mode=client_mode)
+        if clients
+        else {}
+    )
+    port_map: dict[tuple[str, str], str] = {}
+    client_port_map = None
+    if include_ports:
+        port_map = build_port_map(devices, only_unifi=False)
+        if clients and show_clients:
+            client_port_map = build_client_port_map(devices, clients, client_mode=client_mode)
+    return port_map, client_port_map, client_rows
+
+
+def _render_device_lldp_section(
+    device: Device,
+    *,
+    device_index: dict[str, str],
+    port_map: dict[tuple[str, str], str],
+    client_port_map: dict[str, list[tuple[int, str]]] | None,
+    client_rows: dict[str, list[tuple[str, str | None]]],
+    include_ports: bool,
+    show_clients: bool,
+    client_mode: str,
+) -> str:
+    details = "\n".join(_details_table_lines(device, client_rows, client_mode)).rstrip()
+    ports_section = ""
+    if include_ports:
+        ports_section = "\n".join(
+            [
+                "### Ports",
+                "",
+                render_device_port_details(device, port_map, client_ports=client_port_map).strip(),
+            ]
+        ).rstrip()
+    if device.lldp_info:
+        lldp_section = "\n".join(
+            markdown_table_lines(
+                ["Local Port", "Neighbor", "Neighbor Port", "Chassis ID", "Port Description"],
+                _lldp_rows(device.lldp_info, device_index),
+                escape=_escape_cell,
+            )
+        ).rstrip()
+    else:
+        lldp_section = "_No LLDP neighbors._"
+    clients_section = ""
+    rows = client_rows.get(device.name)
+    if rows and show_clients:
+        if include_ports:
+            clients_section = "\n".join(
+                [
+                    "### Clients",
+                    "",
+                    "\n".join(
+                        markdown_table_lines(
+                            ["Client", "Port"],
+                            [
+                                [_escape_cell(client_name), _escape_cell(port_label or "-")]
+                                for client_name, port_label in rows
+                            ],
+                        )
+                    ),
+                ]
+            ).rstrip()
+        else:
+            clients_section = "\n".join(
+                ["### Clients", *[f"- {_escape_cell(name)}" for name, _ in rows]]
+            ).rstrip()
+    return render_template(
+        "lldp_device_section.md.j2",
+        device_name=device.name,
+        details=details,
+        ports_section=ports_section,
+        lldp_section=lldp_section,
+        clients_section=clients_section,
+    ).rstrip()
+
+
+def render_lldp_md(
+    devices: list[Device],
+    *,
+    clients: Iterable[object] | None = None,
+    include_ports: bool = False,
+    show_clients: bool = False,
+    client_mode: str = "wired",
+) -> str:
+    device_index = build_device_index(devices)
+    port_map, client_port_map, client_rows = _prepare_lldp_maps(
+        devices,
+        clients=clients,
+        include_ports=include_ports,
+        show_clients=show_clients,
+        client_mode=client_mode,
+    )
+    sections: list[str] = []
+    for device in sorted(devices, key=lambda item: item.name.lower()):
+        sections.append(
+            _render_device_lldp_section(
+                device,
+                device_index=device_index,
+                port_map=port_map,
+                client_port_map=client_port_map,
+                client_rows=client_rows,
+                include_ports=include_ports,
+                show_clients=show_clients,
+                client_mode=client_mode,
+            )
+        )
+    body = "\n\n".join(section for section in sections if section).rstrip()
+    return (
+        render_template(
+            "markdown_section.md.j2",
+            title="LLDP Neighbors",
+            body=body,
+        ).rstrip()
+        + "\n"
+    )

unifi_network_maps/render/markdown_tables.py

@@ -0,0 +1,21 @@
+"""Markdown table helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+
+
+def markdown_table_lines(
+    headers: list[str],
+    rows: Iterable[Iterable[str]],
+    *,
+    escape: Callable[[str], str] | None = None,
+) -> list[str]:
+    esc = escape or (lambda value: value)
+    lines = [
+        "| " + " | ".join(headers) + " |",
+        "| " + " | ".join(["---"] * len(headers)) + " |",
+    ]
+    for row in rows:
+        lines.append("| " + " | ".join(esc(cell) for cell in row) + " |")
+    return lines

unifi_network_maps/render/mermaid.py

@@ -0,0 +1,273 @@
+"""Mermaid diagram rendering."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+
+from ..model.topology import Edge
+from .mermaid_theme import DEFAULT_THEME, MermaidTheme, class_defs
+from .templating import render_template
+
+
+def _escape(label: str) -> str:
+    normalized = label.replace("\r\n", "\n").replace("\r", "\n")
+    escaped = normalized.replace("\\", "\\\\").replace("\n", "\\n")
+    return escaped.replace('"', '\\"')
+
+
+def _slugify(value: str) -> str:
+    normalized = []
+    for ch in value.strip():
+        if ch.isalnum():
+            normalized.append(ch.lower())
+        else:
+            normalized.append("_")
+    slug = "".join(normalized).strip("_")
+    if not slug or slug[0].isdigit():
+        slug = f"n_{slug}" if slug else "n"
+    return slug
+
+
+def _build_id_map(edges: Iterable[Edge], nodes: Iterable[str]) -> dict[str, str]:
+    id_map: dict[str, str] = {}
+    used: set[str] = set()
+
+    def assign(name: str) -> None:
+        if name in id_map:
+            return
+        base = _slugify(name)
+        candidate = base
+        counter = 2
+        while candidate in used:
+            candidate = f"{base}_{counter}"
+            counter += 1
+        id_map[name] = candidate
+        used.add(candidate)
+
+    for node in nodes:
+        assign(node)
+    for edge in edges:
+        assign(edge.left)
+        assign(edge.right)
+
+    return id_map
+
+
+def _node_ref(name: str, node_id: str) -> str:
+    return f'{node_id}["{_escape(name)}"]'
+
+
+def _group_nodes(groups: dict[str, list[str]] | None) -> list[str]:
+    if not groups:
+        return []
+    nodes: list[str] = []
+    for members in groups.values():
+        nodes.extend(members)
+    return nodes
+
+
+def _render_group_sections(
+    lines: list[str],
+    groups: dict[str, list[str]],
+    *,
+    group_order: list[str] | None,
+    id_map: dict[str, str],
+) -> None:
+    ordered = group_order or list(groups.keys())
+    for group_name in ordered:
+        members = groups.get(group_name, [])
+        if not members:
+            continue
+        group_id = _slugify(f"group_{group_name}")
+        label = group_name.replace("_", " ").title()
+        lines.append(f'  subgraph {group_id}["{_escape(label)}"];')
+        for member in members:
+            lines.append(f"    {_node_ref(member, id_map[member])};")
+        lines.append("  end")
+
+
+def _render_edge_lines(
+    lines: list[str],
+    edges: list[Edge],
+    *,
+    id_map: dict[str, str],
+    use_node_labels: bool,
+) -> tuple[list[int], list[int]]:
+    poe_links: list[int] = []
+    wireless_links: list[int] = []
+    for index, edge in enumerate(edges):
+        if use_node_labels:
+            left = _node_ref(edge.left, id_map[edge.left])
+            right = _node_ref(edge.right, id_map[edge.right])
+        else:
+            left = id_map[edge.left]
+            right = id_map[edge.right]
+        if edge.label:
+            label = _escape(edge.label)
+            lines.append(f'  {left} ---|"{label}"| {right};')
+        else:
+            lines.append(f"  {left} --- {right};")
+        if edge.poe:
+            poe_links.append(index)
+        if edge.wireless:
+            wireless_links.append(index)
+    return poe_links, wireless_links
+
+
+def _render_node_classes(
+    lines: list[str],
+    *,
+    node_types: dict[str, str],
+    id_map: dict[str, str],
+    theme: MermaidTheme,
+) -> None:
+    class_map = {
+        "gateway": "node_gateway",
+        "switch": "node_switch",
+        "ap": "node_ap",
+        "client": "node_client",
+        "other": "node_other",
+    }
+    for name, node_type in node_types.items():
+        class_name = class_map.get(node_type, "node_other")
+        node_id = id_map.get(name)
+        if node_id:
+            lines.append(f"  class {node_id} {class_name};")
+    lines.extend(class_defs(theme))
+
+
+def _render_link_styles(
+    lines: list[str],
+    *,
+    poe_links: list[int],
+    wireless_links: list[int],
+    theme: MermaidTheme,
+) -> None:
+    for index in poe_links:
+        lines.append(
+            "  linkStyle "
+            f"{index} stroke:{theme.poe_link},stroke-width:{theme.poe_link_width}px,"
+            f"arrowhead:{theme.poe_link_arrow};"
+        )
+    for index in wireless_links:
+        lines.append(f"  linkStyle {index} stroke-dasharray: 5 4;")
+
+
+def render_mermaid(
+    edges: Iterable[Edge],
+    direction: str = "LR",
+    *,
+    groups: dict[str, list[str]] | None = None,
+    group_order: list[str] | None = None,
+    node_types: dict[str, str] | None = None,
+    theme: MermaidTheme = DEFAULT_THEME,
+) -> str:
+    edge_list = list(edges)
+    id_map = _build_id_map(edge_list, _group_nodes(groups))
+    theme_vars: dict[str, object] = {}
+    if theme.edge_label_border:
+        theme_vars["edgeLabelBorderColor"] = theme.edge_label_border
+    if theme.edge_label_border_width:
+        theme_vars["edgeLabelBorderWidth"] = theme.edge_label_border_width
+    lines = []
+    if theme_vars:
+        lines.append(f'%%{{init: {{"themeVariables": {json.dumps(theme_vars)}}}}}%%')
+    lines.append(f"graph {direction}")
+    if groups:
+        _render_group_sections(lines, groups, group_order=group_order, id_map=id_map)
+    use_node_labels = not groups
+    poe_links, wireless_links = _render_edge_lines(
+        lines, edge_list, id_map=id_map, use_node_labels=use_node_labels
+    )
+    if node_types:
+        _render_node_classes(lines, node_types=node_types, id_map=id_map, theme=theme)
+    _render_link_styles(lines, poe_links=poe_links, wireless_links=wireless_links, theme=theme)
+    return "\n".join(lines) + "\n"
+
+
+def render_legend(theme: MermaidTheme = DEFAULT_THEME, *, legend_scale: float = 1.0) -> str:
+    scale = legend_scale if legend_scale > 0 else 1.0
+    legend_font_size = max(7, round(10 * scale))
+    poe_link_width = max(1, round(theme.poe_link_width * scale))
+    standard_link_width = max(1, round(theme.standard_link_width * scale))
+    node_spacing = max(10, round(50 * scale))
+    rank_spacing = max(10, round(50 * scale))
+    node_padding = max(4, round(12 * scale))
+    return (
+        render_template(
+            "mermaid_legend.mmd.j2",
+            node_spacing=node_spacing,
+            rank_spacing=rank_spacing,
+            legend_font_size=legend_font_size,
+            node_padding=node_padding,
+            class_defs="\n".join(class_defs(theme)),
+            poe_link=theme.poe_link,
+            poe_link_width=poe_link_width,
+            poe_link_arrow=theme.poe_link_arrow,
+            standard_link=theme.standard_link,
+            standard_link_width=standard_link_width,
+            standard_link_arrow=theme.standard_link_arrow,
+        ).rstrip()
+        + "\n"
+    )
+
+
+def render_legend_compact(theme: MermaidTheme = DEFAULT_THEME) -> str:
+    rows = [
+        {
+            "kind": "swatch",
+            "fill": theme.node_gateway[0],
+            "stroke": theme.node_gateway[1],
+            "label": "Gateway",
+        },
+        {
+            "kind": "swatch",
+            "fill": theme.node_switch[0],
+            "stroke": theme.node_switch[1],
+            "label": "Switch",
+        },
+        {
+            "kind": "swatch",
+            "fill": theme.node_ap[0],
+            "stroke": theme.node_ap[1],
+            "label": "AP",
+        },
+        {
+            "kind": "swatch",
+            "fill": theme.node_client[0],
+            "stroke": theme.node_client[1],
+            "label": "Client",
+        },
+        {
+            "kind": "swatch",
+            "fill": theme.node_other[0],
+            "stroke": theme.node_other[1],
+            "label": "Other",
+        },
+        {
+            "kind": "line",
+            "color": theme.poe_link,
+            "width": max(1, theme.poe_link_width),
+            "dashed": False,
+            "label": "PoE",
+            "bolt": True,
+        },
+        {
+            "kind": "line",
+            "color": theme.standard_link,
+            "width": max(1, theme.standard_link_width),
+            "dashed": False,
+            "label": "Link",
+            "bolt": False,
+        },
+        {
+            "kind": "line",
+            "color": theme.standard_link,
+            "width": max(1, theme.standard_link_width),
+            "dashed": True,
+            "label": "Wireless",
+            "bolt": False,
+        },
+    ]
+    return render_template("legend_compact.html.j2", rows=rows)

unifi_network_maps/render/mermaid_theme.py

@@ -0,0 +1,56 @@
+"""Mermaid theming helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class MermaidTheme:
+    node_gateway: tuple[str, str]
+    node_switch: tuple[str, str]
+    node_ap: tuple[str, str]
+    node_client: tuple[str, str]
+    node_other: tuple[str, str]
+    poe_link: str
+    poe_link_width: int
+    poe_link_arrow: str
+    standard_link: str
+    standard_link_width: int
+    standard_link_arrow: str
+    node_text: str | None = None
+    edge_label_border: str | None = None
+    edge_label_border_width: int | None = None
+
+
+DEFAULT_THEME = MermaidTheme(
+    node_gateway=("#ffe3b3", "#d98300"),
+    node_switch=("#d6ecff", "#3a7bd5"),
+    node_ap=("#d7f5e7", "#27ae60"),
+    node_client=("#f2e5ff", "#7f3fbf"),
+    node_other=("#eeeeee", "#8f8f8f"),
+    poe_link="#1e88e5",
+    poe_link_width=2,
+    poe_link_arrow="none",
+    standard_link="#2ecc71",
+    standard_link_width=2,
+    standard_link_arrow="none",
+    node_text=None,
+    edge_label_border=None,
+    edge_label_border_width=None,
+)
+
+
+def class_defs(theme: MermaidTheme = DEFAULT_THEME) -> list[str]:
+    def node_def(name: str, fill: str, stroke: str) -> str:
+        color = f",color:{theme.node_text}" if theme.node_text else ""
+        return f"  classDef {name} fill:{fill},stroke:{stroke},stroke-width:1px{color};"
+
+    return [
+        node_def("node_gateway", theme.node_gateway[0], theme.node_gateway[1]),
+        node_def("node_switch", theme.node_switch[0], theme.node_switch[1]),
+        node_def("node_ap", theme.node_ap[0], theme.node_ap[1]),
+        node_def("node_client", theme.node_client[0], theme.node_client[1]),
+        node_def("node_other", theme.node_other[0], theme.node_other[1]),
+        "  classDef node_legend font-size:10px;",
+    ]