unifi-network-maps 1.3.1__py3-none-any.whl → 1.4.1__py3-none-any.whl

unifi_network_maps/render/device_ports_md.py

@@ -0,0 +1,462 @@
+"""Render per-device port overview tables."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from html import escape as _escape_html
+
+from ..model.ports import extract_port_number
+from ..model.topology import ClientPortMap, Device, PortMap, classify_device_type
+
+
+def render_device_port_overview(
+    devices: list[Device],
+    port_map: PortMap,
+    *,
+    client_ports: ClientPortMap | None = None,
+) -> str:
+    gateways = _collect_devices_by_type(devices, "gateway")
+    switches = _collect_devices_by_type(devices, "switch")
+    lines: list[str] = []
+    if gateways:
+        lines.append("## Gateways")
+        lines.append("")
+        lines.extend(_render_device_group(gateways, port_map, client_ports))
+    if switches:
+        if lines:
+            lines.append("")
+        lines.append("## Switches")
+        lines.append("")
+        lines.extend(_render_device_group(switches, port_map, client_ports))
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _collect_devices_by_type(devices: list[Device], desired_type: str) -> list[Device]:
+    return sorted(
+        [device for device in devices if classify_device_type(device) == desired_type],
+        key=lambda item: item.name.lower(),
+    )
+
+
+def _render_device_group(
+    devices: list[Device],
+    port_map: PortMap,
+    client_ports: ClientPortMap | None,
+) -> list[str]:
+    lines: list[str] = []
+    for device in devices:
+        lines.append(f"### {device.name}")
+        lines.append("")
+        lines.extend(_render_device_details(device))
+        lines.extend(_render_device_ports(device, port_map, client_ports))
+        lines.append("")
+    return lines
+
+
+def render_device_port_details(
+    device: Device,
+    port_map: PortMap,
+    *,
+    client_ports: ClientPortMap | None = None,
+) -> str:
+    lines = _render_device_details(device)
+    lines.extend(_render_device_ports(device, port_map, client_ports))
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _render_device_ports(
+    device: Device,
+    port_map: PortMap,
+    client_ports: ClientPortMap | None,
+) -> list[str]:
+    rows = _build_port_rows(device, port_map, client_ports)
+    lines = [
+        "#### Ports",
+        "",
+        "| Port | Connected | Speed | PoE | Power |",
+        "| --- | --- | --- | --- | --- |",
+    ]
+    for port_label, connected, speed, poe_state, power in rows:
+        lines.append(
+            f"| {_escape_cell(port_label)} | {_escape_cell(connected or '-')} | "
+            f"{_escape_cell(speed)} | {_escape_cell(poe_state)} | {_escape_cell(power)} |"
+        )
+    return lines
+
+
+def _build_port_rows(
+    device: Device,
+    port_map: PortMap,
+    client_ports: ClientPortMap | None,
+) -> list[tuple[str, str, str, str, str]]:
+    connections = _device_port_connections(device.name, port_map)
+    client_connections = _device_client_connections(device.name, client_ports)
+    aggregated = _aggregate_ports(device.port_table)
+    aggregated_indices = {
+        port.port_idx
+        for ports in aggregated.values()
+        for port in ports
+        if getattr(port, "port_idx", None) is not None
+    }
+    rows: list[tuple[tuple[int, int], tuple[str, str, str, str, str]]] = []
+    seen_ports: set[int] = set()
+    for port in sorted(device.port_table, key=_port_sort_key):
+        if port.port_idx in aggregated_indices:
+            port_idx = _port_index(port.port_idx, port.name)
+            if port_idx is not None:
+                seen_ports.add(port_idx)
+            continue
+        port_idx = _port_index(port.port_idx, port.name)
+        if port_idx is not None:
+            seen_ports.add(port_idx)
+        port_label = _format_port_label(port_idx, port.name)
+        connected = _format_connections(
+            device.name,
+            port_idx,
+            connections,
+            client_connections,
+            port_map,
+        )
+        rows.append(
+            (
+                (0, port_idx or 10_000),
+                (
+                    port_label,
+                    connected,
+                    _format_speed(port.speed),
+                    _format_poe_state(port),
+                    _format_poe_power(port.poe_power),
+                ),
+            )
+        )
+    for _group_id, group_ports in aggregated.items():
+        group_label = _format_aggregate_label(group_ports)
+        group_sort = _aggregate_sort_key(group_ports)
+        group_connections = _format_aggregate_connections(
+            device.name,
+            group_ports,
+            connections,
+            client_connections,
+            port_map,
+        )
+        rows.append(
+            (
+                (0, group_sort),
+                (
+                    group_label,
+                    group_connections,
+                    _format_aggregate_speed(group_ports),
+                    _format_aggregate_poe_state(group_ports),
+                    _format_aggregate_power(group_ports),
+                ),
+            )
+        )
+    for port_idx in sorted(connections):
+        if port_idx in seen_ports:
+            continue
+        port_label = _format_port_label(port_idx, None)
+        connected = _format_connections(
+            device.name,
+            port_idx,
+            connections,
+            client_connections,
+            port_map,
+        )
+        rows.append(((2, port_idx), (port_label, connected, "-", "-", "-")))
+    return [row for _key, row in sorted(rows, key=lambda item: item[0])]
+
+
+def _device_port_connections(device_name: str, port_map: PortMap) -> dict[int, list[str]]:
+    connections: dict[int, list[str]] = defaultdict(list)
+    for (src, dst), label in port_map.items():
+        if src != device_name:
+            continue
+        port_idx = extract_port_number(label or "")
+        if port_idx is None:
+            continue
+        connections[port_idx].append(dst)
+    return connections
+
+
+def _device_client_connections(
+    device_name: str, client_ports: ClientPortMap | None
+) -> dict[int, list[str]]:
+    if not client_ports:
+        return {}
+    rows = client_ports.get(device_name, [])
+    connections: dict[int, list[str]] = defaultdict(list)
+    for port_idx, name in rows:
+        connections[port_idx].append(name)
+    return connections
+
+
+def _format_connections(
+    device_name: str,
+    port_idx: int | None,
+    connections: dict[int, list[str]],
+    client_connections: dict[int, list[str]],
+    port_map: PortMap,
+) -> str:
+    if port_idx is None:
+        return ""
+    peers = connections.get(port_idx, [])
+    clients = client_connections.get(port_idx, [])
+    if not peers and not clients:
+        return ""
+    peer_entries: list[str] = []
+    for peer in sorted(peers, key=str.lower):
+        peer_label = port_map.get((peer, device_name))
+        if peer_label:
+            peer_entries.append(f"{peer} ({peer_label})")
+        else:
+            peer_entries.append(peer)
+    peer_text = ", ".join(peer_entries)
+    client_text = _format_client_connections(clients)
+    if peer_text and client_text:
+        return f"{peer_text}<br/>{client_text}"
+    return peer_text or client_text
+
+
+def _format_port_label(port_idx: int | None, name: str | None) -> str:
+    if name and name.strip():
+        normalized = name.strip()
+        if port_idx is None:
+            return normalized
+        if normalized.lower() != f"port {port_idx}".lower():
+            return normalized
+    if port_idx is None:
+        return "Port ?"
+    return f"Port {port_idx}"
+
+
+def _format_speed(speed: int | None) -> str:
+    if speed is None or speed <= 0:
+        return "-"
+    if speed >= 1000:
+        if speed % 1000 == 0:
+            return f"{speed // 1000}G"
+        return f"{speed / 1000:.1f}G"
+    return f"{speed}M"
+
+
+def _format_poe_state(port: object) -> str:
+    poe_power = getattr(port, "poe_power", None)
+    poe_good = getattr(port, "poe_good", False)
+    poe_enable = getattr(port, "poe_enable", False)
+    port_poe = getattr(port, "port_poe", False)
+    if (poe_power or 0.0) > 0 or poe_good:
+        return "active"
+    if port_poe or poe_enable:
+        if not poe_enable:
+            return "disabled"
+        return "capable"
+    return "-"
+
+
+def _format_poe_power(power: float | None) -> str:
+    if power is None or power <= 0:
+        return "-"
+    return f"{power:.2f}W"
+
+
+def _port_index(port_idx: int | None, name: str | None) -> int | None:
+    if port_idx is not None:
+        return port_idx
+    if name:
+        return extract_port_number(name)
+    return None
+
+
+def _port_sort_key(port: object) -> tuple[int, str]:
+    port_idx = _port_index(getattr(port, "port_idx", None), getattr(port, "name", None))
+    if port_idx is not None:
+        return (0, f"{port_idx:04d}")
+    name = getattr(port, "name", "") or ""
+    return (1, name.lower())
+
+
+def _escape_cell(value: str) -> str:
+    return value.replace("|", "\\|")
+
+
+def _render_device_details(device: Device) -> list[str]:
+    lines = [
+        "#### Details",
+        "",
+        "| Field | Value |",
+        "| --- | --- |",
+        f"| Model | {_escape_cell(_device_model_label(device))} |",
+        f"| Type | {_escape_cell(device.type or '-')} |",
+        f"| IP | {_escape_cell(device.ip or '-')} |",
+        f"| MAC | {_escape_cell(device.mac or '-')} |",
+        f"| Firmware | {_escape_cell(device.version or '-')} |",
+        f"| Uplink | {_escape_cell(_uplink_summary(device))} |",
+        f"| Ports | {_escape_cell(_port_summary(device))} |",
+        f"| PoE | {_escape_cell(_poe_summary(device))} |",
+        "",
+    ]
+    return lines
+
+
+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)
+    active_ports = sum(1 for port in ports if (port.speed or 0) > 0)
+    return f"{total_ports} total, {active_ports} active"
+
+
+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 _format_poe_state(port) == "active")
+    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:
+        if classify_device_type(device) == "gateway":
+            return "Internet"
+        return "-"
+    name = uplink.name or uplink.mac or "Unknown"
+    if classify_device_type(device) == "gateway":
+        lowered = name.lower()
+        if lowered in {"unknown", "wan", "internet"}:
+            name = "Internet"
+        elif lowered.startswith(("eth", "wan")):
+            name = "Internet"
+    if uplink.port is not None:
+        return f"{name} (Port {uplink.port})"
+    return name
+
+
+def _device_model_label(device: Device) -> str:
+    if device.model_name:
+        return device.model_name
+    if device.model:
+        return device.model
+    return device.type or "-"
+
+
+def _format_client_connections(clients: list[str]) -> str:
+    if not clients:
+        return ""
+    if len(clients) == 1:
+        return f"{clients[0]} (client)"
+    items = "".join(f"<li>{_escape_html(name)}</li>" for name in clients)
+    return f'<ul class="unifi-port-clients">{items}</ul>'
+
+
+def _aggregate_ports(port_table: list[object]) -> dict[str, list[object]]:
+    groups: dict[str, list[object]] = defaultdict(list)
+    for port in port_table:
+        group = getattr(port, "aggregation_group", None)
+        if group:
+            groups[str(group)].append(port)
+            continue
+        if _looks_like_lag(port):
+            port_idx = getattr(port, "port_idx", None)
+            if port_idx is not None:
+                groups[f"lag-{port_idx}"].append(port)
+    if not groups:
+        return groups
+    port_by_idx = {
+        getattr(port, "port_idx", None): port for port in port_table if port.port_idx is not None
+    }
+    for group_id, group_ports in list(groups.items()):
+        if len(group_ports) > 1:
+            continue
+        lone_port = group_ports[0]
+        if not _looks_like_lag(lone_port):
+            continue
+        if getattr(lone_port, "port_idx", None) is None:
+            continue
+        candidates = []
+        for neighbor in (lone_port.port_idx - 1, lone_port.port_idx + 1):
+            port = port_by_idx.get(neighbor)
+            if port and not getattr(port, "aggregation_group", None):
+                if getattr(port, "speed", None) == getattr(lone_port, "speed", None):
+                    candidates.append(port)
+        if candidates:
+            groups[group_id].extend(candidates)
+    return groups
+
+
+def _looks_like_lag(port: object) -> bool:
+    name = (getattr(port, "name", "") or "").lower()
+    ifname = (getattr(port, "ifname", "") or "").lower()
+    return "lag" in name or "lag" in ifname or "aggregate" in name
+
+
+def _format_aggregate_label(group_ports: list[object]) -> str:
+    ports = sorted([p.port_idx for p in group_ports if getattr(p, "port_idx", None) is not None])
+    if ports:
+        if len(ports) == 1:
+            return f"Port {ports[0]} (LAG)"
+        if ports == list(range(ports[0], ports[-1] + 1)):
+            return f"Port {ports[0]}-{ports[-1]} (LAG)"
+        return "Ports " + "+".join(str(port) for port in ports) + " (LAG)"
+    return "Aggregated ports"
+
+
+def _aggregate_sort_key(group_ports: list[object]) -> int:
+    ports = sorted([p.port_idx for p in group_ports if getattr(p, "port_idx", None) is not None])
+    return ports[0] if ports else 10_000
+
+
+def _format_aggregate_connections(
+    device_name: str,
+    group_ports: list[object],
+    connections: dict[int, list[str]],
+    client_connections: dict[int, list[str]],
+    port_map: PortMap,
+) -> str:
+    rendered: list[str] = []
+    for port in group_ports:
+        port_idx = _port_index(getattr(port, "port_idx", None), getattr(port, "name", None))
+        if port_idx is None:
+            continue
+        text = _format_connections(
+            device_name,
+            port_idx,
+            connections,
+            client_connections,
+            port_map,
+        )
+        if text:
+            rendered.append(text)
+    return ", ".join([item for item in rendered if item])
+
+
+def _format_aggregate_speed(group_ports: list[object]) -> str:
+    speeds = {getattr(port, "speed", None) for port in group_ports}
+    speeds.discard(None)
+    if not speeds:
+        return "-"
+    if len(speeds) == 1:
+        return _format_speed(next(iter(speeds)))
+    return "mixed"
+
+
+def _format_aggregate_poe_state(group_ports: list[object]) -> str:
+    states = {_format_poe_state(port) for port in group_ports}
+    if "active" in states:
+        return "active"
+    if "disabled" in states:
+        return "disabled"
+    if "capable" in states:
+        return "capable"
+    return "-"
+
+
+def _format_aggregate_power(group_ports: list[object]) -> str:
+    total = sum(getattr(port, "poe_power", 0.0) or 0.0 for port in group_ports)
+    return _format_poe_power(total)

unifi_network_maps/render/lldp_md.py

@@ -5,7 +5,8 @@ from __future__ import annotations
 from collections.abc import Iterable
 
 from ..model.lldp import LLDPEntry, local_port_label
-from ..model.topology import Device, build_device_index
+from ..model.topology import Device, build_client_port_map, build_device_index, build_port_map
+from .device_ports_md import render_device_port_details
 
 
 def _normalize_mac(value: str) -> str:
@@ -78,17 +79,7 @@ def _lldp_sort_key(entry: LLDPEntry) -> tuple[int, str, str]:
 
 
 def _device_header_lines(device: Device) -> list[str]:
-    lines = [f"## {device.name}"]
-    meta = []
-    if device.model_name:
-        meta.append(f"Model: {device.model_name}")
-    if device.ip:
-        meta.append(f"IP: {device.ip}")
-    if device.mac:
-        meta.append(f"MAC: {device.mac}")
-    if meta:
-        lines.append(f"*{' | '.join(meta)}*")
-    return lines
+    return [f"## {device.name}"]
 
 
 def _port_summary(device: Device) -> str:
@@ -105,6 +96,19 @@ def _port_summary(device: Device) -> str:
     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:
@@ -141,9 +145,14 @@ def _details_table_lines(
         "",
         "| Field | Value |",
         "| --- | --- |",
+        f"| Model | {_escape_cell(device.model_name or device.type or '-')} |",
+        f"| Type | {_escape_cell(device.type or '-')} |",
+        f"| IP | {_escape_cell(device.ip or '-')} |",
+        f"| MAC | {_escape_cell(device.mac or '-')} |",
         f"| Firmware | {_escape_cell(device.version or '-')} |",
         f"| Uplink | {_escape_cell(_uplink_summary(device))} |",
         f"| Ports | {_escape_cell(_port_summary(device))} |",
+        f"| PoE | {_escape_cell(_poe_summary(device))} |",
         f"| {client_label} | {_escape_cell(wired_count)} |",
         f"| Client examples | {_escape_cell(client_sample)} |",
         "",
@@ -213,16 +222,28 @@ def render_lldp_md(
     client_mode: str = "wired",
 ) -> str:
     device_index = build_device_index(devices)
+    port_map = {}
+    client_port_map = None
     client_rows = (
         _client_rows(clients, device_index, include_ports=include_ports, client_mode=client_mode)
         if clients
         else {}
     )
+    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)
     lines: list[str] = ["# LLDP Neighbors", ""]
     for device in sorted(devices, key=lambda item: item.name.lower()):
         lines.extend(_device_header_lines(device))
         lines.append("")
         lines.extend(_details_table_lines(device, client_rows, client_mode))
+        if include_ports:
+            lines.append("### Ports")
+            lines.append("")
+            lines.append(
+                render_device_port_details(device, port_map, client_ports=client_port_map).strip()
+            )
         if device.lldp_info:
             lines.append("")
             lines.append(

unifi_network_maps/render/mermaid.py

@@ -129,8 +129,19 @@ def render_mermaid(
     return "\n".join(lines) + "\n"
 
 
-def render_legend(theme: MermaidTheme = DEFAULT_THEME) -> str:
+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))
     lines = [
+        "%%{init: {"
+        f'"flowchart": {{"nodeSpacing": {node_spacing}, "rankSpacing": {rank_spacing}}}, '
+        f'"themeVariables": {{"fontSize": "{legend_font_size}px", "nodePadding": {node_padding}}}'
+        "}}%%",
         "graph TB",
         '  subgraph legend["Legend"];',
         '    legend_gateway["Gateway"];',
@@ -158,14 +169,62 @@ def render_legend(theme: MermaidTheme = DEFAULT_THEME) -> str:
         "  class legend_no_poe_b node_legend;",
     ]
     lines.extend(class_defs(theme))
+    lines.append(f"  classDef node_legend font-size:{legend_font_size}px;")
     lines.append(
         "  linkStyle 0 "
-        f"stroke:{theme.poe_link},stroke-width:{theme.poe_link_width}px,"
+        f"stroke:{theme.poe_link},stroke-width:{poe_link_width}px,"
         f"arrowhead:{theme.poe_link_arrow};"
     )
     lines.append(
         "  linkStyle 1 "
-        f"stroke:{theme.standard_link},stroke-width:{theme.standard_link_width}px,"
+        f"stroke:{theme.standard_link},stroke-width:{standard_link_width}px,"
         f"arrowhead:{theme.standard_link_arrow};"
     )
     return "\n".join(lines) + "\n"
+
+
+def render_legend_compact(theme: MermaidTheme = DEFAULT_THEME) -> str:
+    def swatch(fill: str, stroke: str, label: str) -> str:
+        return (
+            f'<span style="display:inline-block;width:12px;height:12px;'
+            f"background:{fill};border:1px solid {stroke};border-radius:2px;"
+            f'margin-right:6px;"></span>{label}'
+        )
+
+    def line_sample(
+        color: str,
+        width: int,
+        *,
+        dashed: bool = False,
+        label: str = "",
+        bolt: bool = False,
+    ) -> str:
+        dash = ' stroke-dasharray="5 4"' if dashed else ""
+        bolt_suffix = " ⚡" if bolt else ""
+        return (
+            f'<span style="display:inline-flex;align-items:center;gap:6px;">'
+            f'<svg width="42" height="10" viewBox="0 0 42 10" '
+            f'xmlns="http://www.w3.org/2000/svg" aria-hidden="true">'
+            f'<line x1="2" y1="5" x2="40" y2="5" stroke="{color}" '
+            f'stroke-width="{max(1, width)}"{dash} />'
+            f"</svg>{label}{bolt_suffix}</span>"
+        )
+
+    rows = [
+        swatch(theme.node_gateway[0], theme.node_gateway[1], "Gateway"),
+        swatch(theme.node_switch[0], theme.node_switch[1], "Switch"),
+        swatch(theme.node_ap[0], theme.node_ap[1], "AP"),
+        swatch(theme.node_client[0], theme.node_client[1], "Client"),
+        swatch(theme.node_other[0], theme.node_other[1], "Other"),
+        line_sample(theme.poe_link, theme.poe_link_width, label="PoE", bolt=True),
+        line_sample(theme.standard_link, theme.standard_link_width, label="Link"),
+        line_sample(theme.standard_link, theme.standard_link_width, dashed=True, label="Wireless"),
+    ]
+    lines = [
+        '<table class="unifi-legend-table">',
+        "<tbody>",
+    ]
+    lines.extend(f"  <tr><td>{style}</td></tr>" for style in rows)
+    lines.append("</tbody>")
+    lines.append("</table>")
+    return "\n".join(lines) + "\n"