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

{unifi_network_maps-1.2.4 → unifi_network_maps-1.3.1}/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.1/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.1/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.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: unifi-network-maps
-Version: 1.2.4
-Summary: Dynamic UniFi -> Mermaid network maps
+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,9 +22,9 @@ 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
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
@@ -66,6 +65,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,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:
@@ -135,26 +143,90 @@ 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
 
-- `--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.
+- `--client-scope wired|wireless|all`: which client types to include (default wired).
 - `--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|lldp-md`: 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`.
+- 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.
+
+## 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.1}/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):
@@ -67,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:
@@ -100,26 +109,90 @@ 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
 
-- `--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.
+- `--client-scope wired|wireless|all`: which client types to include (default wired).
 - `--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|lldp-md`: 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`.
+- 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.
+
+## 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.1}/pyproject.toml

@@ -4,17 +4,17 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unifi-network-maps"
-version = "1.2.4"
-description = "Dynamic UniFi -> Mermaid network maps"
+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",
@@ -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.1/src/unifi_network_maps/__init__.py

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

unifi_network_maps-1.3.1/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.1/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.1/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.1/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.1/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.1/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.1/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())