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

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

@@ -2,8 +2,25 @@
 
 All notable changes to this project will be documented in this file.
 
-## Unreleased
-- TBD.
+## v1.4.0
+- 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
+- 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
 - Reorganized package into submodules (`adapters/`, `model/`, `render/`, `io/`, `cli/`).

{unifi_network_maps-1.3.0 → unifi_network_maps-1.4.0}/CONTRIBUTING.md

@@ -7,7 +7,8 @@ Thanks for considering a contribution!
 ```bash
 python -m venv .venv
 source .venv/bin/activate
-pip install -e ".[dev]"
+pip install -r requirements-build.txt
+pip install -r requirements-dev.txt -c constraints.txt
 pre-commit install
 ```
 

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: unifi-network-maps
-Version: 1.3.0
+Version: 1.4.0
 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,27 +11,24 @@ 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
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Documentation
 Classifier: Topic :: System :: Networking
-Requires-Python: >=3.10
+Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
-License-File: LICENSES.md
-Requires-Dist: unifi-controller-api
-Requires-Dist: python-dotenv
-Requires-Dist: PyYAML
+Requires-Dist: unifi-controller-api==0.3.2
+Requires-Dist: python-dotenv==1.2.1
+Requires-Dist: PyYAML==6.0.3
 Provides-Extra: dev
-Requires-Dist: pre-commit; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
+Requires-Dist: Faker==40.1.0; extra == "dev"
+Requires-Dist: pre-commit==4.5.1; extra == "dev"
+Requires-Dist: pytest==9.0.2; extra == "dev"
+Requires-Dist: pytest-cov==7.0.0; extra == "dev"
+Requires-Dist: ruff==0.14.10; extra == "dev"
 Dynamic: license-file
 
 # unifi-network-maps
@@ -40,13 +37,14 @@ Dynamic UniFi -> Mermaid network maps generated from LLDP topology.
 
 ## Setup
 
-- Python >= 3.10
+- Python >= 3.13
 - Virtualenv required
 
 ```bash
 python -m venv .venv
 source .venv/bin/activate
-pip install -e .
+pip install -r requirements-build.txt
+pip install -e . -c constraints.txt
 ```
 
 Local install (non-editable):
@@ -103,12 +101,24 @@ Isometric SVG output:
 
 ```bash
 unifi-network-maps --format svg-iso --output ./network.svg
+
+# Single-page MkDocs output (ports included, no clients)
+unifi-network-maps --format mkdocs --output ./docs/unifi-network.md
+
+# MkDocs output (map + legend + gateway/switch port tables)
+unifi-network-maps --format mkdocs --output ./docs/unifi-network.md
+
+# Include wired clients in the port tables
+unifi-network-maps --format mkdocs --include-clients --output ./docs/unifi-network.md
 ```
 
 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:
