unifi-network-maps 1.4.15__py3-none-any.whl → 1.5.0__py3-none-any.whl

unifi_network_maps/render/device_ports_md.py

@@ -5,9 +5,11 @@ from __future__ import annotations
 from collections import defaultdict
 from html import escape as _escape_html
 
+from ..model.classify import classify_device_type
 from ..model.ports import extract_port_number
-from ..model.topology import ClientPortMap, Device, PortInfo, PortMap, classify_device_type
-from .markdown_tables import markdown_table_lines
+from ..model.topology import ClientPortMap, Device, PortInfo, PortMap
+from .device_summary import poe_summary, port_summary, uplink_summary
+from .markdown_tables import escape_markdown, markdown_table_lines
 from .templating import render_template
 
 
@@ -83,11 +85,11 @@ def _render_device_ports(
     rows = _build_port_rows(device, port_map, client_ports)
     table_rows = [
         [
-            _escape_markdown_text(port_label),
-            _escape_connected_cell(connected or "-"),
-            _escape_markdown_text(speed),
-            _escape_markdown_text(poe_state),
-            _escape_markdown_text(power),
+            escape_markdown(port_label),
+            connected or "-",  # Not escaped: contains intentional HTML (br, ul)
+            escape_markdown(speed),
+            escape_markdown(poe_state),
+            escape_markdown(power),
         ]
         for port_label, connected, speed, poe_state, power in rows
     ]
@@ -113,7 +115,7 @@ def _build_port_rows(
         port.port_idx
         for ports in aggregated.values()
         for port in ports
-        if getattr(port, "port_idx", None) is not None
+        if port.port_idx is not None
     }
     rows: list[tuple[tuple[int, int], tuple[str, str, str, str, str]]] = []
     seen_ports: set[int] = set()
@@ -224,11 +226,9 @@ def _format_connections(
     for peer in sorted(peers, key=str.lower):
         peer_label = port_map.get((peer, device_name))
         if peer_label:
-            peer_entries.append(
-                f"{_escape_markdown_text(peer)} ({_escape_markdown_text(peer_label)})"
-            )
+            peer_entries.append(f"{escape_markdown(peer)} ({escape_markdown(peer_label)})")
         else:
-            peer_entries.append(_escape_markdown_text(peer))
+            peer_entries.append(escape_markdown(peer))
     peer_text = ", ".join(peer_entries)
     client_text = _format_client_connections(clients)
     if peer_text and client_text:
@@ -258,15 +258,11 @@ def _format_speed(speed: int | None) -> str:
     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:
+def _format_poe_state(port: PortInfo) -> str:
+    if (port.poe_power or 0.0) > 0 or port.poe_good:
         return "active"
-    if port_poe or poe_enable:
-        if not poe_enable:
+    if port.port_poe or port.poe_enable:
+        if not port.poe_enable:
             return "disabled"
         return "capable"
     return "-"
@@ -286,23 +282,11 @@ def _port_index(port_idx: int | None, name: str | None) -> int | None:
     return None
 
 
-def _port_sort_key(port: object) -> tuple[int, str]:
-    port_idx = _port_index(getattr(port, "port_idx", None), getattr(port, "name", None))
+def _port_sort_key(port: PortInfo) -> tuple[int, str]:
+    port_idx = _port_index(port.port_idx, port.name)
     if port_idx is not None:
         return (0, f"{port_idx:04d}")
-    name = getattr(port, "name", "") or ""
-    return (1, name.lower())
-
-
-def _escape_markdown_text(value: str) -> str:
-    escaped = value.replace("\\", "\\\\")
-    for char in ("|", "[", "]", "*", "_", "`", "<", ">"):
-        escaped = escaped.replace(char, f"\\{char}")
-    return escaped
-
-
-def _escape_connected_cell(value: str) -> str:
-    return value
+    return (1, (port.name or "").lower())
 
 
 def _render_device_details(device: Device) -> list[str]:
@@ -311,59 +295,19 @@ def _render_device_details(device: Device) -> list[str]:
         "",
         "| Field | Value |",
         "| --- | --- |",
-        f"| Model | {_escape_markdown_text(_device_model_label(device))} |",
-        f"| Type | {_escape_markdown_text(device.type or '-')} |",
-        f"| IP | {_escape_markdown_text(device.ip or '-')} |",
-        f"| MAC | {_escape_markdown_text(device.mac or '-')} |",
-        f"| Firmware | {_escape_markdown_text(device.version or '-')} |",
-        f"| Uplink | {_escape_markdown_text(_uplink_summary(device))} |",
-        f"| Ports | {_escape_markdown_text(_port_summary(device))} |",
-        f"| PoE | {_escape_markdown_text(_poe_summary(device))} |",
+        f"| Model | {escape_markdown(_device_model_label(device))} |",
+        f"| Type | {escape_markdown(device.type or '-')} |",
+        f"| IP | {escape_markdown(device.ip or '-')} |",
+        f"| MAC | {escape_markdown(device.mac or '-')} |",
+        f"| Firmware | {escape_markdown(device.version or '-')} |",
+        f"| Uplink | {escape_markdown(uplink_summary(device))} |",
+        f"| Ports | {escape_markdown(port_summary(device))} |",
+        f"| PoE | {escape_markdown(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
@@ -376,7 +320,7 @@ def _format_client_connections(clients: list[str]) -> str:
     if not clients:
         return ""
     if len(clients) == 1:
-        return f"{_escape_markdown_text(clients[0])} (client)"
+        return f"{escape_markdown(clients[0])} (client)"
     items = "".join(f"<li>{_escape_html(name)}</li>" for name in clients)
     return f'<ul class="unifi-port-clients">{items}</ul>'
 
@@ -384,14 +328,12 @@ def _format_client_connections(clients: list[str]) -> str:
 def _aggregate_base_groups(port_table: list[PortInfo]) -> dict[str, list[PortInfo]]:
     groups: dict[str, list[PortInfo]] = defaultdict(list)
     for port in port_table:
-        group = getattr(port, "aggregation_group", None)
-        if group:
-            groups[str(group)].append(port)
+        if port.aggregation_group:
+            groups[str(port.aggregation_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 port.port_idx is not None:
+                groups[f"lag-{port.port_idx}"].append(port)
     return groups
 
 
@@ -416,8 +358,8 @@ def _extend_singleton_groups(
         candidates: list[PortInfo] = []
         for neighbor in (port_idx - 1, 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):
+            if port and not port.aggregation_group:
+                if port.speed == lone_port.speed:
                     candidates.append(port)
         if candidates:
             groups[group_id].extend(candidates)
@@ -430,8 +372,8 @@ def _aggregate_ports(port_table: list[PortInfo]) -> dict[str, list[PortInfo]]:
 
 
 def _looks_like_lag(port: PortInfo) -> bool:
-    name = (getattr(port, "name", "") or "").lower()
-    ifname = (getattr(port, "ifname", "") or "").lower()
+    name = (port.name or "").lower()
+    ifname = (port.ifname or "").lower()
     return "lag" in name or "lag" in ifname or "aggregate" in name
 
 
@@ -460,7 +402,7 @@ def _format_aggregate_connections(
 ) -> str:
     rendered: list[str] = []
     for port in group_ports:
-        port_idx = _port_index(getattr(port, "port_idx", None), getattr(port, "name", None))
+        port_idx = _port_index(port.port_idx, port.name)
         if port_idx is None:
             continue
         text = _format_connections(
@@ -476,7 +418,7 @@ def _format_aggregate_connections(
 
 
 def _format_aggregate_speed(group_ports: list[PortInfo]) -> str:
-    speeds = {getattr(port, "speed", None) for port in group_ports}
+    speeds = {port.speed for port in group_ports}
     speeds.discard(None)
     if not speeds:
         return "-"
@@ -497,5 +439,5 @@ def _format_aggregate_poe_state(group_ports: list[PortInfo]) -> str:
 
 
 def _format_aggregate_power(group_ports: list[PortInfo]) -> str:
-    total = sum(getattr(port, "poe_power", 0.0) or 0.0 for port in group_ports)
+    total = sum(port.poe_power or 0.0 for port in group_ports)
     return _format_poe_power(total)

unifi_network_maps/render/device_summary.py

@@ -0,0 +1,53 @@
+"""Shared device summary helpers for markdown renderers."""
+
+from __future__ import annotations
+
+from ..model.classify import classify_device_type
+from ..model.topology import Device, PortInfo
+
+
+def port_summary(device: Device) -> str:
+    """Summarize port count and activity for a device."""
+    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:
+    """Summarize PoE capability, activity, and power draw."""
+    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 _is_poe_active(port))
+    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:
+    """Describe the device's uplink connection."""
+    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 _is_poe_active(port: PortInfo) -> bool:
+    return (port.poe_power or 0.0) > 0 or port.poe_good

unifi_network_maps/render/lldp_md.py

@@ -4,212 +4,29 @@ from __future__ import annotations
 
 from collections.abc import Iterable
 
+from ..model.classify import client_display_name
+from ..model.clients import (
+    _client_uplink_mac,
+    _client_uplink_port,
+    build_client_port_map,
+    client_matches_filters,
+)
+from ..model.edges import build_device_index, build_port_map
+from ..model.helpers import normalize_mac
 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 ..model.topology import Device
 from .device_ports_md import render_device_port_details
-from .markdown_tables import markdown_table_lines
+from .device_summary import poe_summary, port_summary, uplink_summary
+from .markdown_tables import escape_markdown, 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:
-    raw_name = _client_field(client, "name")
-    if isinstance(raw_name, str) and raw_name.strip():
-        return raw_name.strip()
-    preferred = _client_ucore_display_name(client)
-    if preferred:
-        return preferred
-    for key in ("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_unifi_flag(client: object) -> bool | None:
-    for key in ("is_unifi", "is_unifi_device", "is_ubnt", "is_uap", "is_managed"):
-        value = _client_field(client, key)
-        if isinstance(value, bool):
-            return value
-        if isinstance(value, int):
-            return value != 0
-    return None
-
-
-def _client_vendor(client: object) -> str | None:
-    for key in ("oui", "vendor", "vendor_name", "manufacturer", "manufacturer_name"):
-        value = _client_field(client, key)
-        if isinstance(value, str) and value.strip():
-            return value.strip()
-    return None
-
-
-def _client_ucore_info(client: object) -> dict[str, object] | None:
-    info = _client_field(client, "unifi_device_info_from_ucore")
-    if isinstance(info, dict):
-        return info
-    return None
-
-
-def _client_ucore_display_name(client: object) -> str | None:
-    ucore = _client_ucore_info(client)
-    if not ucore:
-        return None
-    for key in ("name", "computed_model", "product_model", "product_shortname"):
-        value = ucore.get(key)
-        if isinstance(value, str) and value.strip():
-            return value.strip()
-    return None
-
-
-def _client_hostname_source(client: object) -> str | None:
-    value = _client_field(client, "hostname_source")
-    if isinstance(value, str) and value.strip():
-        return value.strip()
-    return None
-
-
-def _client_is_unifi(client: object) -> bool:
-    flag = _client_unifi_flag(client)
-    if flag is not None:
-        return flag
-    ucore = _client_ucore_info(client)
-    if ucore:
-        managed = ucore.get("managed")
-        if isinstance(managed, bool) and managed:
-            return True
-        if isinstance(ucore.get("product_line"), str) and ucore.get("product_line"):
-            return True
-        if isinstance(ucore.get("product_shortname"), str) and ucore.get("product_shortname"):
-            return True
-        for key in ("name", "computed_model", "product_model"):
-            value = ucore.get(key)
-            if isinstance(value, str) and value.strip():
-                return True
-    vendor = _client_vendor(client)
-    if not vendor:
-        return False
-    normalized = vendor.lower()
-    return "ubiquiti" in normalized or "unifi" in normalized
-
-
-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 _client_matches_filters(client: object, *, client_mode: str, only_unifi: bool) -> bool:
-    if not _client_matches_mode(client, client_mode):
-        return False
-    if only_unifi and not _client_is_unifi(client):
-        return False
-    return True
-
-
 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]:
@@ -232,16 +49,16 @@ def _details_table_lines(
     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)],
+        ["Model", escape_markdown(device.model_name or device.type or "-")],
+        ["Type", escape_markdown(device.type or "-")],
+        ["IP", escape_markdown(device.ip or "-")],
+        ["MAC", escape_markdown(device.mac or "-")],
+        ["Firmware", escape_markdown(device.version or "-")],
+        ["Uplink", escape_markdown(uplink_summary(device))],
+        ["Ports", escape_markdown(port_summary(device))],
+        ["PoE", escape_markdown(poe_summary(device))],
+        [client_label, escape_markdown(wired_count)],
+        ["Client examples", escape_markdown(client_sample)],
     ]
     lines = ["### Details", ""]
     lines.extend(markdown_table_lines(["Field", "Value"], rows))
@@ -255,7 +72,7 @@ def _lldp_rows(
     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_name = device_index.get(normalize_mac(entry.chassis_id), "")
         peer_port = entry.port_id or "?"
         port_desc = entry.port_desc or ""
         rows.append(
@@ -270,13 +87,6 @@ def _lldp_rows(
     return rows
 
 
-def _escape_cell(value: str) -> str:
-    escaped = value.replace("\\", "\\\\")
-    for char in ("|", "[", "]", "*", "_", "`", "<", ">"):
-        escaped = escaped.replace(char, f"\\{char}")
-    return escaped
-
-
 def _client_rows(
     clients: Iterable[object],
     device_index: dict[str, str],
@@ -287,13 +97,13 @@ def _client_rows(
 ) -> 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_filters(client, client_mode=client_mode, only_unifi=only_unifi):
+        if not client_matches_filters(client, client_mode=client_mode, only_unifi=only_unifi):
             continue
-        name = _client_display_name(client)
+        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))
+        device_name = device_index.get(normalize_mac(uplink_mac))
         if not device_name:
             continue
         port_label = None
@@ -370,7 +180,7 @@ def _render_device_lldp_section(
             markdown_table_lines(
                 ["Local Port", "Neighbor", "Neighbor Port", "Chassis ID", "Port Description"],
                 _lldp_rows(device.lldp_info, device_index),
-                escape=_escape_cell,
+                escape=escape_markdown,
             )
         ).rstrip()
     else:
@@ -387,7 +197,7 @@ def _render_device_lldp_section(
                         markdown_table_lines(
                             ["Client", "Port"],
                             [
-                                [_escape_cell(client_name), _escape_cell(port_label or "-")]
+                                [escape_markdown(client_name), escape_markdown(port_label or "-")]
                                 for client_name, port_label in rows
                             ],
                         )
@@ -396,7 +206,7 @@ def _render_device_lldp_section(
             ).rstrip()
         else:
             clients_section = "\n".join(
-                ["### Clients", *[f"- {_escape_cell(name)}" for name, _ in rows]]
+                ["### Clients", *[f"- {escape_markdown(name)}" for name, _ in rows]]
             ).rstrip()
     return render_template(
         "lldp_device_section.md.j2",

unifi_network_maps/render/markdown_tables.py

@@ -5,6 +5,14 @@ from __future__ import annotations
 from collections.abc import Callable, Iterable
 
 
+def escape_markdown(value: str) -> str:
+    """Escape characters that have special meaning in Markdown table cells."""
+    escaped = value.replace("\\", "\\\\")
+    for char in ("|", "[", "]", "*", "_", "`", "<", ">"):
+        escaped = escaped.replace(char, f"\\{char}")
+    return escaped
+
+
 def markdown_table_lines(
     headers: list[str],
     rows: Iterable[Iterable[str]],

unifi_network_maps/render/mermaid.py

@@ -87,6 +87,14 @@ def _render_group_sections(
         lines.append("  end")
 
 
+def _format_vlan_suffix(active_vlans: tuple[int, ...]) -> str:
+    """Format VLAN suffix for edge labels."""
+    if not active_vlans:
+        return ""
+    vlan_str = ",".join(f"V{v}" for v in sorted(active_vlans))
+    return f" [{vlan_str}]"
+
+
 def _render_edge_lines(
     lines: list[str],
     edges: list[Edge],
@@ -103,8 +111,9 @@ def _render_edge_lines(
         else:
             left = id_map[edge.left]
             right = id_map[edge.right]
-        if edge.label:
-            label = _escape(edge.label)
+        vlan_suffix = _format_vlan_suffix(edge.active_vlans)
+        if edge.label or vlan_suffix:
+            label = _escape(f"{edge.label or ''}{vlan_suffix}".strip())
             lines.append(f'  {left} ---|"{label}"| {right};')
         else:
             lines.append(f"  {left} --- {right};")

unifi_network_maps/render/mkdocs.py

@@ -7,7 +7,8 @@ from dataclasses import dataclass
 from datetime import datetime
 from zoneinfo import ZoneInfo
 
-from ..model.topology import ClientPortMap, Device, PortMap, build_node_type_map
+from ..model.clients import build_node_type_map
+from ..model.topology import ClientPortMap, Device, PortMap
 from .device_ports_md import render_device_port_overview
 from .mermaid import render_legend, render_legend_compact, render_mermaid
 from .mermaid_theme import MermaidTheme