unifi-network-maps 1.4.5__tar.gz → 1.4.6__tar.gz

unifi_network_maps-1.4.6/CHANGELOG.md

@@ -0,0 +1,165 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.4.6] - 2026-01-15
+### Added
+- Home Assistant docs pointing to the standalone integration repo.
+
+### Changed
+- Home Assistant integration work moved to `unifi-network-maps-ha`; core repo focuses on renderer + CLI.
+
+### Removed
+- HA POC export module, CLI flag, BDD scenarios, and smoketest outputs (now in the HA repo).
+
+### Fixed
+- BDD theme-file scenario
+- SVG links render correctly for vertically stacked nodes.
+- Publish workflow now checks out the tagged source before building.
+
+## [1.4.5] - 2026-01-11
+### Added
+- Jinja2 templating for MkDocs output, Mermaid legend blocks, and Markdown sections.
+- MkDocs sidebar assets and legend HTML blocks moved into reusable templates.
+- BDD scenarios for module/console entrypoints plus additional CLI validation errors.
+
+### Changed
+- Refactored CLI orchestration into focused CLI/render/runtime modules.
+- Extracted MkDocs rendering and sidebar asset output into dedicated modules.
+- Moved mock generation into the model layer with a thin IO facade.
+- Centralized legend rendering helpers and shared markdown table utilities.
+- Publish workflow now runs only after successful tagged CI.
+- Added explicit workflow permissions to CI/CodeQL workflows.
+
+### Fixed
+- CLI error handling for invalid theme file paths.
+
+### Security
+- Enabled Jinja2 autoescaping for HTML templates and marked trusted HTML blocks safe.
+
+## [1.4.4] - 2026-01-11
+### Added
+- Added smoke tests for dual-theme MkDocs sidebar legend output.
+
+### Changed
+- Improved dark theme Mermaid readability (labels + link borders).
+
+### Fixed
+- MkDocs sidebar legend duplication with dual-theme output.
+
+## [1.4.2] - 2026-01-10
+### Added
+- Static code analysis and stricter type-checking.
+- Contract tests for UniFi API wrapper with fixture-based validation.
+- Optional live UniFi contract tests (gated by `UNIFI_CONTRACT_LIVE=1`).
+- Split CI into dedicated jobs and added a contract-test job.
+- Behave-based BDD tests covering CLI outputs, mkdocs assets, and error handling.
+- Mkdocs timestamp (timezone configurable via `--mkdocs-timestamp-zone`).
+- Optional dual Mermaid blocks for MkDocs Material theme switching (`--mkdocs-dual-theme`).
+- `--no-cache` to bypass UniFi API cache reads/writes.
+- File locking around cache read/write operations to avoid concurrent corruption.
+- Optional UniFi API request timeouts via `UNIFI_REQUEST_TIMEOUT_SECONDS`.
+- Made `--output` writes atomic to avoid partial files on interruption.
+
+### Changed
+- Switched UniFi API cache payloads to JSON for safer local storage.
+- Skips cache usage when the cache directory is group/world-writable.
+
+### Fixed
+- Hardened Mermaid label escaping for newlines and backslashes.
+- Device cache serialization to preserve LLDP data when caching.
+
+## [1.4.1] - 2026-01-06
+### Fixed
+- Fixed pip install failure.
+
+## [1.4.0] - 2026-01-06
+### Added
+- MkDocs output with gateway/switch details and per-port tables.
+- Port tables show speed, PoE status, power, and wired clients per port.
+- Compact legend with sidebar injection (`--mkdocs-sidebar-legend`).
+- LLDP markdown includes the same device details and port tables when enabled.
+- `--mock-data` for safe, offline rendering from fixtures.
+- Faker-powered `--generate-mock` for deterministic mock fixtures (dev-only).
+- Mock fixtures + SVG/Mermaid examples, with mock smoketest/CI steps.
+
+### Changed
+- Improved uplink labeling (gateway shows Internet for WAN/unknown).
+- Aggregated ports are combined into single LAG rows.
+- Bumped minimum Python to 3.13 and aligned CI to 3.13.
+- Pinned runtime/dev/build dependencies and added `requirements*.txt` + `constraints.txt`.
+
+## [1.3.1] - 2026-01-04
+### Added
+- `lldp-md` output with per-device details tables and optional client sections.
+- `--client-scope wired|wireless|all` and dashed wireless client links in Mermaid/SVG.
+- Expanded smoketest outputs for wireless/all client scopes and LLDP markdown.
+
+### Fixed
+- Fixed SVG icon loading paths after package reorg.
+
+### Changed
+- Isometric port label placement on front tiles.
+
+## [1.3.0] - 2026-01-04
+### Added
+- YAML-based theming with default + dark themes and `--theme-file`.
+
+### Changed
+- Reorganized package into submodules (`adapters/`, `model/`, `render/`, `io/`, `cli/`).
+- CLI help now grouped by category; CLI logic split into focused helpers.
+- Isometric SVG layout constants centralized; extra viewBox padding to avoid clipping.
+- LLDP port index fallback matches `port_table` `ifname`/`name`.
+- Added PoE/edge/device count logging and improved label ordering helpers.
+- Coverage excludes asset packages; docs updated (options/groups + AI disclosure).
+
+## [1.2.4] - 2026-01-03
+### Added
+- Typed `UplinkInfo`/`PortInfo` and uplink fallback for LLDP gaps.
+- CI publish workflow (trusted publishing) and release docs.
+- Project metadata and packaging updated for OSS readiness.
+
+### Changed
+- Deterministic edge ordering for repeatable output.
+
+## [1.1.0] - 2026-01-03
+### Added
+- Isometric SVG output with grid-aligned links and isometric icon set.
+- Smoketest target with multiple outputs (ports/clients/legend).
+- UniFi API response caching with TTL.
+
+### Changed
+- Improved port label placement and client labeling in SVG outputs.
+- Refined visuals: link gradients, tile gradients, icon placement tweaks.
+
+### Fixed
+- Mermaid legend/grouped output parsing errors.
+
+## [1.0.0] - 2025-12-30
+### Added
+- Mermaid legend can render as a separate graph.
+- Straight Mermaid links with node type coloring.
+- Wired client leaf nodes and uplink port labels.
+- CLI loads `.env` automatically.
+
+## [0.2.0] - 2026-01-02
+### Added
+- Versioning workflow and bump tooling.
+- Introduced SVG renderer and tree layout fixes.
+- Increased test coverage and added coverage tooling.
+
+[Unreleased]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.5...HEAD
+[1.4.5]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.4...v1.4.5
+[1.4.4]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.2...v1.4.4
+[1.4.2]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.1...v1.4.2
+[1.4.1]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.4.0...v1.4.1
+[1.4.0]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.3.1...v1.4.0
+[1.3.1]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.3.0...v1.3.1
+[1.3.0]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.2.4...v1.3.0
+[1.2.4]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.1.0...v1.2.4
+[1.1.0]: https://github.com/merlijntishauser/unifi-network-maps/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/merlijntishauser/unifi-network-maps/compare/v0.2.0...v1.0.0
+[0.2.0]: https://github.com/merlijntishauser/unifi-network-maps/releases/tag/v0.2.0

