unifi-network-maps 1.4.4__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.4 → unifi_network_maps-1.4.6}/CONTRIBUTING.md

@@ -43,6 +43,7 @@ Notes:
 - Contract tests use fixtures in `tests/test_contract_unifi.py` and run in CI.
 - Live contract tests require `UNIFI_CONTRACT_LIVE=1` plus UniFi env vars.
 - BDD tests live in `features/` and run via `behave` (included in `make ci`).
+- Render helper structure is documented in `src/unifi_network_maps/render/README.md`.
 
 ## Release
 
@@ -82,8 +83,8 @@ 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.4 → unifi_network_maps-1.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unifi-network-maps
-Version: 1.4.4
+Version: 1.4.6
 Summary: Dynamic UniFi -> network maps in mermaid or svg
 Author: Merlijn
 License-Expression: MIT
@@ -23,6 +23,7 @@ License-File: LICENSE
 Requires-Dist: unifi-controller-api==0.3.2
 Requires-Dist: python-dotenv==1.2.1
 Requires-Dist: PyYAML==6.0.3
+Requires-Dist: Jinja2==3.1.6
 Provides-Extra: dev
 Requires-Dist: Faker==40.1.0; extra == "dev"
 Requires-Dist: behave==1.3.3; extra == "dev"
@@ -143,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.4 → 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.4 → 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.4"
+version = "1.4.6"
 description = "Dynamic UniFi -> network maps in mermaid or svg"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -26,6 +26,7 @@ dependencies = [
   "unifi-controller-api==0.3.2",
   "python-dotenv==1.2.1",
   "PyYAML==6.0.3",
+  "Jinja2==3.1.6",
 ]
 
 [project.urls]
@@ -96,6 +97,7 @@ package-dir = {"" = "src"}
   "assets/icons/*.svg",
   "assets/icons/isometric/*.svg",
   "assets/icons/isometric/ISOPACKS_LICENSE",
+  "render/templates/*.j2",
 ]
 
 [tool.setuptools.packages.find]

unifi_network_maps-1.4.6/src/unifi_network_maps/__init__.py

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

unifi_network_maps-1.4.6/src/unifi_network_maps/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI package facade."""
+
+from .main import main
+
+__all__ = ["main"]

unifi_network_maps-1.4.6/src/unifi_network_maps/cli/args.py

@@ -0,0 +1,166 @@
+"""CLI argument definitions."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Generate network maps from UniFi LLDP data, as mermaid or SVG"
+    )
+    add_source_args(parser.add_argument_group("Source"))
+    add_mock_args(parser.add_argument_group("Mock"))
+    add_functional_args(parser.add_argument_group("Functional"))
+    add_mermaid_args(parser.add_argument_group("Mermaid"))
+    add_svg_args(parser.add_argument_group("SVG"))
+    add_general_render_args(parser.add_argument_group("Output"))
+    add_debug_args(parser.add_argument_group("Debug"))
+    return parser
+
+
+def add_source_args(parser: argparse._ArgumentGroup) -> None:
+    parser.add_argument("--site", default=None, help="UniFi site name (overrides UNIFI_SITE)")
+    parser.add_argument(
+        "--env-file",
+        default=None,
+        help="Path to .env file (overrides default .env discovery)",
+    )
+    parser.add_argument(
+        "--mock-data",
+        default=None,
+        help="Path to mock data JSON (skips UniFi API calls)",
+    )
+
+
+def add_mock_args(parser: argparse._ArgumentGroup) -> None:
+    parser.add_argument(
+        "--generate-mock",
+        default=None,
+        help="Write mock data JSON to the given path and exit",
+    )
+    parser.add_argument("--mock-seed", type=int, default=1337, help="Seed for mock generation")
+    parser.add_argument(
+        "--mock-switches",
+        type=int,
+        default=1,
+        help="Number of switches to generate (default: 1)",
+    )
+    parser.add_argument(
+        "--mock-aps",
+        type=int,
+        default=2,
+        help="Number of access points to generate (default: 2)",
+    )
+    parser.add_argument(
+        "--mock-wired-clients",
+        type=int,
+        default=2,
+        help="Number of wired clients to generate (default: 2)",
+    )
+    parser.add_argument(
+        "--mock-wireless-clients",
+        type=int,
+        default=2,
+        help="Number of wireless clients to generate (default: 2)",
+    )
+
+
+def add_functional_args(parser: argparse._ArgumentGroup) -> None:
+    parser.add_argument("--include-ports", action="store_true", help="Include port labels in edges")
+    parser.add_argument(
+        "--include-clients",
+        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"
+    )
+    parser.add_argument(
+        "--no-cache",
+        action="store_true",
+        help="Disable UniFi API cache reads and writes",
+    )
+
+
+def add_mermaid_args(parser: argparse._ArgumentGroup) -> None:
+    parser.add_argument("--direction", default="TB", choices=["LR", "TB"], help="Mermaid direction")
+    parser.add_argument(
+        "--group-by-type",
+        action="store_true",
+        help="Group nodes by gateway/switch/ap in Mermaid subgraphs",
+    )
+    parser.add_argument(
+        "--legend-scale",
+        type=float,
+        default=1.0,
+        help="Scale legend font/link sizes for Mermaid output (default: 1.0)",
+    )
+    parser.add_argument(
+        "--legend-style",
+        default="auto",
+        choices=["auto", "compact", "diagram"],
+        help="Legend style (auto uses compact for mkdocs, diagram otherwise)",
+    )
+    parser.add_argument(
+        "--legend-only",
+        action="store_true",
+        help="Render only the legend as a separate Mermaid graph",
+    )
+
+
+def add_svg_args(parser: argparse._ArgumentGroup) -> None:
+    parser.add_argument("--svg-width", type=int, default=None, help="SVG width override")
+    parser.add_argument("--svg-height", type=int, default=None, help="SVG height override")
+    parser.add_argument("--theme-file", default=None, help="Path to theme YAML file")
+
+
+def add_general_render_args(parser: argparse._ArgumentGroup) -> None:
+    parser.add_argument(
+        "--format",
+        default="mermaid",
+        choices=["mermaid", "svg", "svg-iso", "lldp-md", "mkdocs"],
+        help="Output format",
+    )
+    parser.add_argument(
+        "--markdown",
+        action="store_true",
+        help="Wrap output in a Markdown mermaid code fence for notes tools like Obsidian",
+    )
+    parser.add_argument("--output", default=None, help="Output file path")
+    parser.add_argument("--stdout", action="store_true", help="Write output to stdout")
+    parser.add_argument(
+        "--mkdocs-sidebar-legend",
+        action="store_true",
+        help="For mkdocs output, write sidebar legend assets next to the output file",
+    )
+    parser.add_argument(
+        "--mkdocs-dual-theme",
+        action="store_true",
+        help="Render light/dark Mermaid blocks for MkDocs Material theme switching",
+    )
+    parser.add_argument(
+        "--mkdocs-timestamp-zone",
+        default="Europe/Amsterdam",
+        help="Timezone for mkdocs generated timestamp (use 'off' to disable)",
+    )
+
+
+def add_debug_args(parser: argparse._ArgumentGroup) -> None:
+    parser.add_argument(
+        "--debug-dump",
+        action="store_true",
+        help="Dump gateway and sample device data to stderr for debugging",
+    )
+    parser.add_argument(
+        "--debug-sample",
+        type=int,
+        default=2,
+        help="Number of non-gateway devices to include in debug dump (default: 2)",
+    )

