unifi-network-maps 1.4.4__py3-none-any.whl → 1.4.5__py3-none-any.whl

unifi_network_maps/render/legend.py

@@ -0,0 +1,30 @@
+"""Legend rendering helpers."""
+
+from __future__ import annotations
+
+from .mermaid import render_legend, render_legend_compact
+from .mermaid_theme import MermaidTheme
+
+
+def resolve_legend_style(*, format_name: str, legend_style: str) -> str:
+    if legend_style == "auto":
+        return "compact" if format_name == "mkdocs" else "diagram"
+    return legend_style
+
+
+def render_legend_only(
+    *,
+    legend_style: str,
+    legend_scale: float,
+    markdown: bool,
+    theme: MermaidTheme,
+) -> str:
+    if legend_style == "compact":
+        content = "# Legend\n\n" + render_legend_compact(theme=theme)
+    else:
+        content = render_legend(theme=theme, legend_scale=legend_scale)
+    if markdown:
+        content = f"""```mermaid
+{content}```
+"""
+    return content

unifi_network_maps/render/lldp_md.py

@@ -7,6 +7,8 @@ from collections.abc import Iterable
 from ..model.lldp import LLDPEntry, local_port_label
 from ..model.topology import Device, build_client_port_map, build_device_index, build_port_map
 from .device_ports_md import render_device_port_details
+from .markdown_tables import markdown_table_lines
+from .templating import render_template
 
 
 def _normalize_mac(value: str) -> str:
@@ -78,10 +80,6 @@ def _lldp_sort_key(entry: LLDPEntry) -> tuple[int, str, str]:
     return (int(port_number or 0), port_label, entry.port_id)
 
 
-def _device_header_lines(device: Device) -> list[str]:
-    return [f"## {device.name}"]
-
-
 def _port_summary(device: Device) -> str:
     ports = [port for port in device.port_table if port.port_idx is not None]
     if not ports:
@@ -140,23 +138,20 @@ def _details_table_lines(
 ) -> list[str]:
     wired_count, client_sample = _client_summary(device, client_rows)
     client_label = f"Clients ({client_mode})"
-    lines = [
-        "### Details",
-        "",
-        "| 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)} |",
-        "",
+    rows = [
+        ["Model", _escape_cell(device.model_name or device.type or "-")],
+        ["Type", _escape_cell(device.type or "-")],
+        ["IP", _escape_cell(device.ip or "-")],
+        ["MAC", _escape_cell(device.mac or "-")],
+        ["Firmware", _escape_cell(device.version or "-")],
+        ["Uplink", _escape_cell(_uplink_summary(device))],
+        ["Ports", _escape_cell(_port_summary(device))],
+        ["PoE", _escape_cell(_poe_summary(device))],
+        [client_label, _escape_cell(wired_count)],
+        ["Client examples", _escape_cell(client_sample)],
     ]
+    lines = ["### Details", ""]
+    lines.extend(markdown_table_lines(["Field", "Value"], rows))
     return lines
 
 
@@ -241,7 +236,6 @@ def _prepare_lldp_maps(
 
 
 def _render_device_lldp_section(
-    lines: list[str],
     device: Device,
     *,
     device_index: dict[str, str],
@@ -251,40 +245,58 @@ def _render_device_lldp_section(
     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))
+) -> str:
+    details = "\n".join(_details_table_lines(device, client_rows, client_mode)).rstrip()
+    ports_section = ""
     if include_ports:
-        lines.append("### Ports")
-        lines.append("")
-        lines.append(
-            render_device_port_details(device, port_map, client_ports=client_port_map).strip()
-        )
+        ports_section = "\n".join(
+            [
+                "### Ports",
+                "",
+                render_device_port_details(device, port_map, client_ports=client_port_map).strip(),
+            ]
+        ).rstrip()
     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("")
+        lldp_section = "\n".join(
+            markdown_table_lines(
+                ["Local Port", "Neighbor", "Neighbor Port", "Chassis ID", "Port Description"],
+                _lldp_rows(device.lldp_info, device_index),
+                escape=_escape_cell,
+            )
+        ).rstrip()
     else:
-        lines.append("_No LLDP neighbors._")
-        lines.append("")
+        lldp_section = "_No LLDP neighbors._"
+    clients_section = ""
     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 '-')} |")
