unifi-network-maps 1.3.0__tar.gz → 1.3.1__tar.gz

{unifi_network_maps-1.3.0 → unifi_network_maps-1.3.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: unifi-network-maps
-Version: 1.3.0
+Version: 1.3.1
 Summary: Dynamic UniFi -> network maps in mermaid or svg
 Author: Merlijn
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/merlijntishauser/unifi-network-maps
 Project-URL: Repository, https://github.com/merlijntishauser/unifi-network-maps
 Project-URL: Issues, https://github.com/merlijntishauser/unifi-network-maps/issues
@@ -11,7 +11,6 @@ Project-URL: Changelog, https://github.com/merlijntishauser/unifi-network-maps/b
 Keywords: unifi,mermaid,network,topology,diagram,svg
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: System Administrators
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -23,7 +22,6 @@ Classifier: Topic :: System :: Networking
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-License-File: LICENSES.md
 Requires-Dist: unifi-controller-api
 Requires-Dist: python-dotenv
 Requires-Dist: PyYAML
@@ -109,6 +107,9 @@ SVG size overrides:
 
 ```bash
 unifi-network-maps --format svg --svg-width 1400 --svg-height 900 --output ./network.svg
+
+# LLDP tables for troubleshooting
+unifi-network-maps --format lldp-md --output ./lldp.md
 ```
 
 Legend only:
@@ -142,6 +143,20 @@ git push origin vX.Y.Z
 
 See `LICENSES.md` for third-party license info.
 
+## Installation
+
+PyPI: https://pypi.org/project/unifi-network-maps/
+
+```bash
+pip install unifi-network-maps
+```
+
+Then run:
+
+```bash
+unifi-network-maps --help
+```
+
 ## Options
 
 The CLI groups options by category (`Source`, `Functional`, `Mermaid`, `SVG`, `Output`, `Debug`).
@@ -153,6 +168,7 @@ Source:
 Functional:
 - `--include-ports`: show port labels (Mermaid shows both ends; SVG shows compact labels).
 - `--include-clients`: add active wired clients as leaf nodes.
+- `--client-scope wired|wireless|all`: which client types to include (default wired).
 - `--only-unifi`: only include neighbors that are UniFi devices.
 
 Mermaid:
@@ -165,7 +181,7 @@ SVG:
 - `--theme-file`: load a YAML theme for Mermaid + SVG colors (see `examples/theme.yaml` and `examples/theme-dark.yaml`).
 
 Output:
-- `--format mermaid|svg|svg-iso`: output format (default mermaid).
+- `--format mermaid|svg|svg-iso|lldp-md`: output format (default mermaid).
 - `--stdout`: write output to stdout.
 - `--markdown`: wrap Mermaid output in a code fence.
 
@@ -178,6 +194,7 @@ Debug:
 - Default output is top-to-bottom (TB) and rendered as a hop-based tree from the gateway(s).
 - Nodes are color-coded by type (gateway/switch/AP/client) with a sensible default palette.
 - PoE links are highlighted in blue and annotated with a power icon when detected from `port_table`.
+- Wireless client links render as dashed lines to indicate the last-known upstream.
 - SVG output uses vendored device glyphs from `src/unifi_network_maps/assets/icons`.
 - Isometric SVG output uses MIT-licensed icons from `markmanx/isopacks`.
 - SVG port labels render inside child nodes for readability.

{unifi_network_maps-1.3.0 → unifi_network_maps-1.3.1}/README.md

@@ -73,6 +73,9 @@ SVG size overrides:
 
 ```bash
 unifi-network-maps --format svg --svg-width 1400 --svg-height 900 --output ./network.svg
+
+# LLDP tables for troubleshooting
+unifi-network-maps --format lldp-md --output ./lldp.md
 ```
 
 Legend only:
@@ -106,6 +109,20 @@ git push origin vX.Y.Z
 
 See `LICENSES.md` for third-party license info.
 
+## Installation
+
+PyPI: https://pypi.org/project/unifi-network-maps/
+
+```bash
+pip install unifi-network-maps
+```
+
+Then run:
+
+```bash
+unifi-network-maps --help
+```
+
 ## Options
 
 The CLI groups options by category (`Source`, `Functional`, `Mermaid`, `SVG`, `Output`, `Debug`).
@@ -117,6 +134,7 @@ Source:
 Functional:
 - `--include-ports`: show port labels (Mermaid shows both ends; SVG shows compact labels).
 - `--include-clients`: add active wired clients as leaf nodes.
+- `--client-scope wired|wireless|all`: which client types to include (default wired).
 - `--only-unifi`: only include neighbors that are UniFi devices.
 
 Mermaid:
@@ -129,7 +147,7 @@ SVG:
 - `--theme-file`: load a YAML theme for Mermaid + SVG colors (see `examples/theme.yaml` and `examples/theme-dark.yaml`).
 
 Output:
-- `--format mermaid|svg|svg-iso`: output format (default mermaid).
+- `--format mermaid|svg|svg-iso|lldp-md`: output format (default mermaid).
 - `--stdout`: write output to stdout.
 - `--markdown`: wrap Mermaid output in a code fence.
 
@@ -142,6 +160,7 @@ Debug:
 - Default output is top-to-bottom (TB) and rendered as a hop-based tree from the gateway(s).
 - Nodes are color-coded by type (gateway/switch/AP/client) with a sensible default palette.
 - PoE links are highlighted in blue and annotated with a power icon when detected from `port_table`.
+- Wireless client links render as dashed lines to indicate the last-known upstream.
 - SVG output uses vendored device glyphs from `src/unifi_network_maps/assets/icons`.
 - Isometric SVG output uses MIT-licensed icons from `markmanx/isopacks`.
 - SVG port labels render inside child nodes for readability.

{unifi_network_maps-1.3.0 → unifi_network_maps-1.3.1}/pyproject.toml

@@ -4,17 +4,17 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unifi-network-maps"
-version = "1.3.0"
+version = "1.3.1"
 description = "Dynamic UniFi -> network maps in mermaid or svg"
 readme = "README.md"
 requires-python = ">=3.10"
-license = { text = "MIT" }
+license = "MIT"
+license-files = ["LICENSE"]
 authors = [{ name = "Merlijn" }]
 keywords = ["unifi", "mermaid", "network", "topology", "diagram", "svg"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: System Administrators",
-  "License :: OSI Approved :: MIT License",
   "Operating System :: OS Independent",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",

unifi_network_maps-1.3.1/src/unifi_network_maps/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.3.1"

{unifi_network_maps-1.3.0 → unifi_network_maps-1.3.1}/src/unifi_network_maps/cli/main.py

@@ -18,6 +18,7 @@ from ..model.topology import (
     group_devices_by_type,
     normalize_devices,
 )
+from ..render.lldp_md import render_lldp_md
 from ..render.mermaid import render_legend, render_mermaid
 from ..render.mermaid_theme import MermaidTheme
 from ..render.svg import SvgOptions, render_svg
@@ -65,6 +66,12 @@ def _add_functional_args(parser: argparse._ArgumentGroup) -> None:
         action="store_true",
         help="Include active clients as leaf nodes",
     )
+    parser.add_argument(
+        "--client-scope",
+        choices=["wired", "wireless", "all"],
+        default="wired",
+        help="Client types to include (default: wired)",
+    )
     parser.add_argument(
         "--only-unifi", action="store_true", help="Only include neighbors that are UniFi devices"
     )
@@ -94,7 +101,7 @@ def _add_general_render_args(parser: argparse._ArgumentGroup) -> None:
     parser.add_argument(
         "--format",
         default="mermaid",
-        choices=["mermaid", "svg", "svg-iso"],
+        choices=["mermaid", "svg", "svg-iso", "lldp-md"],
         help="Output format",
     )
     parser.add_argument(
@@ -147,13 +154,20 @@ def _render_legend_only(args: argparse.Namespace, mermaid_theme: MermaidTheme) -
     return content
 
 
-def _build_topology_data(
+def _load_devices_data(
     args: argparse.Namespace, config: Config, site: str
-) -> tuple[list[Device], list[str], object]:
+) -> tuple[list[object], list[Device]]:
     raw_devices = list(fetch_devices(config, site=site, detailed=True))
     devices = normalize_devices(raw_devices)
     if args.debug_dump:
         debug_dump_devices(raw_devices, devices, sample_count=max(0, args.debug_sample))
+    return raw_devices, devices
+
+
+def _build_topology_data(
+    args: argparse.Namespace, config: Config, site: str
+) -> tuple[list[Device], list[str], object]:
+    _raw_devices, devices = _load_devices_data(args, config, site)
     groups_for_rank = group_devices_by_type(devices)
     gateways = groups_for_rank.get("gateway", [])
     topology = build_topology(
@@ -176,7 +190,12 @@ def _build_edges_with_clients(
     if args.include_clients:
         clients = list(fetch_clients(config, site=site))
         device_index = build_device_index(devices)
-        edges = edges + build_client_edges(clients, device_index, include_ports=args.include_ports)
+        edges = edges + build_client_edges(
+            clients,
+            device_index,
+            include_ports=args.include_ports,
+            client_mode=args.client_scope,
+        )
     return edges, clients
 
 
@@ -207,7 +226,7 @@ def _render_mermaid_output(
         direction=args.direction,
         groups=groups,
         group_order=group_order,
-        node_types=build_node_type_map(devices, clients),
+        node_types=build_node_type_map(devices, clients, client_mode=args.client_scope),
         theme=mermaid_theme,
     )
     if args.markdown:
@@ -233,13 +252,13 @@ def _render_svg_output(
 
         return render_svg_isometric(
             edges,
-            node_types=build_node_type_map(devices, clients),
+            node_types=build_node_type_map(devices, clients, client_mode=args.client_scope),
             options=options,
             theme=svg_theme,
         )
     return render_svg(
         edges,
-        node_types=build_node_type_map(devices, clients),
+        node_types=build_node_type_map(devices, clients, client_mode=args.client_scope),
         options=options,
         theme=svg_theme,
     )
@@ -259,6 +278,23 @@ def main(argv: list[str] | None = None) -> int:
         write_output(content, output_path=args.output, stdout=args.stdout)
         return 0
 
+    if args.format == "lldp-md":
+        try:
+            _raw_devices, devices = _load_devices_data(args, config, site)
+        except Exception as exc:
+            logging.error("Failed to load devices: %s", exc)
+            return 1
+        clients = list(fetch_clients(config, site=site))
+        content = render_lldp_md(
+            devices,
+            clients=clients,
+            include_ports=args.include_ports,
+            show_clients=args.include_clients,
+            client_mode=args.client_scope,
+        )
+        write_output(content, output_path=args.output, stdout=args.stdout)
+        return 0
+
     try:
         devices, _gateways, topology = _build_topology_data(args, config, site)
     except Exception as exc:

{unifi_network_maps-1.3.0 → unifi_network_maps-1.3.1}/src/unifi_network_maps/model/topology.py

@@ -27,6 +27,7 @@ class Device:
     poe_ports: dict[int, bool] = field(default_factory=dict)
     uplink: UplinkInfo | None = None
     last_uplink: UplinkInfo | None = None
+    version: str = ""
 
 
 @dataclass(frozen=True)
@@ -35,6 +36,7 @@ class Edge:
     right: str
     label: str | None = None
     poe: bool = False
+    wireless: bool = False
 
 
 class DeviceLike(Protocol):
@@ -56,6 +58,8 @@ class DeviceLike(Protocol):
     last_uplink_mac: object | None
     uplink_device_name: object | None
     uplink_remote_port: object | None
+    version: object | None
+    displayable_version: object | None
 
 
 @dataclass(frozen=True)
@@ -242,6 +246,7 @@ def coerce_device(device: DeviceLike) -> Device:
     mac = _get_attr(device, "mac")
     ip = _get_attr(device, "ip") or _get_attr(device, "ip_address")
     dev_type = _get_attr(device, "type") or _get_attr(device, "device_type")
+    version = _get_attr(device, "displayable_version") or _get_attr(device, "version")
     lldp_info = _get_attr(device, "lldp_info")
     if lldp_info is None:
         lldp_info = _get_attr(device, "lldp")
@@ -271,6 +276,7 @@ def coerce_device(device: DeviceLike) -> Device:
         poe_ports=poe_ports,
         uplink=uplink,
         last_uplink=last_uplink,
+        version=str(version or ""),
     )
 
 
@@ -407,16 +413,26 @@ 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 build_client_edges(
     clients: Iterable[object],
     device_index: dict[str, str],
     *,
     include_ports: bool = False,
+    client_mode: str = "wired",
 ) -> list[Edge]:
     edges: list[Edge] = []
     seen: set[tuple[str, str]] = set()
     for client in clients:
-        if not _client_is_wired(client):
+        if not _client_matches_mode(client, client_mode):
             continue
         name = _client_display_name(client)
         uplink_mac = _client_uplink_mac(client)
@@ -433,20 +449,30 @@ def build_client_edges(
         key = (device_name, name)
         if key in seen:
             continue
-        edges.append(Edge(left=device_name, right=name, label=label))
+        edges.append(
+            Edge(
+                left=device_name,
+                right=name,
+                label=label,
+                wireless=not _client_is_wired(client),
+            )
+        )
         seen.add(key)
     return edges
 
 
 def build_node_type_map(
-    devices: Iterable[Device], clients: Iterable[object] | None = None
+    devices: Iterable[Device],
+    clients: Iterable[object] | None = None,
+    *,
+    client_mode: str = "wired",
 ) -> dict[str, str]:
     node_types: dict[str, str] = {}
     for device in devices:
         node_types[device.name] = classify_device_type(device)
     if clients:
         for client in clients:
-            if not _client_is_wired(client):
+            if not _client_matches_mode(client, client_mode):
                 continue
             name = _client_display_name(client)
             if name:

unifi_network_maps-1.3.1/src/unifi_network_maps/render/lldp_md.py

@@ -0,0 +1,254 @@
+"""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.topology import Device, build_device_index
+
+
+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 key in ("uplink_remote_port", "sw_port", "ap_port"):
+        value = _client_field(client, key)
+        if isinstance(value, int):
+            return value
+        if isinstance(value, str) and value.isdigit():
+            return int(value)
+    for key in ("uplink", "last_uplink"):
+        nested = _client_field(client, key)
+        if isinstance(nested, dict):
+            value = nested.get("uplink_remote_port")
+            if isinstance(value, int):
+                return value
+            if isinstance(value, str) and value.isdigit():
+                return int(value)
+    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 _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
+
+
+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 _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})"
+    lines = [
+        "### Details",
+        "",
+        "| Field | Value |",
+        "| --- | --- |",
+        f"| Firmware | {_escape_cell(device.version or '-')} |",
+        f"| Uplink | {_escape_cell(_uplink_summary(device))} |",
+        f"| Ports | {_escape_cell(_port_summary(device))} |",
+        f"| {client_label} | {_escape_cell(wired_count)} |",
+        f"| Client examples | {_escape_cell(client_sample)} |",
+        "",
+    ]
+    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 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)
+    client_rows = (
+        _client_rows(clients, device_index, include_ports=include_ports, client_mode=client_mode)
+        if clients
+        else {}
+    )
+    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 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("")
+        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("")
+    return "\n".join(lines).rstrip() + "\n"

{unifi_network_maps-1.3.0 → unifi_network_maps-1.3.1}/src/unifi_network_maps/render/mermaid.py

@@ -71,6 +71,7 @@ def render_mermaid(
     id_map = _build_id_map(edge_list, group_nodes)
     lines = [f"graph {direction}"]
     poe_links: list[int] = []
+    wireless_links: list[int] = []
     link_index = 0
     if groups:
         ordered = group_order or list(groups.keys())
@@ -99,6 +100,8 @@ def render_mermaid(
             lines.append(f"  {left} --- {right};")
         if edge.poe:
             poe_links.append(link_index)
+        if edge.wireless:
+            wireless_links.append(link_index)
         link_index += 1
     if node_types:
         class_map = {
@@ -121,6 +124,8 @@ def render_mermaid(
             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;")
     return "\n".join(lines) + "\n"