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

{unifi_network_maps-1.2.4 → unifi_network_maps-1.3.0}/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 ## Unreleased
 - TBD.
 
+## v1.3.0
+- 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
+- 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
 - Added isometric SVG output with grid-aligned links and isometric icon set.
 - Improved port label placement and client labeling in SVG outputs.

unifi_network_maps-1.3.0/LICENSES.md

@@ -0,0 +1,10 @@
+# Third-Party Licenses
+
+## markmanx/isopacks (MIT)
+
+Isometric SVG icons are vendored under `src/unifi_network_maps/assets/icons/isometric/`.
+The upstream MIT license is included at:
+
+```
+src/unifi_network_maps/assets/icons/isometric/ISOPACKS_LICENSE
+```

unifi_network_maps-1.3.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include SECURITY.md
+include CONTRIBUTING.md
+include LICENSES.md
+include RELEASING.md
+recursive-include src/unifi_network_maps/assets/icons *.svg
+recursive-include src/unifi_network_maps/assets/icons/isometric ISOPACKS_LICENSE
+recursive-include src/unifi_network_maps/assets/themes *.yaml

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: unifi-network-maps
-Version: 1.2.4
-Summary: Dynamic UniFi -> Mermaid network maps
+Version: 1.3.0
+Summary: Dynamic UniFi -> network maps in mermaid or svg
 Author: Merlijn
 License: MIT
 Project-URL: Homepage, https://github.com/merlijntishauser/unifi-network-maps
@@ -26,6 +26,7 @@ License-File: LICENSE
 License-File: LICENSES.md
 Requires-Dist: unifi-controller-api
 Requires-Dist: python-dotenv
+Requires-Dist: PyYAML
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
@@ -66,6 +67,12 @@ export UNIFI_PASS=********
 export UNIFI_VERIFY_SSL=false
 ```
 
+Use a custom env file:
+
+```bash
+unifi-network-maps --env-file ./site.env --stdout
+```
+
 ## Usage
 
 Basic map (tree layout by LLDP hops):
@@ -137,24 +144,72 @@ See `LICENSES.md` for third-party license info.
 
 ## Options
 
-- `--format mermaid|svg|svg-iso`: output format (default mermaid).
+The CLI groups options by category (`Source`, `Functional`, `Mermaid`, `SVG`, `Output`, `Debug`).
+
+Source:
+- `--site`: override `UNIFI_SITE`.
+- `--env-file`: load environment variables from a specific `.env` file.
+
+Functional:
 - `--include-ports`: show port labels (Mermaid shows both ends; SVG shows compact labels).
+- `--include-clients`: add active wired clients as leaf nodes.
 - `--only-unifi`: only include neighbors that are UniFi devices.
+
+Mermaid:
 - `--direction LR|TB`: diagram direction for Mermaid (default TB).
-- `--stdout`: write output to stdout.
-- `--markdown`: wrap Mermaid output in a code fence.
 - `--group-by-type`: group nodes by gateway/switch/AP in Mermaid subgraphs.
-- `--include-clients`: add active wired clients as leaf nodes.
 - `--legend-only`: render just the legend as a separate Mermaid graph (Mermaid only).
+
+SVG:
+- `--svg-width/--svg-height`: override SVG output dimensions.
+- `--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).
+- `--stdout`: write output to stdout.
+- `--markdown`: wrap Mermaid output in a code fence.
+
+Debug:
 - `--debug-dump`: dump gateway + sample devices to stderr for debugging.
 - `--debug-sample N`: number of non-gateway devices in debug dump (default 2).
-- `--svg-width/--svg-height`: override SVG output dimensions.
 
 ## Notes
 
 - 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`.
-- SVG output uses vendored device glyphs from `src/unifi_mermaid/assets/icons`.
+- 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.
+
+## AI Disclosure
+
+This project used OpenAI Codex as a coding assistant for portions of the implementation and documentation.
+
+## Theme file
+
+Example theme YAML (override only the values you want):
+
+```yaml
+mermaid:
+  nodes:
+    gateway:
+      fill: "#ffe3b3"
+      stroke: "#d98300"
+  poe_link: "#1e88e5"
+svg:
+  links:
+    standard:
+      from: "#2ecc71"
+      to: "#1b8f4a"
+    poe:
+      from: "#1e88e5"
+      to: "#0d47a1"
+  nodes:
+    switch:
+      from: "#d6ecff"
+      to: "#b6dcff"
+```
+
+The built-in themes live at `src/unifi_network_maps/assets/themes/default.yaml` and
+`src/unifi_network_maps/assets/themes/dark.yaml`.

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

@@ -31,6 +31,12 @@ export UNIFI_PASS=********
 export UNIFI_VERIFY_SSL=false
 ```
 
+Use a custom env file:
+
+```bash
+unifi-network-maps --env-file ./site.env --stdout
+```
+
 ## Usage
 
 Basic map (tree layout by LLDP hops):
