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

unifi_network_maps/model/topology.py

@@ -6,7 +6,6 @@ import logging
 from collections import deque
 from collections.abc import Iterable
 from dataclasses import dataclass, field
-from typing import Protocol
 
 from .labels import compose_port_label, order_edge_names
 from .lldp import LLDPEntry, coerce_lldp, local_port_label
@@ -40,27 +39,7 @@ class Edge:
     wireless: bool = False
 
 
-class DeviceLike(Protocol):
-    name: str | None
-    model_name: str | None
-    model: str | None
-    mac: str | None
-    ip: str | None
-    ip_address: str | None
-    type: str | None
-    device_type: str | None
-    lldp_info: object | None
-    lldp: object | None
-    port_table: object | None
-    uplink: object | None
-    last_uplink: object | None
-    uplink_mac: object | None
-    uplink_device_mac: object | None
-    last_uplink_mac: object | None
-    uplink_device_name: object | None
-    uplink_remote_port: object | None
-    version: object | None
-    displayable_version: object | None
+type DeviceSource = object
 
 
 @dataclass(frozen=True)
@@ -94,6 +73,20 @@ def _get_attr(obj: object, name: str) -> object | None:
     return getattr(obj, name, None)
 
 
+def _as_list(value: object | None) -> list[object]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    if isinstance(value, dict):
+        return [value]
+    if isinstance(value, str | bytes):
+        return []
+    if isinstance(value, Iterable):
+        return list(value)
+    return []
+
+
 def _normalize_mac(value: str) -> str:
     return value.strip().lower()
 
@@ -167,14 +160,16 @@ def _aggregation_group(port_entry: object) -> object | None:
     return None
 
 
-def _resolve_port_idx_from_lldp(lldp_entry: LLDPEntry, port_table: list[PortInfo]) -> int | None:
-    if lldp_entry.local_port_idx is not None:
-        return lldp_entry.local_port_idx
-    candidates = []
-    if lldp_entry.local_port_name:
-        candidates.append(lldp_entry.local_port_name)
-    if lldp_entry.port_id:
-        candidates.append(lldp_entry.port_id)
+def _lldp_candidates(entry: LLDPEntry) -> list[str]:
+    candidates: list[str] = []
+    if entry.local_port_name:
+        candidates.append(entry.local_port_name)
+    if entry.port_id:
+        candidates.append(entry.port_id)
+    return candidates
+
+
+def _match_port_by_name(candidates: list[str], port_table: list[PortInfo]) -> int | None:
     for candidate in candidates:
         normalized = candidate.strip().lower()
         for port in port_table:
@@ -182,6 +177,10 @@ def _resolve_port_idx_from_lldp(lldp_entry: LLDPEntry, port_table: list[PortInfo
                 return port.port_idx
             if port.name and port.name.strip().lower() == normalized:
                 return port.port_idx
+    return None
+
+
+def _match_port_by_number(candidates: list[str], port_table: list[PortInfo]) -> int | None:
     for candidate in candidates:
         number = extract_port_number(candidate)
         if number is None:
@@ -192,6 +191,16 @@ def _resolve_port_idx_from_lldp(lldp_entry: LLDPEntry, port_table: list[PortInfo
     return None
 
 
+def _resolve_port_idx_from_lldp(lldp_entry: LLDPEntry, port_table: list[PortInfo]) -> int | None:
+    if lldp_entry.local_port_idx is not None:
+        return lldp_entry.local_port_idx
+    candidates = _lldp_candidates(lldp_entry)
+    matched = _match_port_by_name(candidates, port_table)
+    if matched is not None:
+        return matched
+    return _match_port_by_number(candidates, port_table)
+
+
 def _port_info_from_entry(port_entry: object) -> PortInfo:
     if isinstance(port_entry, dict):
         port_idx = port_entry.get("port_idx") or port_entry.get("portIdx")
@@ -226,12 +235,12 @@ def _port_info_from_entry(port_entry: object) -> PortInfo:
     )
 
 
-def _coerce_port_table(device: DeviceLike) -> list[PortInfo]:
-    port_table = _get_attr(device, "port_table") or []
+def _coerce_port_table(device: DeviceSource) -> list[PortInfo]:
+    port_table = _as_list(_get_attr(device, "port_table"))
     return [_port_info_from_entry(port_entry) for port_entry in port_table]
 
 
-def _poe_ports_from_device(device: DeviceLike) -> dict[int, bool]:
+def _poe_ports_from_device(device: DeviceSource) -> dict[int, bool]:
     port_table = _coerce_port_table(device)
     poe_ports: dict[int, bool] = {}
     for port_entry in port_table:
@@ -271,7 +280,7 @@ def _parse_uplink(value: object | None) -> UplinkInfo | None:
     return UplinkInfo(mac=mac_value, name=name_value, port=port)
 
 
-def _uplink_info(device: DeviceLike) -> tuple[UplinkInfo | None, UplinkInfo | None]:
+def _uplink_info(device: DeviceSource) -> tuple[UplinkInfo | None, UplinkInfo | None]:
     uplink = _parse_uplink(_device_field(device, "uplink"))
     last_uplink = _parse_uplink(_device_field(device, "last_uplink"))
 
@@ -290,7 +299,7 @@ def _uplink_info(device: DeviceLike) -> tuple[UplinkInfo | None, UplinkInfo | No
     return uplink, last_uplink
 
 
-def coerce_device(device: DeviceLike) -> Device:
+def coerce_device(device: DeviceSource) -> Device:
     name = _get_attr(device, "name")
     model_name = _get_attr(device, "model_name") or _get_attr(device, "model")
     model = _get_attr(device, "model")
@@ -301,6 +310,8 @@ def coerce_device(device: DeviceLike) -> Device:
     lldp_info = _get_attr(device, "lldp_info")
     if lldp_info is None:
         lldp_info = _get_attr(device, "lldp")
+    if lldp_info is None:
+        lldp_info = _get_attr(device, "lldp_table")
 
     if not name or not mac:
         raise ValueError("Device missing name or mac")
@@ -312,7 +323,8 @@ def coerce_device(device: DeviceLike) -> Device:
         else:
             raise ValueError(f"Device {name} missing LLDP info")
 
-    coerced_lldp = [coerce_lldp(lldp_entry) for lldp_entry in lldp_info]
+    lldp_entries = _as_list(lldp_info)
+    coerced_lldp = [coerce_lldp(lldp_entry) for lldp_entry in lldp_entries]
     port_table = _coerce_port_table(device)
     poe_ports = _poe_ports_from_device(device)
 
@@ -332,14 +344,16 @@ def coerce_device(device: DeviceLike) -> Device:
     )
 
 
-def normalize_devices(devices: Iterable[DeviceLike]) -> list[Device]:
+def normalize_devices(devices: Iterable[DeviceSource]) -> list[Device]:
     return [coerce_device(device) for device in devices]
 
 
-def classify_device_type(device: Device) -> str:
-    value = device.type.strip().lower()
+def classify_device_type(device: object) -> str:
+    raw_type = _device_field(device, "type")
+    raw_name = _device_field(device, "name")
+    value = raw_type.strip().lower() if isinstance(raw_type, str) else ""
     if not value:
-        name = device.name.strip().lower()
+        name = raw_name.strip().lower() if isinstance(raw_name, str) else ""
         if "gateway" in name or name.startswith("gw"):
             return "gateway"
         if "switch" in name:
@@ -363,19 +377,19 @@ def group_devices_by_type(devices: Iterable[Device]) -> dict[str, list[str]]:
     return groups
 
 
-def build_tree_edges_by_topology(edges: Iterable[Edge], gateways: list[str]) -> list[Edge]:
+def _build_adjacency(edges: Iterable[Edge]) -> dict[str, set[str]]:
     adjacency: dict[str, set[str]] = {}
     for edge in edges:
         adjacency.setdefault(edge.left, set()).add(edge.right)
         adjacency.setdefault(edge.right, set()).add(edge.left)
+    return adjacency
 
-    if not gateways:
-        return []
 
-    edge_map: dict[frozenset[str], Edge] = {}
-    for edge in edges:
-        edge_map[frozenset({edge.left, edge.right})] = edge
+def _build_edge_map(edges: Iterable[Edge]) -> dict[frozenset[str], Edge]:
+    return {frozenset({edge.left, edge.right}): edge for edge in edges}
 
+
+def _tree_parents(adjacency: dict[str, set[str]], gateways: list[str]) -> dict[str, str]:
     visited: set[str] = set()
     parent: dict[str, str] = {}
     queue: deque[str] = deque()
@@ -393,7 +407,12 @@ def build_tree_edges_by_topology(edges: Iterable[Edge], gateways: list[str]) ->
             visited.add(neighbor)
             parent[neighbor] = current
             queue.append(neighbor)
+    return parent
+
 
+def _tree_edges_from_parent(
+    parent: dict[str, str], edge_map: dict[frozenset[str], Edge]
+) -> list[Edge]:
     tree_edges: list[Edge] = []
     for child in sorted(parent):
         parent_name = parent[child]
@@ -404,10 +423,18 @@ def build_tree_edges_by_topology(edges: Iterable[Edge], gateways: list[str]) ->
             tree_edges.append(
                 Edge(left=parent_name, right=child, label=original.label, poe=original.poe)
             )
-
     return tree_edges
 
 
+def build_tree_edges_by_topology(edges: Iterable[Edge], gateways: list[str]) -> list[Edge]:
+    if not gateways:
+        return []
+    adjacency = _build_adjacency(edges)
+    edge_map = _build_edge_map(edges)
+    parent = _tree_parents(adjacency, gateways)
+    return _tree_edges_from_parent(parent, edge_map)
+
+
 def build_device_index(devices: Iterable[Device]) -> dict[str, str]:
     index: dict[str, str] = {}
     for device in devices:
@@ -561,7 +588,6 @@ def build_edges(
         index,
         device_by_name,
         port_map,
-        poe_map,
         raw_links,
         seen,
         include_ports=include_ports,
@@ -604,7 +630,6 @@ def build_port_map(devices: Iterable[Device], *, only_unifi: bool = True) -> Por
         index,
         device_by_name,
         port_map,
-        poe_map,
         raw_links,
         seen,
         include_ports=True,
@@ -692,13 +717,52 @@ def _collect_lldp_links(
     return devices_with_lldp_edges
 
 
+def _uplink_name(
+    uplink: UplinkInfo | None,
+    index: dict[str, str],
+    *,
+    only_unifi: bool,
+) -> str | None:
+    if not uplink:
+        return None
+    if uplink.mac:
+        resolved = index.get(_normalize_mac(uplink.mac))
+        if resolved:
+            return resolved
+    if uplink.name:
+        return uplink.name
+    if not only_unifi and uplink.mac:
+        return uplink.mac
+    return None
+
+
+def _maybe_add_uplink_link(
+    device: Device,
+    upstream_name: str,
+    *,
+    uplink: UplinkInfo | None,
+    device_by_name: dict[str, Device],
+    port_map: PortMap,
+    raw_links: list[tuple[str, str]],
+    seen: set[frozenset[str]],
+    include_ports: bool,
+) -> None:
+    key = frozenset({device.name, upstream_name})
+    if key in seen:
+        return
+    if uplink and uplink.port is not None:
+        if include_ports:
+            port_map[(upstream_name, device.name)] = f"Port {uplink.port}"
+    raw_links.append((upstream_name, device.name))
+    seen.add(key)
+
+
 def _collect_uplink_links(
     devices: list[Device],
     devices_with_lldp_edges: set[str],
     index: dict[str, str],
     device_by_name: dict[str, Device],
     port_map: PortMap,
-    poe_map: PoeMap,
     raw_links: list[tuple[str, str]],
     seen: set[frozenset[str]],
     *,
@@ -709,31 +773,21 @@ def _collect_uplink_links(
         if device.name in devices_with_lldp_edges:
             continue
         uplink = device.uplink or device.last_uplink
-        upstream_name = None
-        if uplink and uplink.mac:
-            upstream_name = index.get(_normalize_mac(uplink.mac))
-        if not upstream_name and uplink and uplink.name:
-            upstream_name = uplink.name
-        if not upstream_name and not only_unifi and uplink and uplink.mac:
-            upstream_name = uplink.mac
+        upstream_name = _uplink_name(uplink, index, only_unifi=only_unifi)
         if not upstream_name:
             continue
         if only_unifi and upstream_name not in device_by_name:
             continue
-        key = frozenset({device.name, upstream_name})
-        if key in seen:
-            continue
-        poe = False
-        if uplink and uplink.port is not None:
-            if include_ports:
-                port_map[(upstream_name, device.name)] = f"Port {uplink.port}"
-            uplink_device = device_by_name.get(upstream_name)
-            if uplink_device and uplink.port in uplink_device.poe_ports:
-                poe = uplink_device.poe_ports[uplink.port]
-        raw_links.append((upstream_name, device.name))
-        seen.add(key)
-        if poe:
-            poe_map[(upstream_name, device.name)] = poe
+        _maybe_add_uplink_link(
+            device,
+            upstream_name,
+            uplink=uplink,
+            device_by_name=device_by_name,
+            port_map=port_map,
+            raw_links=raw_links,
+            seen=seen,
+            include_ports=include_ports,
+        )
 
 
 def _build_ordered_edges(

unifi_network_maps/render/device_ports_md.py

@@ -6,7 +6,7 @@ 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
+from ..model.topology import ClientPortMap, Device, PortInfo, PortMap, classify_device_type
 
 
 def render_device_port_overview(
@@ -355,8 +355,8 @@ def _format_client_connections(clients: list[str]) -> str:
     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)
+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:
@@ -366,10 +366,17 @@ def _aggregate_ports(port_table: list[object]) -> dict[str, list[object]]:
             port_idx = getattr(port, "port_idx", None)
             if port_idx is not None:
                 groups[f"lag-{port_idx}"].append(port)
+    return groups
+
+
+def _extend_singleton_groups(
+    groups: dict[str, list[PortInfo]],
+    port_table: list[PortInfo],
+) -> None:
     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
+        return
+    port_by_idx: dict[int, PortInfo] = {
+        port.port_idx: 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:
@@ -377,27 +384,33 @@ def _aggregate_ports(port_table: list[object]) -> dict[str, list[object]]:
         lone_port = group_ports[0]
         if not _looks_like_lag(lone_port):
             continue
-        if getattr(lone_port, "port_idx", None) is None:
+        port_idx = lone_port.port_idx
+        if port_idx is None:
             continue
-        candidates = []
-        for neighbor in (lone_port.port_idx - 1, lone_port.port_idx + 1):
+        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):
                     candidates.append(port)
         if candidates:
             groups[group_id].extend(candidates)
+
+
+def _aggregate_ports(port_table: list[PortInfo]) -> dict[str, list[PortInfo]]:
+    groups = _aggregate_base_groups(port_table)
+    _extend_singleton_groups(groups, port_table)
     return groups
 
 
-def _looks_like_lag(port: object) -> bool:
+def _looks_like_lag(port: PortInfo) -> 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])
+def _format_aggregate_label(group_ports: list[PortInfo]) -> str:
+    ports = sorted([int(p.port_idx) for p in group_ports if p.port_idx is not None])
     if ports:
         if len(ports) == 1:
             return f"Port {ports[0]} (LAG)"
@@ -407,14 +420,14 @@ def _format_aggregate_label(group_ports: list[object]) -> str:
     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])
+def _aggregate_sort_key(group_ports: list[PortInfo]) -> int:
+    ports = sorted([int(p.port_idx) for p in group_ports if p.port_idx is not None])
     return ports[0] if ports else 10_000
 
 
 def _format_aggregate_connections(
     device_name: str,
-    group_ports: list[object],
+    group_ports: list[PortInfo],
     connections: dict[int, list[str]],
     client_connections: dict[int, list[str]],
     port_map: PortMap,
@@ -436,7 +449,7 @@ def _format_aggregate_connections(
     return ", ".join([item for item in rendered if item])
 
 
-def _format_aggregate_speed(group_ports: list[object]) -> str:
+def _format_aggregate_speed(group_ports: list[PortInfo]) -> str:
     speeds = {getattr(port, "speed", None) for port in group_ports}
     speeds.discard(None)
     if not speeds:
@@ -446,7 +459,7 @@ def _format_aggregate_speed(group_ports: list[object]) -> str:
     return "mixed"
 
 
-def _format_aggregate_poe_state(group_ports: list[object]) -> str:
+def _format_aggregate_poe_state(group_ports: list[PortInfo]) -> str:
     states = {_format_poe_state(port) for port in group_ports}
     if "active" in states:
         return "active"
@@ -457,6 +470,6 @@ def _format_aggregate_poe_state(group_ports: list[object]) -> str:
     return "-"
 
 
-def _format_aggregate_power(group_ports: list[object]) -> 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)
     return _format_poe_power(total)

unifi_network_maps/render/lldp_md.py

@@ -213,63 +213,107 @@ def _client_rows(
     return rows_by_device
 
 
-def render_lldp_md(
+def _prepare_lldp_maps(
     devices: list[Device],
     *,
-    clients: Iterable[object] | None = None,
-    include_ports: bool = False,
-    show_clients: bool = False,
-    client_mode: str = "wired",
-) -> str:
+    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)
-    port_map = {}
-    client_port_map = None
     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)
-    lines: list[str] = ["# LLDP Neighbors", ""]
-    for device in sorted(devices, key=lambda item: item.name.lower()):
-        lines.extend(_device_header_lines(device))
+    return port_map, client_port_map, client_rows
+
+
+def _render_device_lldp_section(
+    lines: list[str],
+    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,
+) -> None:
+    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("| Local Port | Neighbor | Neighbor Port | Chassis ID | Port Description |")
+        lines.append("| --- | --- | --- | --- | --- |")
+        for row in _lldp_rows(device.lldp_info, device_index):
+            lines.append("| " + " | ".join(_escape_cell(cell) for cell in row) + " |")
         lines.append("")
-        lines.extend(_details_table_lines(device, client_rows, client_mode))
+    else:
+        lines.append("_No LLDP neighbors._")
+        lines.append("")
+    rows = client_rows.get(device.name)
+    if rows and show_clients:
+        lines.append("")
+        lines.append("### Clients")
         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(
-                "| Local Port | Neighbor | Neighbor Port | Chassis ID | Port Description |"
-            )
-            lines.append("| --- | --- | --- | --- | --- |")
-            for row in _lldp_rows(device.lldp_info, device_index):
-                lines.append("| " + " | ".join(_escape_cell(cell) for cell in row) + " |")
             lines.append("")
+            lines.append("| Client | Port |")
+            lines.append("| --- | --- |")
+            for client_name, port_label in rows:
+                lines.append(f"| {_escape_cell(client_name)} | {_escape_cell(port_label or '-')} |")
         else:
-            lines.append("_No LLDP neighbors._")
-            lines.append("")
-        rows = client_rows.get(device.name)
-        if rows and show_clients:
-            lines.append("")
-            lines.append("### Clients")
-            if include_ports:
-                lines.append("")
-                lines.append("| Client | Port |")
-                lines.append("| --- | --- |")
-                for client_name, port_label in rows:
-                    lines.append(
-                        f"| {_escape_cell(client_name)} | {_escape_cell(port_label or '-')} |"
-                    )
-            else:
-                for client_name, _port_label in rows:
-                    lines.append(f"- {_escape_cell(client_name)}")
-            lines.append("")
+            for client_name, _port_label in rows:
+                lines.append(f"- {_escape_cell(client_name)}")
+        lines.append("")
+
+
+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,
+    )
+    lines: list[str] = ["# LLDP Neighbors", ""]
+    for device in sorted(devices, key=lambda item: item.name.lower()):
+        _render_device_lldp_section(
+            lines,
+            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,
+        )
     return "\n".join(lines).rstrip() + "\n"