@@ -117,12 +127,61 @@ Legend only:
 unifi-network-maps --legend-only --stdout
 ```
 
+## Examples (mock data)
+
+These examples are generated from `examples/mock_data.json` (safe, anonymized fixture).
+Mock generation requires dev dependencies (`pip install -r requirements-dev.txt -c constraints.txt`).
+Regenerate the fixture + SVG with `make mock-data`.
+
+Generate mock data (dev-only, uses Faker):
+
+```bash
+unifi-network-maps --generate-mock examples/mock_data.json --mock-seed 1337
+```
+
+Generate the isometric SVG:
+
+```bash
+unifi-network-maps --mock-data examples/mock_data.json \
+  --include-ports --include-clients --format svg-iso \
+  --output examples/output/network_ports_clients_iso.svg
+```
+
+![Isometric network example](examples/output/network_ports_clients_iso.svg)
+
+Mermaid example with ports:
+
+```mermaid
+graph TB
+  core_switch["Core Switch"] ---|"Core Switch: Port 7 (AP Attic) <-> AP Attic: Port 1 (Core Switch)"| ap_attic["AP Attic"];
+  core_switch["Core Switch"] ---|"Core Switch: Port 3 (AP Living Room) <-> AP Living Room: Port 1 (Core Switch)"| ap_living_room["AP Living Room"];
+  cloud_gateway["Cloud Gateway"] ---|"Cloud Gateway: Port 9 (Core Switch) <-> Core Switch: Port 1 (Cloud Gateway)"| core_switch["Core Switch"];
+  class cloud_gateway node_gateway;
+  class core_switch node_switch;
+  class ap_living_room node_ap;
+  class ap_attic node_ap;
+  classDef node_gateway fill:#ffe3b3,stroke:#d98300,stroke-width:1px;
+  classDef node_switch fill:#d6ecff,stroke:#3a7bd5,stroke-width:1px;
+  classDef node_ap fill:#d7f5e7,stroke:#27ae60,stroke-width:1px;
+  classDef node_client fill:#f2e5ff,stroke:#7f3fbf,stroke-width:1px;
+  classDef node_other fill:#eeeeee,stroke:#8f8f8f,stroke-width:1px;
+  classDef node_legend font-size:10px;
+  linkStyle 0 stroke:#1e88e5,stroke-width:2px,arrowhead:none;
+  linkStyle 1 stroke:#1e88e5,stroke-width:2px,arrowhead:none;
+```
+
 ## Local install check
 
 ```bash
 pip install .
 ```
 
+## Dev
+
+```bash
+pip install -r requirements-dev.txt -c constraints.txt
+```
+
 ## Release
 
 Build and upload to PyPI:
@@ -142,6 +201,20 @@ 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
 
 The CLI groups options by category (`Source`, `Functional`, `Mermaid`, `SVG`, `Output`, `Debug`).
@@ -149,15 +222,26 @@ The CLI groups options by category (`Source`, `Functional`, `Mermaid`, `SVG`, `O
 Source:
 - `--site`: override `UNIFI_SITE`.
 - `--env-file`: load environment variables from a specific `.env` file.
+- `--mock-data`: use mock data JSON instead of the UniFi API.
+Mock:
+- `--generate-mock`: write mock data JSON and exit.
+- `--mock-seed`: seed for deterministic mock generation.
+- `--mock-switches`: number of switches to generate.
+- `--mock-aps`: number of access points to generate.
+- `--mock-wired-clients`: number of wired clients to generate.
+- `--mock-wireless-clients`: number of wireless clients to generate.
 
 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).
 - `--group-by-type`: group nodes by gateway/switch/AP in Mermaid subgraphs.
+- `--legend-scale`: scale legend font/link sizes for Mermaid outputs (default 1.0).
+- `--legend-style auto|compact|diagram`: legend rendering mode (auto uses compact for mkdocs).
 - `--legend-only`: render just the legend as a separate Mermaid graph (Mermaid only).
 
 SVG:
@@ -165,9 +249,10 @@ SVG:
 - `--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).
+- `--format mermaid|svg|svg-iso|lldp-md|mkdocs`: output format (default mermaid).
 - `--stdout`: write output to stdout.
 - `--markdown`: wrap Mermaid output in a code fence.
+- `--mkdocs-sidebar-legend`: write assets to place the compact legend in the MkDocs right sidebar.
 
 Debug:
 - `--debug-dump`: dump gateway + sample devices to stderr for debugging.
@@ -178,6 +263,7 @@ Debug:
 - 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`.
+- 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.
@@ -211,5 +297,10 @@ svg:
       to: "#b6dcff"
 ```
 
+## MkDocs Material example
+
+See `examples/mkdocs/` for a ready-to-use setup that renders Mermaid diagrams
+with Material for MkDocs, including a sample `unifi-network` page and legend.
+
 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.3.0 → unifi_network_maps-1.4.0}/README.md

@@ -4,13 +4,14 @@ Dynamic UniFi -> Mermaid network maps generated from LLDP topology.
 
 ## Setup
 
-- Python >= 3.10
+- Python >= 3.13
 - Virtualenv required
 
 ```bash
 python -m venv .venv
 source .venv/bin/activate
-pip install -e .
+pip install -r requirements-build.txt
+pip install -e . -c constraints.txt
 ```
 
 Local install (non-editable):
@@ -67,12 +68,24 @@ Isometric SVG output:
 
 ```bash
 unifi-network-maps --format svg-iso --output ./network.svg