@@ -102,24 +108,72 @@ See `LICENSES.md` for third-party license info.
 
 ## Options
 
-- `--format mermaid|svg|svg-iso`: output format (default mermaid).
+The CLI groups options by category (`Source`, `Functional`, `Mermaid`, `SVG`, `Output`, `Debug`).
+
+Source:
+- `--site`: override `UNIFI_SITE`.
+- `--env-file`: load environment variables from a specific `.env` file.
+
+Functional:
 - `--include-ports`: show port labels (Mermaid shows both ends; SVG shows compact labels).
+- `--include-clients`: add active wired clients as leaf nodes.
 - `--only-unifi`: only include neighbors that are UniFi devices.
+
+Mermaid:
 - `--direction LR|TB`: diagram direction for Mermaid (default TB).
-- `--stdout`: write output to stdout.
-- `--markdown`: wrap Mermaid output in a code fence.
 - `--group-by-type`: group nodes by gateway/switch/AP in Mermaid subgraphs.
-- `--include-clients`: add active wired clients as leaf nodes.
 - `--legend-only`: render just the legend as a separate Mermaid graph (Mermaid only).
+
+SVG:
+- `--svg-width/--svg-height`: override SVG output dimensions.
+- `--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).
+- `--stdout`: write output to stdout.
+- `--markdown`: wrap Mermaid output in a code fence.
+
+Debug:
 - `--debug-dump`: dump gateway + sample devices to stderr for debugging.
 - `--debug-sample N`: number of non-gateway devices in debug dump (default 2).
-- `--svg-width/--svg-height`: override SVG output dimensions.
 
 ## Notes
 
 - 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`.