unifi_network_maps-1.4.6/src/unifi_network_maps/cli/main.py

@@ -0,0 +1,134 @@
+"""CLI entry point."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+
+from ..adapters.config import Config
+from ..io.export import write_output
+from ..io.mock_data import load_mock_data
+from ..render.legend import render_legend_only, resolve_legend_style
+from ..render.theme import resolve_themes
+from .args import build_parser
+from .render import render_lldp_format, render_standard_format
+
+logger = logging.getLogger(__name__)
+
+
+def _load_dotenv(env_file: str | None = None) -> None:
+    try:
+        from dotenv import load_dotenv
+    except ImportError:
+        logger.info("python-dotenv not installed; skipping .env loading")
+        return
+    load_dotenv(dotenv_path=env_file) if env_file else load_dotenv()
+
+
+def _parse_args(argv: list[str] | None) -> argparse.Namespace:
+    parser = build_parser()
+    return parser.parse_args(argv)
+
+
+def _load_config(args: argparse.Namespace) -> Config | None:
+    try:
+        _load_dotenv(args.env_file)
+        return Config.from_env(env_file=args.env_file)
+    except ValueError as exc:
+        logging.error(str(exc))
+        return None
+
+
+def _resolve_site(args: argparse.Namespace, config: Config) -> str:
+    return args.site or config.site
+
+
+def _handle_generate_mock(args: argparse.Namespace) -> int | None:
+    if not args.generate_mock:
+        return None
+    try:
+        from ..model.mock import MockOptions, mock_payload_json
+    except ImportError as exc:
+        logging.error("Faker is required for --generate-mock: %s", exc)
+        return 2
+    options = MockOptions(
+        seed=args.mock_seed,
+        switch_count=max(1, args.mock_switches),
+        ap_count=max(0, args.mock_aps),
+        wired_client_count=max(0, args.mock_wired_clients),
+        wireless_client_count=max(0, args.mock_wireless_clients),
+    )
+    content = mock_payload_json(options)
+    write_output(content, output_path=args.generate_mock, stdout=args.stdout)
+    return 0
+
+
+def _load_runtime_context(
+    args: argparse.Namespace,
+) -> tuple[Config | None, str, list[object] | None, list[object] | None]:
+    if args.mock_data:
+        try:
+            mock_devices, mock_clients = load_mock_data(args.mock_data)
+        except Exception as exc:  # noqa: BLE001
+            raise ValueError(f"Failed to load mock data: {exc}") from exc
+        return None, "mock", mock_devices, mock_clients
+    config = _load_config(args)
+    if config is None:
+        raise ValueError("Config required to run")
+    site = _resolve_site(args, config)
+    return config, site, None, None
+
+
+def main(argv: list[str] | None = None) -> int:
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    args = _parse_args(argv)
+    mock_result = _handle_generate_mock(args)
+    if mock_result is not None:
+        return mock_result
+    try:
+        config, site, mock_devices, mock_clients = _load_runtime_context(args)
+    except ValueError as exc:
+        logging.error(str(exc))
+        return 2
+    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(
+            format_name=args.format,
+            legend_style=args.legend_style,
+        )
+        content = render_legend_only(
+            legend_style=legend_style,
+            legend_scale=args.legend_scale,
+            markdown=args.markdown,
+            theme=mermaid_theme,
+        )
+        write_output(content, output_path=args.output, stdout=args.stdout)
+        return 0
+
+    if args.format == "lldp-md":
+        return render_lldp_format(
+            args,
+            config=config,
+            site=site,
+            mock_devices=mock_devices,
+            mock_clients=mock_clients,
+        )
+
+    return render_standard_format(
+        args,
+        config=config,
+        site=site,
+        mock_devices=mock_devices,
+        mock_clients=mock_clients,
+        mermaid_theme=mermaid_theme,
+        svg_theme=svg_theme,
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())