+
+# Single-page MkDocs output (ports included, no clients)
+unifi-network-maps --format mkdocs --output ./docs/unifi-network.md
+
+# MkDocs output (map + legend + gateway/switch port tables)
+unifi-network-maps --format mkdocs --output ./docs/unifi-network.md
+
+# Include wired clients in the port tables
+unifi-network-maps --format mkdocs --include-clients --output ./docs/unifi-network.md
 ```
 
 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:
@@ -81,12 +94,61 @@ Legend only:
 unifi-network-maps --legend-only --stdout
 ```
 
+## Examples (mock data)
+
+These examples are generated from `examples/mock_data.json` (safe, anonymized fixture).
+Mock generation requires dev dependencies (`pip install -r requirements-dev.txt -c constraints.txt`).
+Regenerate the fixture + SVG with `make mock-data`.
+
+Generate mock data (dev-only, uses Faker):
+
+```bash
+unifi-network-maps --generate-mock examples/mock_data.json --mock-seed 1337
+```
+
+Generate the isometric SVG:
+
+```bash
+unifi-network-maps --mock-data examples/mock_data.json \
+  --include-ports --include-clients --format svg-iso \
+  --output examples/output/network_ports_clients_iso.svg
+```
+
+![Isometric network example](examples/output/network_ports_clients_iso.svg)
+
+Mermaid example with ports:
+
+```mermaid
+graph TB
+  core_switch["Core Switch"] ---|"Core Switch: Port 7 (AP Attic) <-> AP Attic: Port 1 (Core Switch)"| ap_attic["AP Attic"];
+  core_switch["Core Switch"] ---|"Core Switch: Port 3 (AP Living Room) <-> AP Living Room: Port 1 (Core Switch)"| ap_living_room["AP Living Room"];
+  cloud_gateway["Cloud Gateway"] ---|"Cloud Gateway: Port 9 (Core Switch) <-> Core Switch: Port 1 (Cloud Gateway)"| core_switch["Core Switch"];
+  class cloud_gateway node_gateway;
+  class core_switch node_switch;
+  class ap_living_room node_ap;
+  class ap_attic node_ap;
+  classDef node_gateway fill:#ffe3b3,stroke:#d98300,stroke-width:1px;
+  classDef node_switch fill:#d6ecff,stroke:#3a7bd5,stroke-width:1px;
+  classDef node_ap fill:#d7f5e7,stroke:#27ae60,stroke-width:1px;
+  classDef node_client fill:#f2e5ff,stroke:#7f3fbf,stroke-width:1px;
+  classDef node_other fill:#eeeeee,stroke:#8f8f8f,stroke-width:1px;
+  classDef node_legend font-size:10px;
+  linkStyle 0 stroke:#1e88e5,stroke-width:2px,arrowhead:none;
+  linkStyle 1 stroke:#1e88e5,stroke-width:2px,arrowhead:none;
+```
+
 ## Local install check
 
 ```bash
 pip install .
 ```
 
+## Dev
+
+```bash
+pip install -r requirements-dev.txt -c constraints.txt
+```
+
 ## Release
 
 Build and upload to PyPI:
@@ -106,6 +168,20 @@ 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
 
 The CLI groups options by category (`Source`, `Functional`, `Mermaid`, `SVG`, `Output`, `Debug`).
@@ -113,15 +189,26 @@ The CLI groups options by category (`Source`, `Functional`, `Mermaid`, `SVG`, `O
 Source:
 - `--site`: override `UNIFI_SITE`.
 - `--env-file`: load environment variables from a specific `.env` file.
+- `--mock-data`: use mock data JSON instead of the UniFi API.
+Mock:
+- `--generate-mock`: write mock data JSON and exit.
+- `--mock-seed`: seed for deterministic mock generation.
+- `--mock-switches`: number of switches to generate.
+- `--mock-aps`: number of access points to generate.
+- `--mock-wired-clients`: number of wired clients to generate.
+- `--mock-wireless-clients`: number of wireless clients to generate.
 
 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).
 - `--group-by-type`: group nodes by gateway/switch/AP in Mermaid subgraphs.
+- `--legend-scale`: scale legend font/link sizes for Mermaid outputs (default 1.0).
+- `--legend-style auto|compact|diagram`: legend rendering mode (auto uses compact for mkdocs).
 - `--legend-only`: render just the legend as a separate Mermaid graph (Mermaid only).
 
 SVG:
@@ -129,9 +216,10 @@ SVG:
 - `--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).