-- SVG output uses vendored device glyphs from `src/unifi_mermaid/assets/icons`.
+- 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.
+
+## AI Disclosure
+
+This project used OpenAI Codex as a coding assistant for portions of the implementation and documentation.
+
+## Theme file
+
+Example theme YAML (override only the values you want):
+
+```yaml
+mermaid:
+  nodes:
+    gateway:
+      fill: "#ffe3b3"
+      stroke: "#d98300"
+  poe_link: "#1e88e5"
+svg:
+  links:
+    standard:
+      from: "#2ecc71"
+      to: "#1b8f4a"
+    poe:
+      from: "#1e88e5"
+      to: "#0d47a1"
+  nodes:
+    switch:
+      from: "#d6ecff"
+      to: "#b6dcff"
+```
+
+The built-in themes live at `src/unifi_network_maps/assets/themes/default.yaml` and
+`src/unifi_network_maps/assets/themes/dark.yaml`.

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

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unifi-network-maps"
-version = "1.2.4"
-description = "Dynamic UniFi -> Mermaid network maps"
+version = "1.3.0"
+description = "Dynamic UniFi -> network maps in mermaid or svg"
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "MIT" }
@@ -27,6 +27,7 @@ classifiers = [
 dependencies = [
   "unifi-controller-api",
   "python-dotenv",
+  "PyYAML",
 ]
 
 [project.urls]
@@ -44,7 +45,7 @@ dev = [
 ]
 
 [project.scripts]
-unifi-network-maps = "unifi_mermaid.cli:main"
+unifi-network-maps = "unifi_network_maps.cli:main"
 
 [tool.ruff]
 line-length = 100
@@ -59,10 +60,15 @@ line-ending = "lf"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+norecursedirs = ["src/unifi_network_maps/assets"]
 
 [tool.coverage.run]
 branch = true
-source = ["unifi_mermaid"]
+source = ["unifi_network_maps"]
+omit = [
+  "src/unifi_network_maps/assets/*",
+  "src/unifi_network_maps/assets/**",
+]
 
 [tool.coverage.report]
 show_missing = true
@@ -71,7 +77,7 @@ show_missing = true
 package-dir = {"" = "src"}
 
 [tool.setuptools.package-data]
-"unifi_mermaid" = [
+"unifi_network_maps" = [
   "assets/icons/*.svg",
   "assets/icons/isometric/*.svg",
   "assets/icons/isometric/ISOPACKS_LICENSE",

unifi_network_maps-1.3.0/src/unifi_network_maps/__init__.py

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

unifi_network_maps-1.3.0/src/unifi_network_maps/adapters/__init__.py

@@ -0,0 +1 @@
+"""Package module."""

{unifi_network_maps-1.2.4/src/unifi_mermaid → unifi_network_maps-1.3.0/src/unifi_network_maps/adapters}/config.py

@@ -26,7 +26,13 @@ class Config:
     verify_ssl: bool
 
     @classmethod
-    def from_env(cls) -> Config:
+    def from_env(cls, *, env_file: str | None = None) -> Config:
+        if env_file:
+            try:
+                from dotenv import load_dotenv
+            except ImportError:
+                raise ValueError("python-dotenv required for --env-file") from None
+            load_dotenv(dotenv_path=env_file)
         url = os.environ.get("UNIFI_URL", "").strip()
         site = os.environ.get("UNIFI_SITE", "default").strip()
         user = os.environ.get("UNIFI_USER", "").strip()

{unifi_network_maps-1.2.4/src/unifi_mermaid → unifi_network_maps-1.3.0/src/unifi_network_maps/adapters}/unifi.py

@@ -20,7 +20,7 @@ logger = logging.getLogger(__name__)
 
 
 def _cache_dir() -> Path:
-    return Path(os.environ.get("UNIFI_CACHE_DIR", ".cache/unifi_mermaid"))
+    return Path(os.environ.get("UNIFI_CACHE_DIR", ".cache/unifi_network_maps"))
 
 
 def _cache_ttl_seconds() -> int:

unifi_network_maps-1.3.0/src/unifi_network_maps/assets/themes/dark.yaml

@@ -0,0 +1,47 @@
+mermaid:
+  nodes:
+    gateway:
+      fill: "#5c3b00"
+      stroke: "#ffb347"
+    switch:
+      fill: "#0f2b3d"
+      stroke: "#5dade2"
+    ap:
+      fill: "#0f3b2d"
+      stroke: "#2ecc71"
+    client:
+      fill: "#2b1f3b"
+      stroke: "#b084ff"
+    other:
+      fill: "#2a2a2a"
+      stroke: "#9e9e9e"
+  poe_link: "#64b5f6"
+  poe_link_width: 2
+  poe_link_arrow: "none"
+  standard_link: "#66bb6a"
+  standard_link_width: 2
+  standard_link_arrow: "none"
+svg:
+  links:
+    standard:
+      from: "#66bb6a"
+      to: "#2e7d32"
+    poe:
+      from: "#64b5f6"
+      to: "#1e88e5"
+  nodes:
+    gateway:
+      from: "#5c3b00"
+      to: "#3e2a00"
+    switch:
+      from: "#0f2b3d"
+      to: "#0a1f2c"
+    ap:
+      from: "#0f3b2d"
+      to: "#0b2a20"
+    client:
+      from: "#2b1f3b"
+      to: "#20162b"
+    other:
+      from: "#2a2a2a"
+      to: "#1f1f1f"

unifi_network_maps-1.3.0/src/unifi_network_maps/assets/themes/default.yaml

@@ -0,0 +1,47 @@
+mermaid:
+  nodes:
+    gateway:
+      fill: "#ffe3b3"
+      stroke: "#d98300"
+    switch:
+      fill: "#d6ecff"
+      stroke: "#3a7bd5"
+    ap:
+      fill: "#d7f5e7"
+      stroke: "#27ae60"
+    client:
+      fill: "#f2e5ff"
+      stroke: "#7f3fbf"
+    other:
+      fill: "#eeeeee"
+      stroke: "#8f8f8f"
+  poe_link: "#1e88e5"
+  poe_link_width: 2
+  poe_link_arrow: "none"
+  standard_link: "#2ecc71"
+  standard_link_width: 2
+  standard_link_arrow: "none"
+svg:
+  links:
+    standard:
+      from: "#2ecc71"
+      to: "#1b8f4a"
+    poe:
+      from: "#1e88e5"
+      to: "#0d47a1"
+  nodes:
+    gateway:
+      from: "#ffe3b3"
+      to: "#f7c77b"
+    switch:
+      from: "#d6ecff"
+      to: "#b6dcff"
+    ap:
+      from: "#d7f5e7"
+      to: "#b8f0d2"
+    client:
+      from: "#f2e5ff"
+      to: "#e0c9ff"
+    other:
+      from: "#eeeeee"
+      to: "#d7d7d7"

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

@@ -0,0 +1,41 @@
+"""CLI package facade."""
+
+from .main import (
+    Config,
+    SvgOptions,
+    build_client_edges,
+    build_device_index,
+    build_node_type_map,
+    build_topology,
+    debug_dump_devices,
+    fetch_clients,
+    fetch_devices,
+    group_devices_by_type,
+    main,
+    normalize_devices,
+    render_legend,
+    render_mermaid,
+    render_svg,
+    resolve_themes,
+    write_output,
+)
+
+__all__ = [
+    "Config",
+    "SvgOptions",
+    "build_client_edges",
+    "build_device_index",
+    "build_node_type_map",
+    "build_topology",
+    "debug_dump_devices",
+    "fetch_clients",
+    "fetch_devices",
+    "group_devices_by_type",
+    "main",
+    "normalize_devices",
+    "render_legend",
+    "render_mermaid",
+    "render_svg",
+    "resolve_themes",
+    "write_output",
+]

unifi_network_maps-1.3.0/src/unifi_network_maps/cli/__main__.py

@@ -0,0 +1,8 @@
+"""CLI module entry point."""
+
+from __future__ import annotations
+
+from .main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())