+            clients_section = "\n".join(
+                [
+                    "### Clients",
+                    "",
+                    "\n".join(
+                        markdown_table_lines(
+                            ["Client", "Port"],
+                            [
+                                [_escape_cell(client_name), _escape_cell(port_label or "-")]
+                                for client_name, port_label in rows
+                            ],
+                        )
+                    ),
+                ]
+            ).rstrip()
         else:
-            for client_name, _port_label in rows:
-                lines.append(f"- {_escape_cell(client_name)}")
-        lines.append("")
+            clients_section = "\n".join(
+                ["### Clients", *[f"- {_escape_cell(name)}" for name, _ in rows]]
+            ).rstrip()
+    return render_template(
+        "lldp_device_section.md.j2",
+        device_name=device.name,
+        details=details,
+        ports_section=ports_section,
+        lldp_section=lldp_section,
+        clients_section=clients_section,
+    ).rstrip()
 
 
 def render_lldp_md(
@@ -303,17 +315,26 @@ def render_lldp_md(
         show_clients=show_clients,
         client_mode=client_mode,
     )
-    lines: list[str] = ["# LLDP Neighbors", ""]
+    sections: list[str] = []
     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,
+        sections.append(
+            _render_device_lldp_section(
+                device,
+                device_index=device_index,
+                port_map=port_map,
+                client_port_map=client_port_map,
+                client_rows=client_rows,
+                include_ports=include_ports,
+                show_clients=show_clients,
+                client_mode=client_mode,
+            )
         )
-    return "\n".join(lines).rstrip() + "\n"
+    body = "\n\n".join(section for section in sections if section).rstrip()
+    return (
+        render_template(
+            "markdown_section.md.j2",
+            title="LLDP Neighbors",
+            body=body,
+        ).rstrip()
+        + "\n"
+    )

unifi_network_maps/render/markdown_tables.py

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

unifi_network_maps/render/mermaid.py

@@ -7,6 +7,7 @@ from collections.abc import Iterable
 
 from ..model.topology import Edge
 from .mermaid_theme import DEFAULT_THEME, MermaidTheme, class_defs
+from .templating import render_template
 
 
 def _escape(label: str) -> str:
@@ -193,94 +194,80 @@ def render_legend(theme: MermaidTheme = DEFAULT_THEME, *, legend_scale: float =
     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"];',
-        '    legend_switch["Switch"];',
-        '    legend_ap["AP"];',
-        '    legend_client["Client"];',
-        '    legend_other["Other"];',
-        '    legend_poe_a["PoE Link A"];',
-        '    legend_poe_b["PoE Link B"];',
-        '    legend_no_poe_a["Link A"];',
-        '    legend_no_poe_b["Link B"];',
-        "    legend_poe_a ---|⚡| legend_poe_b;",
-        "    legend_no_poe_a --- legend_no_poe_b;",
-        "    linkStyle 0 arrowhead:none;",
-        "    linkStyle 1 arrowhead:none;",
-        "  end",
-        "  class legend_gateway node_gateway;",
-        "  class legend_switch node_switch;",
-        "  class legend_ap node_ap;",
-        "  class legend_client node_client;",
-        "  class legend_other node_other;",
-        "  class legend_poe_a node_legend;",
-        "  class legend_poe_b node_legend;",
-        "  class legend_no_poe_a node_legend;",
-        "  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:{poe_link_width}px,"
-        f"arrowhead:{theme.poe_link_arrow};"
-    )
-    lines.append(
-        "  linkStyle 1 "
-        f"stroke:{theme.standard_link},stroke-width:{standard_link_width}px,"
-        f"arrowhead:{theme.standard_link_arrow};"
+    return (
+        render_template(
+            "mermaid_legend.mmd.j2",
+            node_spacing=node_spacing,
+            rank_spacing=rank_spacing,
+            legend_font_size=legend_font_size,
+            node_padding=node_padding,
+            class_defs="\n".join(class_defs(theme)),
+            poe_link=theme.poe_link,
+            poe_link_width=poe_link_width,
+            poe_link_arrow=theme.poe_link_arrow,
+            standard_link=theme.standard_link,
+            standard_link_width=standard_link_width,
+            standard_link_arrow=theme.standard_link_arrow,
+        ).rstrip()
+        + "\n"
     )
-    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"),
+        {
+            "kind": "swatch",
+            "fill": theme.node_gateway[0],
+            "stroke": theme.node_gateway[1],
+            "label": "Gateway",
+        },
+        {
+            "kind": "swatch",
+            "fill": theme.node_switch[0],
+            "stroke": theme.node_switch[1],
+            "label": "Switch",
+        },
+        {
+            "kind": "swatch",
+            "fill": theme.node_ap[0],
+            "stroke": theme.node_ap[1],
+            "label": "AP",
+        },
+        {
+            "kind": "swatch",
+            "fill": theme.node_client[0],
+            "stroke": theme.node_client[1],
+            "label": "Client",
+        },
+        {
+            "kind": "swatch",
+            "fill": theme.node_other[0],
+            "stroke": theme.node_other[1],
+            "label": "Other",
+        },
+        {
+            "kind": "line",
+            "color": theme.poe_link,
+            "width": max(1, theme.poe_link_width),
+            "dashed": False,
+            "label": "PoE",
+            "bolt": True,
+        },
+        {
+            "kind": "line",
+            "color": theme.standard_link,
+            "width": max(1, theme.standard_link_width),
+            "dashed": False,
+            "label": "Link",
+            "bolt": False,
+        },
+        {
+            "kind": "line",
+            "color": theme.standard_link,
+            "width": max(1, theme.standard_link_width),
+            "dashed": True,
+            "label": "Wireless",
+            "bolt": False,
+        },
     ]
-    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"
+    return render_template("legend_compact.html.j2", rows=rows)

unifi_network_maps/render/mkdocs.py

@@ -0,0 +1,167 @@
+"""MkDocs-specific rendering helpers."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime
+from zoneinfo import ZoneInfo
+
+from ..model.topology import ClientPortMap, Device, PortMap, build_node_type_map
+from .device_ports_md import render_device_port_overview
+from .mermaid import render_legend, render_legend_compact, render_mermaid
+from .mermaid_theme import MermaidTheme
+from .templating import render_template
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class MkdocsRenderOptions:
+    direction: str
+    legend_style: str
+    legend_scale: float
+    timestamp_zone: str
+    client_scope: str
+    dual_theme: bool
+
+
+def render_mkdocs(
+    edges: list,
+    devices: list[Device],
+    *,
+    mermaid_theme: MermaidTheme,
+    port_map: PortMap,
+    client_ports: ClientPortMap | None,
+    options: MkdocsRenderOptions,
+    dark_mermaid_theme: MermaidTheme | None = None,
+) -> str:
+    clients = None
+    node_types = build_node_type_map(devices, clients, client_mode=options.client_scope)
+    content = render_mermaid(
+        edges,
+        direction=options.direction,
+        node_types=node_types,
+        theme=mermaid_theme,
+    )
+    dual_theme = options.dual_theme and dark_mermaid_theme is not None
+    legend_title = "Legend" if options.legend_style != "compact" else ""
+    if dual_theme and dark_mermaid_theme is not None:
+        dark_content = render_mermaid(
+            edges,
+            direction=options.direction,
+            node_types=node_types,
+            theme=dark_mermaid_theme,
+        )
+        map_block = _mkdocs_dual_mermaid_block(content, dark_content, base_class="unifi-mermaid")
+        legend_block = _mkdocs_dual_legend_block(
+            options.legend_style,
+            mermaid_theme=mermaid_theme,
+            dark_mermaid_theme=dark_mermaid_theme,
+            legend_scale=options.legend_scale,
+        )
+        dual_style = _mkdocs_dual_theme_style()
+    else:
+        map_block = _mkdocs_mermaid_block(content, class_name="unifi-mermaid")
+        legend_block = _mkdocs_single_legend_block(
+            options.legend_style,
+            mermaid_theme=mermaid_theme,
+            legend_scale=options.legend_scale,
+        )
+        dual_style = ""
+    return render_template(
+        "mkdocs_document.md.j2",
+        title="UniFi network",
+        timestamp_line=_timestamp_line(options.timestamp_zone),
+        dual_style=dual_style,
+        map_block=map_block,
+        legend_title=legend_title,
+        legend_block=legend_block,
+        device_overview=render_device_port_overview(
+            devices, port_map, client_ports=client_ports
+        ).rstrip()
+        + "\n",
+    )
+
+
+def _timestamp_line(timestamp_zone: str) -> str:
+    if timestamp_zone.strip().lower() in {"off", "none", "false"}:
+        return ""
+    try:
+        zone = ZoneInfo(timestamp_zone)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Invalid mkdocs timestamp zone '%s': %s", timestamp_zone, exc)
+        return ""
+    generated_at = datetime.now(zone).strftime("%Y-%m-%d %H:%M:%S %Z")
+    return f"Generated: {generated_at}"
+
+
+def _mkdocs_mermaid_block(content: str, *, class_name: str) -> str:
+    return render_template(
+        "mkdocs_mermaid_block.md.j2",
+        class_name=class_name,
+        content=content,
+    )
+
+
+def _mkdocs_dual_mermaid_block(
+    light_content: str,
+    dark_content: str,
+    *,
+    base_class: str,
+) -> str:
+    light = _mkdocs_mermaid_block(light_content, class_name=f"{base_class} {base_class}--light")
+    dark = _mkdocs_mermaid_block(dark_content, class_name=f"{base_class} {base_class}--dark")
+    return f"{light}\n{dark}"
+
+
+def _mkdocs_single_legend_block(
+    legend_style: str,
+    *,
+    mermaid_theme: MermaidTheme,
+    legend_scale: float,
+) -> str:
+    if legend_style == "compact":
+        return render_template(
+            "mkdocs_html_block.html.j2",
+            class_name="unifi-legend",
+            data_unifi_legend=True,
+            content=render_legend_compact(theme=mermaid_theme),
+        )
+    return "```mermaid\n" + render_legend(theme=mermaid_theme, legend_scale=legend_scale) + "```"
+
+
+def _mkdocs_dual_legend_block(
+    legend_style: str,
+    *,
+    mermaid_theme: MermaidTheme,
+    dark_mermaid_theme: MermaidTheme,
+    legend_scale: float,
+) -> str:
+    if legend_style == "compact":
+        light = render_template(
+            "mkdocs_html_block.html.j2",
+            class_name="unifi-legend unifi-legend--light",
+            data_unifi_legend=True,
+            content=render_legend_compact(theme=mermaid_theme),
+        )
+        dark = render_template(
+            "mkdocs_html_block.html.j2",
+            class_name="unifi-legend unifi-legend--dark",
+            data_unifi_legend=True,
+            content=render_legend_compact(theme=dark_mermaid_theme),
+        )
+        return f"{light}\n{dark}"
+    light = _mkdocs_mermaid_block(
+        render_legend(theme=mermaid_theme, legend_scale=legend_scale),
+        class_name="unifi-legend unifi-legend--light",
+    )
+    dark = _mkdocs_mermaid_block(
+        render_legend(theme=dark_mermaid_theme, legend_scale=legend_scale),
+        class_name="unifi-legend unifi-legend--dark",
+    )
+    return f"{light}\n{dark}"
+
+
+def _mkdocs_dual_theme_style() -> str:
+    return render_template("mkdocs_dual_theme_style.html.j2") + "\n"

unifi_network_maps/render/templates/device_port_block.md.j2

@@ -0,0 +1,5 @@
+### {{ device_name }}
+
+{{ details }}
+
+{{ ports }}

unifi_network_maps/render/templates/legend_compact.html.j2

@@ -0,0 +1,14 @@
+<table class="unifi-legend-table">
+<tbody>
+{% for row in rows %}
+  <tr><td>
+{% if row.kind == "swatch" %}
+    <span style="display:inline-block;width:12px;height:12px;background:{{ row.fill }};border:1px solid {{ row.stroke }};border-radius:2px;margin-right:6px;"></span>{{ row.label }}
+{% else %}
+    <span style="display:inline-flex;align-items:center;gap:6px;">
+      <svg width="42" height="10" viewBox="0 0 42 10" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><line x1="2" y1="5" x2="40" y2="5" stroke="{{ row.color }}" stroke-width="{{ row.width }}"{% if row.dashed %} stroke-dasharray="5 4"{% endif %} /></svg>{{ row.label }}{%- if row.bolt %} ⚡{%- endif %}</span>
+{% endif %}
+  </td></tr>
+{% endfor %}
+</tbody>
+</table>

unifi_network_maps/render/templates/lldp_device_section.md.j2

@@ -0,0 +1,15 @@
+## {{ device_name }}
+
+{{ details }}
+{% if ports_section %}
+
+{{ ports_section }}
+{% endif %}
+{% if lldp_section %}
+
+{{ lldp_section }}
+{% endif %}
+{% if clients_section %}
+
+{{ clients_section }}
+{% endif %}

unifi_network_maps/render/templates/markdown_section.md.j2

@@ -0,0 +1,3 @@
+## {{ title }}
+
+{{ body }}

unifi_network_maps/render/templates/mermaid_legend.mmd.j2

@@ -0,0 +1,30 @@
+%%{init: {"flowchart": {"nodeSpacing": {{ node_spacing }}, "rankSpacing": {{ rank_spacing }}}, "themeVariables": {"fontSize": "{{ legend_font_size }}px", "nodePadding": {{ node_padding }}}}}%%
+graph TB
+  subgraph legend["Legend"];
+    legend_gateway["Gateway"];
+    legend_switch["Switch"];
+    legend_ap["AP"];
+    legend_client["Client"];
+    legend_other["Other"];
+    legend_poe_a["PoE Link A"];
+    legend_poe_b["PoE Link B"];
+    legend_no_poe_a["Link A"];
+    legend_no_poe_b["Link B"];
+    legend_poe_a ---|⚡| legend_poe_b;
+    legend_no_poe_a --- legend_no_poe_b;
+    linkStyle 0 arrowhead:none;
+    linkStyle 1 arrowhead:none;
+  end
+  class legend_gateway node_gateway;
+  class legend_switch node_switch;
+  class legend_ap node_ap;
+  class legend_client node_client;
+  class legend_other node_other;
+  class legend_poe_a node_legend;
+  class legend_poe_b node_legend;
+  class legend_no_poe_a node_legend;
+  class legend_no_poe_b node_legend;
+{{ class_defs }}
+  classDef node_legend font-size:{{ legend_font_size }}px;
+  linkStyle 0 stroke:{{ poe_link }},stroke-width:{{ poe_link_width }}px,arrowhead:{{ poe_link_arrow }};
+  linkStyle 1 stroke:{{ standard_link }},stroke-width:{{ standard_link_width }}px,arrowhead:{{ standard_link_arrow }};