{unifi_network_maps-1.4.5 → unifi_network_maps-1.4.6}/CONTRIBUTING.md

@@ -83,7 +83,7 @@ See `LICENSES.md` for third-party license info.
 
   - Automated UniFi → Mermaid/SVG (incl. isometric) output, with ports/PoE/clients.
   - Deterministic CLI + cache + mock generator for CI and docs.
-  - MkDocs/Markdown output plus planned HA‑friendly artifacts.
+  - MkDocs/Markdown output plus a separate HA integration repo for live updates.
   - A clean render pipeline that can power multiple export targets.
 
   So we’re not duplicating a packaged workflow; we’re combining data + topology modeling + diagram output + documentation/export in a way I haven’t seen in one place.

{unifi_network_maps-1.4.5 → unifi_network_maps-1.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unifi-network-maps
-Version: 1.4.5
+Version: 1.4.6
 Summary: Dynamic UniFi -> network maps in mermaid or svg
 Author: Merlijn
 License-Expression: MIT
@@ -144,6 +144,11 @@ Legend only:
 unifi-network-maps --legend-only --stdout
 ```
 
+## Home Assistant integration
+
+The live Home Assistant integration (Config Flow + coordinator + custom card) lives in a separate repo:
+- https://github.com/merlijntishauser/unifi-network-maps-ha
+
 ## Examples (mock data)
 
 These examples are generated from `examples/mock_data.json` (safe, anonymized fixture).

{unifi_network_maps-1.4.5 → unifi_network_maps-1.4.6}/README.md

@@ -108,6 +108,11 @@ Legend only:
 unifi-network-maps --legend-only --stdout
 ```
 
+## Home Assistant integration
+
+The live Home Assistant integration (Config Flow + coordinator + custom card) lives in a separate repo:
+- https://github.com/merlijntishauser/unifi-network-maps-ha
+
 ## Examples (mock data)
 
 These examples are generated from `examples/mock_data.json` (safe, anonymized fixture).

{unifi_network_maps-1.4.5 → unifi_network_maps-1.4.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unifi-network-maps"
-version = "1.4.5"
+version = "1.4.6"
 description = "Dynamic UniFi -> network maps in mermaid or svg"
 readme = "README.md"
 requires-python = ">=3.13"

unifi_network_maps-1.4.6/src/unifi_network_maps/__init__.py

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

{unifi_network_maps-1.4.5 → unifi_network_maps-1.4.6}/src/unifi_network_maps/cli/main.py

@@ -90,7 +90,11 @@ def main(argv: list[str] | None = None) -> int:
     except ValueError as exc:
         logging.error(str(exc))
         return 2
-    mermaid_theme, svg_theme = resolve_themes(args.theme_file)
+    try:
+        mermaid_theme, svg_theme = resolve_themes(args.theme_file)
+    except Exception as exc:  # noqa: BLE001
+        logging.error("Failed to load theme file: %s", exc)
+        return 2
 
     if args.legend_only:
         legend_style = resolve_legend_style(

{unifi_network_maps-1.4.5 → unifi_network_maps-1.4.6}/src/unifi_network_maps/render/svg.py

@@ -6,6 +6,7 @@ import base64
 import math
 from collections.abc import Callable
 from dataclasses import dataclass
+from html import escape as _escape_attr
 from pathlib import Path
 
 from ..model.topology import Edge
@@ -472,6 +473,7 @@ def render_svg(
     edges: list[Edge],
     *,
     node_types: dict[str, str],
+    node_data: dict[str, dict[str, str]] | None = None,
     options: SvgOptions | None = None,
     theme: SvgTheme = DEFAULT_THEME,
 ) -> str:
@@ -503,6 +505,7 @@ def render_svg(
         node_port_prefix,
         icons,
         options,
+        node_data,
     )
 
     lines.append("</svg>")
@@ -519,6 +522,8 @@ def _render_svg_edges(
     node_port_labels: dict[str, str] = {}
     node_port_prefix: dict[str, str] = {}
     for edge in edges:
+        _record_edge_labels(edge, node_types, node_port_labels, node_port_prefix)
+    for edge in sorted(edges, key=lambda item: item.poe):
         if edge.left not in positions or edge.right not in positions:
             continue
         src_x, src_y = positions[edge.left]
@@ -530,7 +535,17 @@ def _render_svg_edges(
         mid_y = (src_bottom + dst_top) / 2
         color = "url(#link-poe)" if edge.poe else "url(#link-standard)"
         width_px = 2 if edge.poe else 1
-        path = f"M {src_cx} {src_bottom} L {src_cx} {mid_y} L {dst_cx} {mid_y} L {dst_cx} {dst_top}"
+        if math.isclose(src_cx, dst_cx, abs_tol=0.01):
+            elbow_x = src_cx + 0.5
+            path = (
+                f"M {src_cx} {src_bottom} L {src_cx} {mid_y} "
+                f"L {elbow_x} {mid_y} L {dst_cx} {mid_y} L {dst_cx} {dst_top}"
+            )
+        else:
+            path = (
+                f"M {src_cx} {src_bottom} L {src_cx} {mid_y} "
+                f"L {dst_cx} {mid_y} L {dst_cx} {dst_top}"
+            )
         dash = ' stroke-dasharray="6 4"' if edge.wireless else ""
         lines.append(
             f'<path d="{path}" stroke="{color}" stroke-width="{width_px}" fill="none"{dash}/>'
@@ -542,7 +557,6 @@ def _render_svg_edges(
                 f'<text x="{icon_x}" y="{icon_y}" text-anchor="middle" fill="#1e88e5" '
                 f'font-size="{max(options.font_size, 10)}">⚡</text>'
             )
-        _record_edge_labels(edge, node_types, node_port_labels, node_port_prefix)
     return node_port_labels, node_port_prefix
 
 
@@ -589,11 +603,15 @@ def _render_svg_nodes(
     node_port_prefix: dict[str, str],
     icons: dict[str, str],
     options: SvgOptions,
+    node_data: dict[str, dict[str, str]] | None,
 ) -> None:
     for name, (x, y) in positions.items():
         node_type = node_types.get(name, "other")
         fill, stroke = _TYPE_COLORS.get(node_type, _TYPE_COLORS["other"])
         fill = f"url(#node-{node_type})"
+        extra_attrs = _svg_node_attrs(node_data, name)
+        if extra_attrs:
+            lines.append(f"<g{extra_attrs}>")
         lines.append(
             f'<rect x="{x}" y="{y}" width="{options.node_width}" height="{options.node_height}" '
             f'rx="6" ry="6" fill="{fill}" stroke="{stroke}" stroke-width="1"/>'
@@ -631,6 +649,18 @@ def _render_svg_nodes(
         lines.append(
             f'<text x="{text_x}" y="{text_y}" fill="#1f1f1f" text-anchor="start">{safe_name}</text>'
         )
+        if extra_attrs:
+            lines.append("</g>")
+
+
+def _svg_node_attrs(node_data: dict[str, dict[str, str]] | None, name: str) -> str:
+    if not node_data:
+        return ""
+    attrs = node_data.get(name)
+    if not attrs:
+        return ""
+    rendered = [f' {key}="{_escape_attr(value, quote=True)}"' for key, value in attrs.items()]
+    return "".join(rendered)
 
 
 def _iso_project(layout: IsoLayout, gx: float, gy: float) -> tuple[float, float]:
@@ -759,6 +789,8 @@ def _render_iso_edges(
     node_port_prefix: dict[str, str],
 ) -> None:
     for edge in edges:
+        _record_iso_edge_label(edge, node_types, node_port_labels, node_port_prefix)
+    for edge in sorted(edges, key=lambda item: item.poe):
         if edge.left not in positions or edge.right not in positions:
             continue
         src_grid = grid_positions.get(edge.left)
@@ -800,7 +832,6 @@ def _render_iso_edges(
                 f'<text x="{icon_x}" y="{icon_y}" text-anchor="middle" fill="#1e88e5" '
                 f'font-size="{max(options.font_size, 10)}">⚡</text>'
             )
-        _record_iso_edge_label(edge, node_types, node_port_labels, node_port_prefix)
 
 
 def _iso_edge_path(

{unifi_network_maps-1.4.5 → unifi_network_maps-1.4.6}/src/unifi_network_maps.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unifi-network-maps
-Version: 1.4.5
+Version: 1.4.6
 Summary: Dynamic UniFi -> network maps in mermaid or svg
 Author: Merlijn
 License-Expression: MIT
@@ -144,6 +144,11 @@ Legend only:
 unifi-network-maps --legend-only --stdout
 ```
 
+## Home Assistant integration
+
+The live Home Assistant integration (Config Flow + coordinator + custom card) lives in a separate repo:
+- https://github.com/merlijntishauser/unifi-network-maps-ha
+
 ## Examples (mock data)
 
 These examples are generated from `examples/mock_data.json` (safe, anonymized fixture).

{unifi_network_maps-1.4.5 → unifi_network_maps-1.4.6}/tests/test_svg.py

@@ -1,3 +1,4 @@
+import re
 from pathlib import Path
 
 import unifi_network_maps.render.svg as svg_module
@@ -42,6 +43,18 @@ def test_render_svg_dashes_wireless_links():
     assert 'stroke-dasharray="6 4"' in output
 
 
+def test_render_svg_adds_elbow_for_vertical_links():
+    output = svg_module.render_svg(
+        [Edge("Root", "Child")],
+        node_types={"Root": "gateway", "Child": "switch"},
+    )
+    match = re.search(r'<path d="([^"]+)"', output)
+    assert match is not None
+    coords = [float(value) for value in re.findall(r"-?\d+(?:\.\d+)?", match.group(1))]
+    x_values = {round(x, 2) for x in coords[0::2]}
+    assert len(x_values) > 1
+
+
 def test_render_svg_compacts_device_labels():
     output = svg_module.render_svg(
         [Edge("A", "B", label="Switch A: Port 2 <-> Switch B: Port 5")],

unifi_network_maps-1.4.5/CHANGELOG.md

@@ -1,93 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-
-## 1.4.5 - (2026-01-11)
-- Refactored CLI orchestration into focused CLI/render/runtime modules.
-- Extracted MkDocs rendering and sidebar asset output into dedicated modules.
-- Moved mock generation into the model layer with a thin IO facade.
-- Centralized legend rendering helpers and shared markdown table utilities.
-- Added Jinja2 templating for MkDocs output, Mermaid legend blocks, and Markdown sections.
-- Moved MkDocs sidebar assets and legend HTML blocks into reusable templates.
-- Enabled Jinja2 autoescaping for HTML templates and marked trusted HTML blocks safe.
-
-## v1.4.4 - (2026-01-10)
-- Improved dark theme Mermaid readability (labels + link borders).
-- Fixed MkDocs sidebar legend duplication with dual-theme output.
-- Added smoke tests for dual-theme MkDocs sidebar legend output.
-
-## v1.4.2 - 2026-01-10
-- Added static code analysis and stricter type-checking
-- Added contract tests for UniFi API wrapper with fixture-based validation.
-- Added optional live UniFi contract tests (gated by `UNIFI_CONTRACT_LIVE=1`).
-- Split CI into dedicated jobs and added a contract-test job.
-- Added Behave-based BDD tests covering CLI outputs, mkdocs assets, and error handling.
-- Added mkdocs timestamp (timezone configurable via `--mkdocs-timestamp-zone`).
-- Added optional dual Mermaid blocks for MkDocs Material theme switching (`--mkdocs-dual-theme`).
-- Switched UniFi API cache payloads to JSON for safer local storage.
-- Skips cache usage when the cache directory is group/world-writable.
-- Added `--no-cache` to bypass UniFi API cache reads/writes.
-- Added file locking around cache read/write operations to avoid concurrent corruption.
-- Hardened Mermaid label escaping for newlines and backslashes.
-- Fixed device cache serialization to preserve LLDP data when caching.
-- Added optional UniFi API request timeouts via `UNIFI_REQUEST_TIMEOUT_SECONDS`.
-- Made `--output` writes atomic to avoid partial files on interruption.
-
-## v1.4.1 - 2026-01-06
-- pip install was broken, fixed.
-
-## v1.4.0 - 2026-01-06
-- Added MkDocs output, which includes gateway/switch details and per-port tables.
-- Port tables show speed, PoE status, power, and wired clients per port.
-- Added compact legend with sidebar injection (`--mkdocs-sidebar-legend`).
-- LLDP markdown includes the same device details and port tables when enabled.
-- Improved uplink labeling (gateway shows Internet for WAN/unknown).
-- Aggregated ports are combined into single LAG rows.
-- Bumped minimum Python to 3.13 and aligned CI to 3.13.
-- Pinned runtime/dev/build dependencies and added `requirements*.txt` + `constraints.txt`.
-- Added `--mock-data` for safe, offline rendering from fixtures.
-- Added Faker-powered `--generate-mock` for deterministic mock fixtures (dev-only).
-- Added mock fixtures + SVG/Mermaid examples, with mock smoketest/CI steps.
-
-## v1.3.1 - 2026-01-04
-- Added `lldp-md` output with per-device details tables and optional client sections.
-- Added `--client-scope wired|wireless|all` and dashed wireless client links in Mermaid/SVG.
-- Expanded smoketest outputs for wireless/all client scopes and LLDP markdown.
-- Fixed SVG icon loading paths after package reorg.
-- Tuned isometric port label placement on front tiles.
-
-## v1.3.0 - 2026-01-04
-- Reorganized package into submodules (`adapters/`, `model/`, `render/`, `io/`, `cli/`).
-- YAML-based theming with default + dark themes and `--theme-file`.
-- CLI help now grouped by category; CLI logic split into focused helpers.
-- Isometric SVG layout constants centralized; extra viewBox padding to avoid clipping.
-- LLDP port index fallback matches `port_table` `ifname`/`name`.
-- Added PoE/edge/device count logging and improved label ordering helpers.
-- Coverage excludes asset packages; docs updated (options/groups + AI disclosure).
-
-## v1.2.4 - 2026-01-03
-- Added typed `UplinkInfo`/`PortInfo` and uplink fallback for LLDP gaps.
-- Deterministic edge ordering for repeatable output.
-- CI publish workflow (trusted publishing) and release docs.
-- Project metadata and packaging updated for OSS readiness.
-
-## v1.1.0 - 2026-01-03
-- Added isometric SVG output with grid-aligned links and isometric icon set.
-- Improved port label placement and client labeling in SVG outputs.
-- Added smoketest target with multiple outputs (ports/clients/legend).
-- Added UniFi API response caching with TTL.
-- Fixed Mermaid legend/grouped output parsing errors.
-- Refined visuals: link gradients, tile gradients, icon placement tweaks.
-
-## v1.0.0 - 2025-12-30
-- Mermaid legend can render as a separate graph.
-- Straight Mermaid links with node type coloring.
-- Added wired client leaf nodes and uplink port labels.
-- Expanded PoE detection tests and LLDP helpers.
-- CLI loads `.env` automatically.
-
-## v0.2.0 - 2026-01-02 - Initial public release
-- Added versioning workflow and bump tooling.
-- Introduced SVG renderer and tree layout fixes.
-- Increased test coverage and added coverage tooling.

unifi_network_maps-1.4.5/src/unifi_network_maps/__init__.py

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