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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unifi-network-maps
-Version: 1.3.1
+Version: 1.4.1
 Summary: Dynamic UniFi -> network maps in mermaid or svg
 Author: Merlijn
 License-Expression: MIT
@@ -14,22 +14,21 @@ Classifier: Intended Audience :: System Administrators
 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
-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
@@ -38,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):
@@ -101,6 +101,15 @@ 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:
@@ -118,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:
@@ -164,6 +222,14 @@ 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).
@@ -174,6 +240,8 @@ Functional:
 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:
@@ -181,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|lldp-md`: 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.
@@ -228,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.1 → unifi_network_maps-1.4.1}/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,6 +68,15 @@ 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:
@@ -84,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:
@@ -130,6 +189,14 @@ 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).
@@ -140,6 +207,8 @@ Functional:
 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:
@@ -147,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|lldp-md`: 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.
@@ -194,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.1 → unifi_network_maps-1.4.1}/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.1 → unifi_network_maps-1.4.1}/pyproject.toml

@@ -1,13 +1,13 @@
 [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.1"
+version = "1.4.1"
 description = "Dynamic UniFi -> network maps in mermaid or svg"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.13"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [{ name = "Merlijn" }]
@@ -18,16 +18,14 @@ classifiers = [
   "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.1/src/unifi_network_maps/__init__.py

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

unifi_network_maps-1.4.1/src/unifi_network_maps/__main__.py

@@ -0,0 +1,8 @@
+"""Module entrypoint for python -m unifi_network_maps."""
+
+from __future__ import annotations
+
+from .cli.main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{unifi_network_maps-1.3.1 → unifi_network_maps-1.4.1}/src/unifi_network_maps/adapters/unifi.py

@@ -39,30 +39,83 @@ def _cache_key(*parts: str) -> str:
 
 
 def _load_cache(path: Path, ttl_seconds: int) -> object | None:
-    if ttl_seconds <= 0 or not path.exists():
+    data, age = _load_cache_with_age(path)
+    if data is None:
         return None
+    if ttl_seconds <= 0:
+        return None
+    if age is None or age > ttl_seconds:
+        return None
+    return data
+
+
+def _load_cache_with_age(path: Path) -> tuple[object | None, float | None]:
+    if not path.exists():
+        return None, None
     try:
         payload = pickle.loads(path.read_bytes())
     except Exception as exc:
         logger.debug("Failed to read cache %s: %s", path, exc)
-        return None
+        return None, None
     timestamp = payload.get("timestamp")
     if not isinstance(timestamp, int | float):
-        return None
-    if time.time() - timestamp > ttl_seconds:
-        return None
-    return payload.get("data")
+        return None, None
+    data = payload.get("data")
+    if not isinstance(data, list):
+        logger.debug("Cached payload at %s is not a list", path)
+        return None, None
+    return data, time.time() - timestamp
 
 
 def _save_cache(path: Path, data: object) -> None:
     try:
         path.parent.mkdir(parents=True, exist_ok=True)
         payload = {"timestamp": time.time(), "data": data}
-        path.write_bytes(pickle.dumps(payload))
+        tmp_path = path.with_suffix(path.suffix + ".tmp")
+        tmp_path.write_bytes(pickle.dumps(payload))
+        tmp_path.replace(path)
     except Exception as exc:
         logger.debug("Failed to write cache %s: %s", path, exc)
 
 
+def _retry_attempts() -> int:
+    value = os.environ.get("UNIFI_RETRY_ATTEMPTS", "").strip()
+    if not value:
+        return 2
+    if value.isdigit():
+        return max(1, int(value))
+    logger.warning("Invalid UNIFI_RETRY_ATTEMPTS value: %s", value)
+    return 2
+
+
+def _retry_backoff_seconds() -> float:
+    value = os.environ.get("UNIFI_RETRY_BACKOFF_SECONDS", "").strip()
+    if not value:
+        return 0.5
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        logger.warning("Invalid UNIFI_RETRY_BACKOFF_SECONDS value: %s", value)
+        return 0.5
+
+
+def _call_with_retries(operation: str, func) -> object:
+    attempts = _retry_attempts()
+    backoff = _retry_backoff_seconds()
+    last_exc: Exception | None = None
+    for attempt in range(1, attempts + 1):
+        try:
+            return func()
+        except Exception as exc:  # noqa: BLE001 - surface full error after retries
+            last_exc = exc
+            logger.warning("Failed %s attempt %d/%d: %s", operation, attempt, attempts, exc)
+            if attempt < attempts and backoff > 0:
+                time.sleep(backoff * attempt)
+    if last_exc:
+        raise last_exc
+    raise RuntimeError(f"Failed {operation}")
+
+
 def _init_controller(config: Config, *, is_udm_pro: bool) -> UnifiController:
     from unifi_controller_api import UnifiController
 
@@ -91,6 +144,7 @@ def fetch_devices(
     ttl_seconds = _cache_ttl_seconds()
     cache_path = _cache_dir() / f"devices_{_cache_key(config.url, site_name, str(detailed))}.pkl"
     cached = _load_cache(cache_path, ttl_seconds)
+    stale_cached, cache_age = _load_cache_with_age(cache_path)
     if cached is not None:
         logger.info("Using cached devices (%d)", len(cached))
         return cached
@@ -101,7 +155,20 @@ def fetch_devices(
         logger.info("UDM Pro authentication failed, retrying legacy auth")
         controller = _init_controller(config, is_udm_pro=False)
 
-    devices = controller.get_unifi_site_device(site_name=site_name, detailed=detailed, raw=False)
+    def _fetch() -> list[object]:
+        return controller.get_unifi_site_device(site_name=site_name, detailed=detailed, raw=False)
+
+    try:
+        devices = _call_with_retries("device fetch", _fetch)
+    except Exception as exc:  # noqa: BLE001 - fallback to cache
+        if stale_cached is not None:
+            logger.warning(
+                "Device fetch failed; using stale cache (%ds old): %s",
+                int(cache_age or 0),
+                exc,
+            )
+            return stale_cached
+        raise
     _save_cache(cache_path, devices)
     logger.info("Fetched %d devices", len(devices))
     return devices
@@ -118,6 +185,7 @@ def fetch_clients(config: Config, *, site: str | None = None) -> Iterable[object
     ttl_seconds = _cache_ttl_seconds()
     cache_path = _cache_dir() / f"clients_{_cache_key(config.url, site_name)}.pkl"
     cached = _load_cache(cache_path, ttl_seconds)
+    stale_cached, cache_age = _load_cache_with_age(cache_path)
     if cached is not None:
         logger.info("Using cached clients (%d)", len(cached))
         return cached
@@ -128,7 +196,20 @@ def fetch_clients(config: Config, *, site: str | None = None) -> Iterable[object
         logger.info("UDM Pro authentication failed, retrying legacy auth")
         controller = _init_controller(config, is_udm_pro=False)
 
-    clients = controller.get_unifi_site_client(site_name=site_name, raw=True)
+    def _fetch() -> list[object]:
+        return controller.get_unifi_site_client(site_name=site_name, raw=True)
+
+    try:
+        clients = _call_with_retries("client fetch", _fetch)
+    except Exception as exc:  # noqa: BLE001 - fallback to cache
+        if stale_cached is not None:
+            logger.warning(
+                "Client fetch failed; using stale cache (%ds old): %s",
+                int(cache_age or 0),
+                exc,
+            )
+            return stale_cached
+        raise
     _save_cache(cache_path, clients)
     logger.info("Fetched %d clients", len(clients))
     return clients