+- `--format mermaid|svg|svg-iso|lldp-md|mkdocs`: output format (default mermaid).
 - `--stdout`: write output to stdout.
 - `--markdown`: wrap Mermaid output in a code fence.
+- `--mkdocs-sidebar-legend`: write assets to place the compact legend in the MkDocs right sidebar.
 
 Debug:
 - `--debug-dump`: dump gateway + sample devices to stderr for debugging.
@@ -142,6 +230,7 @@ Debug:
 - 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`.
+- 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.
@@ -175,5 +264,10 @@ svg:
       to: "#b6dcff"
 ```
 
+## MkDocs Material example
+
+See `examples/mkdocs/` for a ready-to-use setup that renders Mermaid diagrams
+with Material for MkDocs, including a sample `unifi-network` page and legend.
+
 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.3.0 → unifi_network_maps-1.4.0}/RELEASING.md

@@ -10,7 +10,8 @@
    ```
 3) Build the package:
    ```bash
-   python -m pip install build twine
+   python -m pip install -r requirements-build.txt
+   python -m pip install build twine -c constraints.txt
    python -m build
    ```
 4) Inspect the artifacts:

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

@@ -1,33 +1,31 @@
 [build-system]
-requires = ["setuptools>=68", "wheel"]
+requires = ["setuptools==80.9.0", "wheel==0.45.1"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "unifi-network-maps"
-version = "1.3.0"
+version = "1.4.0"
 description = "Dynamic UniFi -> network maps in mermaid or svg"
 readme = "README.md"
-requires-python = ">=3.10"
-license = { text = "MIT" }
+requires-python = ">=3.13"
+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",
-  "Programming Language :: Python :: 3.10",
-  "Programming Language :: Python :: 3.11",
-  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
   "Topic :: Documentation",
   "Topic :: System :: Networking",
 ]
 dependencies = [
-  "unifi-controller-api",
-  "python-dotenv",
-  "PyYAML",
+  "unifi-controller-api==0.3.2",
+  "python-dotenv==1.2.1",
+  "PyYAML==6.0.3",
 ]
 
 [project.urls]
@@ -38,10 +36,11 @@ Changelog = "https://github.com/merlijntishauser/unifi-network-maps/blob/main/CH
 
 [project.optional-dependencies]
 dev = [
-  "pre-commit",
-  "pytest",
-  "pytest-cov",
-  "ruff",
+  "Faker==40.1.0",
+  "pre-commit==4.5.1",
+  "pytest==9.0.2",
+  "pytest-cov==7.0.0",
+  "ruff==0.14.10",
 ]
 
 [project.scripts]
@@ -49,7 +48,7 @@ unifi-network-maps = "unifi_network_maps.cli:main"
 
 [tool.ruff]
 line-length = 100
-target-version = "py310"
+target-version = "py313"
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "B", "UP"]
@@ -61,13 +60,17 @@ line-ending = "lf"
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 norecursedirs = ["src/unifi_network_maps/assets"]
+# Remove --cov from here so it doesn't conflict with PyCharm's runner
+addopts = "-ra"
 
 [tool.coverage.run]
 branch = true
 source = ["unifi_network_maps"]
-omit = [
-  "src/unifi_network_maps/assets/*",
-  "src/unifi_network_maps/assets/**",
+
+[tool.coverage.paths]
+source = [
+    "src/unifi_network_maps",
+    "*/site-packages/unifi_network_maps",
 ]
 
 [tool.coverage.report]

unifi_network_maps-1.4.0/src/unifi_network_maps/__init__.py

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