unifi-network-maps 1.4.11__py3-none-any.whl → 1.4.13__py3-none-any.whl

unifi_network_maps/__init__.py

@@ -1 +1 @@
-__version__ = "1.4.11"
+__version__ = "1.4.13"

unifi_network_maps/adapters/config.py

@@ -4,6 +4,9 @@ from __future__ import annotations
 
 import os
 from dataclasses import dataclass
+from pathlib import Path
+
+from ..io.paths import resolve_env_file
 
 
 def _parse_bool(value: str | None, default: bool = True) -> bool:
@@ -26,13 +29,14 @@ class Config:
     verify_ssl: bool
 
     @classmethod
-    def from_env(cls, *, env_file: str | None = None) -> Config:
+    def from_env(cls, *, env_file: str | Path | 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)
+            env_path = resolve_env_file(env_file)
+            load_dotenv(dotenv_path=env_path)
         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/adapters/unifi.py

@@ -7,6 +7,7 @@ import json
 import logging
 import os
 import stat
+import tempfile
 import time
 from collections.abc import Callable, Iterator, Sequence
 from concurrent.futures import ThreadPoolExecutor
@@ -15,6 +16,7 @@ from contextlib import contextmanager
 from pathlib import Path
 from typing import IO, TYPE_CHECKING
 
+from ..io.paths import resolve_cache_dir
 from .config import Config
 
 if TYPE_CHECKING:
@@ -24,7 +26,15 @@ logger = logging.getLogger(__name__)
 
 
 def _cache_dir() -> Path:
-    return Path(os.environ.get("UNIFI_CACHE_DIR", ".cache/unifi_network_maps"))
+    default_dir = ".cache/unifi_network_maps"
+    if os.environ.get("PYTEST_CURRENT_TEST"):
+        default_dir = str(Path(tempfile.gettempdir()) / f"unifi_network_maps_pytest_{os.getpid()}")
+    value = os.environ.get("UNIFI_CACHE_DIR", default_dir)
+    try:
+        return resolve_cache_dir(value)
+    except ValueError as exc:
+        logger.warning("Invalid UNIFI_CACHE_DIR (%s); using default: %s", value, exc)
+        return resolve_cache_dir(".cache/unifi_network_maps")
 
 
 def _device_attr(device: object, name: str) -> object | None:
@@ -377,13 +387,13 @@ def fetch_devices(
         cached = None
         stale_cached, cache_age = None, None
     if cached is not None:
-        logger.info("Using cached devices (%d)", len(cached))
+        logger.debug("Using cached devices (%d)", len(cached))
         return cached
 
     try:
         controller = _init_controller(config, is_udm_pro=True)
     except UnifiAuthenticationError:
-        logger.info("UDM Pro authentication failed, retrying legacy auth")
+        logger.debug("UDM Pro authentication failed, retrying legacy auth")
         controller = _init_controller(config, is_udm_pro=False)
 
     def _fetch() -> Sequence[object]:
@@ -402,7 +412,7 @@ def fetch_devices(
         raise
     if use_cache:
         _save_cache(cache_path, _serialize_devices_for_cache(devices))
-    logger.info("Fetched %d devices", len(devices))
+    logger.debug("Fetched %d devices", len(devices))
     return devices
 
 
@@ -428,13 +438,13 @@ def fetch_clients(
         cached = None
         stale_cached, cache_age = None, None
     if cached is not None:
-        logger.info("Using cached clients (%d)", len(cached))
+        logger.debug("Using cached clients (%d)", len(cached))
         return cached
 
     try:
         controller = _init_controller(config, is_udm_pro=True)
     except UnifiAuthenticationError:
-        logger.info("UDM Pro authentication failed, retrying legacy auth")
+        logger.debug("UDM Pro authentication failed, retrying legacy auth")
         controller = _init_controller(config, is_udm_pro=False)
 
     def _fetch() -> Sequence[object]:
@@ -453,5 +463,5 @@ def fetch_clients(
         raise
     if use_cache:
         _save_cache(cache_path, clients)
-    logger.info("Fetched %d clients", len(clients))
+    logger.debug("Fetched %d clients", len(clients))
     return clients

unifi_network_maps/cli/main.py

@@ -4,10 +4,17 @@ from __future__ import annotations
 
 import argparse
 import logging
+from pathlib import Path
 
 from ..adapters.config import Config
 from ..io.export import write_output
 from ..io.mock_data import load_mock_data
+from ..io.paths import (
+    resolve_env_file,
+    resolve_mock_data_path,
+    resolve_output_path,
+    resolve_theme_path,
+)
 from ..render.legend import render_legend_only, resolve_legend_style
 from ..render.theme import resolve_themes
 from .args import build_parser
@@ -16,7 +23,7 @@ from .render import render_lldp_format, render_standard_format
 logger = logging.getLogger(__name__)
 
 
-def _load_dotenv(env_file: str | None = None) -> None:
+def _load_dotenv(env_file: str | Path | None = None) -> None:
     try:
         from dotenv import load_dotenv
     except ImportError:
@@ -30,6 +37,36 @@ def _parse_args(argv: list[str] | None) -> argparse.Namespace:
     return parser.parse_args(argv)
 
 
+class _DowngradeInfoToDebugFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        if record.name.startswith("unifi_controller_api") and record.levelno == logging.INFO:
+            record.levelno = logging.DEBUG
+            record.levelname = logging.getLevelName(logging.DEBUG)
+        return True
+
+
+def _downgrade_unifi_controller_logs() -> logging.Filter:
+    return _DowngradeInfoToDebugFilter()
+
+
+def _validate_paths(args: argparse.Namespace) -> bool:
+    try:
+        if args.env_file:
+            resolve_env_file(args.env_file)
+        if args.mock_data:
+            resolve_mock_data_path(args.mock_data, require_exists=False)
+        if args.theme_file:
+            resolve_theme_path(args.theme_file, require_exists=False)
+        if args.generate_mock:
+            resolve_output_path(args.generate_mock, format_name="mock")
+        if args.output:
+            resolve_output_path(args.output, format_name=args.format)
+    except ValueError as exc:
+        logging.error(str(exc))
+        return False
+    return True
+
+
 def _load_config(args: argparse.Namespace) -> Config | None:
     try:
         _load_dotenv(args.env_file)
@@ -59,7 +96,8 @@ def _handle_generate_mock(args: argparse.Namespace) -> int | None:
         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)
+    output_kwargs = {"format_name": "mock"} if args.generate_mock else {}
+    write_output(content, output_path=args.generate_mock, stdout=args.stdout, **output_kwargs)
     return 0
 
 
@@ -81,7 +119,11 @@ def _load_runtime_context(
 
 def main(argv: list[str] | None = None) -> int:
     logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    for handler in logging.getLogger().handlers:
+        handler.addFilter(_downgrade_unifi_controller_logs())
     args = _parse_args(argv)
+    if not _validate_paths(args):
+        return 2
     mock_result = _handle_generate_mock(args)
     if mock_result is not None:
         return mock_result
@@ -107,7 +149,8 @@ def main(argv: list[str] | None = None) -> int:
             markdown=args.markdown,
             theme=mermaid_theme,
         )
-        write_output(content, output_path=args.output, stdout=args.stdout)
+        output_kwargs = {"format_name": args.format} if args.output else {}
+        write_output(content, output_path=args.output, stdout=args.stdout, **output_kwargs)
         return 0
 
     if args.format == "lldp-md":

unifi_network_maps/cli/render.py

@@ -62,7 +62,12 @@ def render_mermaid_output(
         direction=args.direction,
         groups=groups,
         group_order=group_order,
-        node_types=build_node_type_map(devices, clients, client_mode=args.client_scope),
+        node_types=build_node_type_map(
+            devices,
+            clients,
+            client_mode=args.client_scope,
+            only_unifi=args.only_unifi,
+        ),
         theme=mermaid_theme,
     )
     if args.markdown:
@@ -97,13 +102,23 @@ def render_svg_output(
 
         return render_svg_isometric(
             edges,
-            node_types=build_node_type_map(devices, clients, client_mode=args.client_scope),
+            node_types=build_node_type_map(
+                devices,
+                clients,
+                client_mode=args.client_scope,
+                only_unifi=args.only_unifi,
+            ),
             options=options,
             theme=svg_theme,
         )
     return render_svg(
         edges,
-        node_types=build_node_type_map(devices, clients, client_mode=args.client_scope),
+        node_types=build_node_type_map(
+            devices,
+            clients,
+            client_mode=args.client_scope,
+            only_unifi=args.only_unifi,
+        ),
         options=options,
         theme=svg_theme,
     )
@@ -190,8 +205,10 @@ def render_lldp_format(
         include_ports=args.include_ports,
         show_clients=args.include_clients,
         client_mode=args.client_scope,
+        only_unifi=args.only_unifi,
     )
-    write_output(content, output_path=args.output, stdout=args.stdout)
+    output_kwargs = {"format_name": args.format} if args.output else {}
+    write_output(content, output_path=args.output, stdout=args.stdout, **output_kwargs)
     return 0
 
 
@@ -251,5 +268,6 @@ def render_standard_format(
         logging.error("Unsupported format: %s", args.format)
         return 2
 
-    write_output(content, output_path=args.output, stdout=args.stdout)
+    output_kwargs = {"format_name": args.format} if args.output else {}
+    write_output(content, output_path=args.output, stdout=args.stdout, **output_kwargs)
     return 0

unifi_network_maps/cli/runtime.py

@@ -95,6 +95,7 @@ def build_edges_with_clients(
             device_index,
             include_ports=args.include_ports,
             client_mode=args.client_scope,
+            only_unifi=args.only_unifi,
         )
     return edges, clients
 
@@ -153,5 +154,10 @@ def resolve_mkdocs_client_ports(
         clients = list(fetch_clients(config, site=site))
     else:
         clients = mock_clients
-    client_ports = build_client_port_map(devices, clients, client_mode=args.client_scope)
+    client_ports = build_client_port_map(
+        devices,
+        clients,
+        client_mode=args.client_scope,
+        only_unifi=args.only_unifi,
+    )
     return client_ports, None

unifi_network_maps/io/export.py

@@ -7,10 +7,19 @@ import sys
 import tempfile
 from pathlib import Path
 
+from .paths import resolve_output_path
 
-def write_output(content: str, *, output_path: str | None, stdout: bool) -> None:
+
+def write_output(
+    content: str,
+    *,
+    output_path: str | Path | None,
+    stdout: bool,
+    format_name: str | None = None,
+) -> None:
     if output_path:
-        _write_atomic(Path(output_path), content)
+        resolved = resolve_output_path(output_path, format_name=format_name)
+        _write_atomic(resolved, content)
     if stdout or not output_path:
         sys.stdout.write(content)
 

unifi_network_maps/io/mkdocs_assets.py

@@ -5,10 +5,12 @@ from __future__ import annotations
 from pathlib import Path
 
 from ..render.templating import render_template
+from .paths import resolve_output_file
 
 
-def write_mkdocs_sidebar_assets(output_path: str) -> None:
-    output_dir = Path(output_path).resolve().parent
+def write_mkdocs_sidebar_assets(output_path: str | Path) -> None:
+    resolved = resolve_output_file(output_path, extensions=None, label="MkDocs output file")
+    output_dir = resolved.parent
     assets_dir = output_dir / "assets"
     assets_dir.mkdir(parents=True, exist_ok=True)
     (assets_dir / "legend.js").write_text(

unifi_network_maps/io/mock_data.py

@@ -3,7 +3,8 @@
 from __future__ import annotations
 
 import json
-from pathlib import Path
+
+from .paths import resolve_mock_data_path
 
 
 def _as_list(value: object, name: str) -> list[object]:
@@ -15,7 +16,8 @@ def _as_list(value: object, name: str) -> list[object]:
 
 
 def load_mock_data(path: str) -> tuple[list[object], list[object]]:
-    payload = json.loads(Path(path).read_text(encoding="utf-8"))
+    resolved = resolve_mock_data_path(path)
+    payload = json.loads(resolved.read_text(encoding="utf-8"))
     if not isinstance(payload, dict):
         raise ValueError("Mock data must be a JSON object")
     devices = _as_list(payload.get("devices"), "devices")

unifi_network_maps/io/paths.py

@@ -0,0 +1,197 @@
+"""Path validation helpers for user-supplied file system inputs."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from collections.abc import Iterable
+from pathlib import Path
+
+
+def _safe_home_dir() -> Path | None:
+    try:
+        return Path.home().resolve()
+    except Exception:
+        return None
+
+
+def _base_roots() -> list[Path]:
+    roots = [Path.cwd().resolve()]
+    home = _safe_home_dir()
+    if home:
+        roots.append(home)
+    try:
+        roots.append(Path(tempfile.gettempdir()).resolve())
+    except Exception:
+        pass
+    return roots
+
+
+def _extra_roots_from_env() -> list[Path]:
+    extra = os.environ.get("UNIFI_ALLOWED_PATHS", "")
+    roots: list[Path] = []
+    if extra:
+        for raw in extra.split(os.pathsep):
+            raw = raw.strip()
+            if raw:
+                roots.append(Path(raw).expanduser().resolve())
+    return roots
+
+
+def _allowed_roots() -> tuple[Path, ...]:
+    roots = _base_roots() + _extra_roots_from_env()
+    seen: set[str] = set()
+    unique: list[Path] = []
+    for root in roots:
+        key = str(root)
+        if key not in seen:
+            seen.add(key)
+            unique.append(root)
+    return tuple(unique)
+
+
+def _resolve_user_path(path: str | Path) -> Path:
+    return Path(path).expanduser().resolve(strict=False)
+
+
+def _ensure_within_allowed(path: Path, roots: Iterable[Path], *, label: str) -> None:
+    for root in roots:
+        try:
+            path.relative_to(root)
+        except ValueError:
+            continue
+        else:
+            return
+    root_list = ", ".join(str(root) for root in roots)
+    raise ValueError(f"{label} must be within: {root_list}")
+
+
+def _ensure_no_symlink(path: Path, *, label: str) -> None:
+    if path.exists() and path.is_symlink():
+        raise ValueError(f"{label} must not be a symlink: {path}")
+
+
+def _ensure_no_symlink_in_parents(path: Path, *, label: str) -> None:
+    for parent in path.parents:
+        if parent.exists() and parent.is_symlink():
+            raise ValueError(f"{label} parent must not be a symlink: {parent}")
+
+
+def _normalize_extensions(extensions: Iterable[str]) -> set[str]:
+    normalized = set()
+    for ext in extensions:
+        ext = ext.strip().lower()
+        if not ext:
+            continue
+        if not ext.startswith("."):
+            ext = f".{ext}"
+        normalized.add(ext)
+    return normalized
+
+
+def _ensure_extension(
+    path: Path,
+    extensions: Iterable[str] | None,
+    *,
+    label: str,
+    allow_missing: bool = False,
+) -> None:
+    if not extensions:
+        return
+    allowed = _normalize_extensions(extensions)
+    suffix = path.suffix.lower()
+    if not suffix:
+        if allow_missing:
+            return
+        raise ValueError(f"{label} must have one of: {', '.join(sorted(allowed))}")
+    if suffix not in allowed:
+        raise ValueError(f"{label} must have one of: {', '.join(sorted(allowed))}")
+
+
+def resolve_input_file(
+    path: str | Path,
+    *,
+    extensions: Iterable[str] | None,
+    label: str,
+    require_exists: bool = True,
+) -> Path:
+    resolved = _resolve_user_path(path)
+    _ensure_within_allowed(resolved, _allowed_roots(), label=label)
+    _ensure_extension(resolved, extensions, label=label)
+    if require_exists:
+        if not resolved.exists():
+            raise ValueError(f"{label} does not exist: {resolved}")
+        if not resolved.is_file():
+            raise ValueError(f"{label} must be a file: {resolved}")
+    return resolved
+
+
+def resolve_output_file(
+    path: str | Path,
+    *,
+    extensions: Iterable[str] | None,
+    label: str,
+    allow_missing_extension: bool = False,
+) -> Path:
+    resolved = _resolve_user_path(path)
+    _ensure_within_allowed(resolved, _allowed_roots(), label=label)
+    _ensure_extension(
+        resolved,
+        extensions,
+        label=label,
+        allow_missing=allow_missing_extension,
+    )
+    return resolved
+
+
+def resolve_env_file(path: str | Path) -> Path:
+    resolved = _resolve_user_path(path)
+    _ensure_within_allowed(resolved, _allowed_roots(), label="Env file")
+    if not (resolved.name.startswith(".env") or resolved.name.endswith(".env")):
+        raise ValueError("Env file must end with .env")
+    if resolved.exists() and not resolved.is_file():
+        raise ValueError(f"Env file must be a file: {resolved}")
+    return resolved
+
+
+def resolve_mock_data_path(path: str | Path, *, require_exists: bool = True) -> Path:
+    return resolve_input_file(
+        path,
+        extensions={".json"},
+        label="Mock data file",
+        require_exists=require_exists,
+    )
+
+
+def resolve_theme_path(path: str | Path, *, require_exists: bool = True) -> Path:
+    return resolve_input_file(
+        path,
+        extensions={".yml", ".yaml"},
+        label="Theme file",
+        require_exists=require_exists,
+    )
+
+
+def resolve_output_path(path: str | Path, *, format_name: str | None) -> Path:
+    extensions: set[str] | None
+    if format_name == "svg" or format_name == "svg-iso":
+        extensions = {".svg"}
+    elif format_name == "mock":
+        extensions = {".json"}
+    elif format_name == "mermaid":
+        extensions = {".md", ".mermaid", ".mmd"}
+    elif format_name == "lldp-md":
+        extensions = {".md"}
+    elif format_name == "mkdocs":
+        extensions = {".md"}
+    else:
+        extensions = None
+    return resolve_output_file(path, extensions=extensions, label="Output file")
+
+
+def resolve_cache_dir(path: str | Path) -> Path:
+    resolved = _resolve_user_path(path)
+    _ensure_within_allowed(resolved, _allowed_roots(), label="Cache directory")
+    _ensure_no_symlink(resolved, label="Cache directory")
+    _ensure_no_symlink_in_parents(resolved, label="Cache directory")
+    return resolved

unifi_network_maps/model/topology.py

@@ -460,7 +460,13 @@ def _client_field(client: object, name: str) -> object | None:
 
 
 def _client_display_name(client: object) -> str | None:
-    for key in ("name", "hostname", "mac"):
+    raw_name = _client_field(client, "name")
+    if isinstance(raw_name, str) and raw_name.strip():
+        return raw_name.strip()
+    preferred = _client_ucore_display_name(client)
+    if preferred:
+        return preferred
+    for key in ("hostname", "mac"):
         value = _client_field(client, key)
         if isinstance(value, str) and value.strip():
             return value.strip()
@@ -514,6 +520,73 @@ def _client_is_wired(client: object) -> bool:
     return bool(_client_field(client, "is_wired"))
 
 
+def _client_unifi_flag(client: object) -> bool | None:
+    for key in ("is_unifi", "is_unifi_device", "is_ubnt", "is_uap", "is_managed"):
+        value = _client_field(client, key)
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, int):
+            return value != 0
+    return None
+
+
+def _client_vendor(client: object) -> str | None:
+    for key in ("oui", "vendor", "vendor_name", "manufacturer", "manufacturer_name"):
+        value = _client_field(client, key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def _client_ucore_info(client: object) -> dict[str, object] | None:
+    info = _client_field(client, "unifi_device_info_from_ucore")
+    if isinstance(info, dict):
+        return info
+    return None
+
+
+def _client_ucore_display_name(client: object) -> str | None:
+    ucore = _client_ucore_info(client)
+    if not ucore:
+        return None
+    for key in ("name", "computed_model", "product_model", "product_shortname"):
+        value = ucore.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def _client_hostname_source(client: object) -> str | None:
+    value = _client_field(client, "hostname_source")
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None
+
+
+def _client_is_unifi(client: object) -> bool:
+    flag = _client_unifi_flag(client)
+    if flag is not None:
+        return flag
+    ucore = _client_ucore_info(client)
+    if ucore:
+        managed = ucore.get("managed")
+        if isinstance(managed, bool) and managed:
+            return True
+        if isinstance(ucore.get("product_line"), str) and ucore.get("product_line"):
+            return True
+        if isinstance(ucore.get("product_shortname"), str) and ucore.get("product_shortname"):
+            return True
+        for key in ("name", "computed_model", "product_model"):
+            value = ucore.get(key)
+            if isinstance(value, str) and value.strip():
+                return True
+    vendor = _client_vendor(client)
+    if not vendor:
+        return False
+    normalized = vendor.lower()
+    return "ubiquiti" in normalized or "unifi" in normalized
+
+
 def _client_channel(client: object) -> int | None:
     for key in ("channel", "radio_channel", "wifi_channel"):
         value = _client_field(client, key)
@@ -533,17 +606,26 @@ def _client_matches_mode(client: object, mode: str) -> bool:
     return wired
 
 
+def _client_matches_filters(client: object, *, client_mode: str, only_unifi: bool) -> bool:
+    if not _client_matches_mode(client, client_mode):
+        return False
+    if only_unifi and not _client_is_unifi(client):
+        return False
+    return True
+
+
 def build_client_edges(
     clients: Iterable[object],
     device_index: dict[str, str],
     *,
     include_ports: bool = False,
     client_mode: str = "wired",
+    only_unifi: bool = False,
 ) -> list[Edge]:
     edges: list[Edge] = []
     seen: set[tuple[str, str]] = set()
     for client in clients:
-        if not _client_matches_mode(client, client_mode):
+        if not _client_matches_filters(client, client_mode=client_mode, only_unifi=only_unifi):
             continue
         name = _client_display_name(client)
         uplink_mac = _client_uplink_mac(client)
@@ -580,13 +662,14 @@ def build_node_type_map(
     clients: Iterable[object] | None = None,
     *,
     client_mode: str = "wired",
+    only_unifi: bool = False,
 ) -> dict[str, str]:
     node_types: dict[str, str] = {}
     for device in devices:
         node_types[device.name] = classify_device_type(device)
     if clients:
         for client in clients:
-            if not _client_matches_mode(client, client_mode):
+            if not _client_matches_filters(client, client_mode=client_mode, only_unifi=only_unifi):
                 continue
             name = _client_display_name(client)
             if name:
@@ -640,7 +723,7 @@ def build_edges(
     )
 
     poe_edges = sum(1 for edge in edges if edge.poe)
-    logger.info("Built %d unique edges (%d PoE)", len(edges), poe_edges)
+    logger.debug("Built %d unique edges (%d PoE)", len(edges), poe_edges)
     return edges
 
 
@@ -683,11 +766,12 @@ def build_client_port_map(
     clients: Iterable[object],
     *,
     client_mode: str,
+    only_unifi: bool = False,
 ) -> ClientPortMap:
     device_index = build_device_index(devices)
     port_map: ClientPortMap = {}
     for client in clients:
-        if not _client_matches_mode(client, client_mode):
+        if not _client_matches_filters(client, client_mode=client_mode, only_unifi=only_unifi):
             continue
         name = _client_display_name(client)
         uplink_mac = _client_uplink_mac(client)
@@ -894,14 +978,14 @@ def build_topology(
 ) -> TopologyResult:
     normalized_devices = list(devices)
     lldp_entries = sum(len(device.lldp_info) for device in normalized_devices)
-    logger.info(
+    logger.debug(
         "Normalized %d devices (%d LLDP entries)",
         len(normalized_devices),
         lldp_entries,
     )
     raw_edges = build_edges(normalized_devices, include_ports=include_ports, only_unifi=only_unifi)
     tree_edges = build_tree_edges_by_topology(raw_edges, gateways)
-    logger.info(
+    logger.debug(
         "Built %d hierarchy edges (gateways=%d)",
         len(tree_edges),
         len(gateways),

unifi_network_maps/render/device_ports_md.py

@@ -83,11 +83,11 @@ def _render_device_ports(
     rows = _build_port_rows(device, port_map, client_ports)
     table_rows = [
         [
-            _escape_cell(port_label),
-            _escape_cell(connected or "-"),
-            _escape_cell(speed),
-            _escape_cell(poe_state),
-            _escape_cell(power),
+            _escape_markdown_text(port_label),
+            _escape_connected_cell(connected or "-"),
+            _escape_markdown_text(speed),
+            _escape_markdown_text(poe_state),
+            _escape_markdown_text(power),
         ]
         for port_label, connected, speed, poe_state, power in rows
     ]
@@ -224,9 +224,11 @@ def _format_connections(
     for peer in sorted(peers, key=str.lower):
         peer_label = port_map.get((peer, device_name))
         if peer_label:
-            peer_entries.append(f"{peer} ({peer_label})")
+            peer_entries.append(
+                f"{_escape_markdown_text(peer)} ({_escape_markdown_text(peer_label)})"
+            )
         else:
-            peer_entries.append(peer)
+            peer_entries.append(_escape_markdown_text(peer))
     peer_text = ", ".join(peer_entries)
     client_text = _format_client_connections(clients)
     if peer_text and client_text:
@@ -292,8 +294,15 @@ def _port_sort_key(port: object) -> tuple[int, str]:
     return (1, name.lower())
 
 
-def _escape_cell(value: str) -> str:
-    return value.replace("|", "\\|")
+def _escape_markdown_text(value: str) -> str:
+    escaped = value.replace("\\", "\\\\")
+    for char in ("|", "[", "]", "*", "_", "`", "<", ">"):
+        escaped = escaped.replace(char, f"\\{char}")
+    return escaped
+
+
+def _escape_connected_cell(value: str) -> str:
+    return value
 
 
 def _render_device_details(device: Device) -> list[str]:
@@ -302,14 +311,14 @@ def _render_device_details(device: Device) -> list[str]:
         "",
         "| Field | Value |",
         "| --- | --- |",
-        f"| Model | {_escape_cell(_device_model_label(device))} |",
-        f"| Type | {_escape_cell(device.type or '-')} |",
-        f"| IP | {_escape_cell(device.ip or '-')} |",
-        f"| MAC | {_escape_cell(device.mac or '-')} |",
-        f"| Firmware | {_escape_cell(device.version or '-')} |",
-        f"| Uplink | {_escape_cell(_uplink_summary(device))} |",
-        f"| Ports | {_escape_cell(_port_summary(device))} |",
-        f"| PoE | {_escape_cell(_poe_summary(device))} |",
+        f"| Model | {_escape_markdown_text(_device_model_label(device))} |",
+        f"| Type | {_escape_markdown_text(device.type or '-')} |",
+        f"| IP | {_escape_markdown_text(device.ip or '-')} |",
+        f"| MAC | {_escape_markdown_text(device.mac or '-')} |",
+        f"| Firmware | {_escape_markdown_text(device.version or '-')} |",
+        f"| Uplink | {_escape_markdown_text(_uplink_summary(device))} |",
+        f"| Ports | {_escape_markdown_text(_port_summary(device))} |",
+        f"| PoE | {_escape_markdown_text(_poe_summary(device))} |",
         "",
     ]
     return lines
@@ -367,7 +376,7 @@ def _format_client_connections(clients: list[str]) -> str:
     if not clients:
         return ""
     if len(clients) == 1:
-        return f"{clients[0]} (client)"
+        return f"{_escape_markdown_text(clients[0])} (client)"
     items = "".join(f"<li>{_escape_html(name)}</li>" for name in clients)
     return f'<ul class="unifi-port-clients">{items}</ul>'
 

unifi_network_maps/render/lldp_md.py

@@ -23,7 +23,13 @@ def _client_field(client: object, name: str) -> object | None:
 
 
 def _client_display_name(client: object) -> str | None:
-    for key in ("name", "hostname", "mac"):
+    raw_name = _client_field(client, "name")
+    if isinstance(raw_name, str) and raw_name.strip():
+        return raw_name.strip()
+    preferred = _client_ucore_display_name(client)
+    if preferred:
+        return preferred
+    for key in ("hostname", "mac"):
         value = _client_field(client, key)
         if isinstance(value, str) and value.strip():
             return value.strip()
@@ -77,6 +83,73 @@ def _client_is_wired(client: object) -> bool:
     return bool(_client_field(client, "is_wired"))
 
 
+def _client_unifi_flag(client: object) -> bool | None:
+    for key in ("is_unifi", "is_unifi_device", "is_ubnt", "is_uap", "is_managed"):
+        value = _client_field(client, key)
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, int):
+            return value != 0
+    return None
+
+
+def _client_vendor(client: object) -> str | None:
+    for key in ("oui", "vendor", "vendor_name", "manufacturer", "manufacturer_name"):
+        value = _client_field(client, key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def _client_ucore_info(client: object) -> dict[str, object] | None:
+    info = _client_field(client, "unifi_device_info_from_ucore")
+    if isinstance(info, dict):
+        return info
+    return None
+
+
+def _client_ucore_display_name(client: object) -> str | None:
+    ucore = _client_ucore_info(client)
+    if not ucore:
+        return None
+    for key in ("name", "computed_model", "product_model", "product_shortname"):
+        value = ucore.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def _client_hostname_source(client: object) -> str | None:
+    value = _client_field(client, "hostname_source")
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None
+
+
+def _client_is_unifi(client: object) -> bool:
+    flag = _client_unifi_flag(client)
+    if flag is not None:
+        return flag
+    ucore = _client_ucore_info(client)
+    if ucore:
+        managed = ucore.get("managed")
+        if isinstance(managed, bool) and managed:
+            return True
+        if isinstance(ucore.get("product_line"), str) and ucore.get("product_line"):
+            return True
+        if isinstance(ucore.get("product_shortname"), str) and ucore.get("product_shortname"):
+            return True
+        for key in ("name", "computed_model", "product_model"):
+            value = ucore.get(key)
+            if isinstance(value, str) and value.strip():
+                return True
+    vendor = _client_vendor(client)
+    if not vendor:
+        return False
+    normalized = vendor.lower()
+    return "ubiquiti" in normalized or "unifi" in normalized
+
+
 def _client_matches_mode(client: object, mode: str) -> bool:
     wired = _client_is_wired(client)
     if mode == "all":
@@ -86,6 +159,14 @@ def _client_matches_mode(client: object, mode: str) -> bool:
     return wired
 
 
+def _client_matches_filters(client: object, *, client_mode: str, only_unifi: bool) -> bool:
+    if not _client_matches_mode(client, client_mode):
+        return False
+    if only_unifi and not _client_is_unifi(client):
+        return False
+    return True
+
+
 def _lldp_sort_key(entry: LLDPEntry) -> tuple[int, str, str]:
     port_label = local_port_label(entry) or ""
     port_number = "".join(ch for ch in port_label if ch.isdigit())
@@ -190,7 +271,10 @@ def _lldp_rows(
 
 
 def _escape_cell(value: str) -> str:
-    return value.replace("|", "\\|")
+    escaped = value.replace("\\", "\\\\")
+    for char in ("|", "[", "]", "*", "_", "`", "<", ">"):
+        escaped = escaped.replace(char, f"\\{char}")
+    return escaped
 
 
 def _client_rows(
@@ -199,10 +283,11 @@ def _client_rows(
     *,
     include_ports: bool,
     client_mode: str,
+    only_unifi: bool,
 ) -> dict[str, list[tuple[str, str | None]]]:
     rows_by_device: dict[str, list[tuple[str, str | None]]] = {}
     for client in clients:
-        if not _client_matches_mode(client, client_mode):
+        if not _client_matches_filters(client, client_mode=client_mode, only_unifi=only_unifi):
             continue
         name = _client_display_name(client)
         uplink_mac = _client_uplink_mac(client)
@@ -227,6 +312,7 @@ def _prepare_lldp_maps(
     include_ports: bool,
     show_clients: bool,
     client_mode: str,
+    only_unifi: bool,
 ) -> tuple[
     dict[tuple[str, str], str],
     dict[str, list[tuple[int, str]]] | None,
@@ -234,7 +320,13 @@ def _prepare_lldp_maps(
 ]:
     device_index = build_device_index(devices)
     client_rows = (
-        _client_rows(clients, device_index, include_ports=include_ports, client_mode=client_mode)
+        _client_rows(
+            clients,
+            device_index,
+            include_ports=include_ports,
+            client_mode=client_mode,
+            only_unifi=only_unifi,
+        )
         if clients
         else {}
     )
@@ -243,7 +335,12 @@ def _prepare_lldp_maps(
     if include_ports:
         port_map = build_port_map(devices, only_unifi=False)
         if clients and show_clients:
-            client_port_map = build_client_port_map(devices, clients, client_mode=client_mode)
+            client_port_map = build_client_port_map(
+                devices,
+                clients,
+                client_mode=client_mode,
+                only_unifi=only_unifi,
+            )
     return port_map, client_port_map, client_rows
 
 
@@ -318,6 +415,7 @@ def render_lldp_md(
     include_ports: bool = False,
     show_clients: bool = False,
     client_mode: str = "wired",
+    only_unifi: bool = False,
 ) -> str:
     device_index = build_device_index(devices)
     port_map, client_port_map, client_rows = _prepare_lldp_maps(
@@ -326,6 +424,7 @@ def render_lldp_md(
         include_ports=include_ports,
         show_clients=show_clients,
         client_mode=client_mode,
+        only_unifi=only_unifi,
     )
     sections: list[str] = []
     for device in sorted(devices, key=lambda item: item.name.lower()):

unifi_network_maps/render/theme.py

@@ -6,6 +6,7 @@ from pathlib import Path
 
 import yaml
 
+from ..io.paths import resolve_theme_path
 from .mermaid_theme import DEFAULT_THEME as DEFAULT_MERMAID_THEME
 from .mermaid_theme import MermaidTheme
 from .svg_theme import DEFAULT_THEME as DEFAULT_SVG_THEME
@@ -90,7 +91,7 @@ def _svg_theme_from_dict(data: dict, base: SvgTheme) -> SvgTheme:
 
 
 def load_theme(path: str | Path) -> tuple[MermaidTheme, SvgTheme]:
-    theme_path = Path(path)
+    theme_path = resolve_theme_path(path, require_exists=False)
     payload = yaml.safe_load(theme_path.read_text(encoding="utf-8"))
     if not isinstance(payload, dict):
         raise ValueError("Theme file must contain a YAML mapping")

{unifi_network_maps-1.4.11.dist-info → unifi_network_maps-1.4.13.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unifi-network-maps
-Version: 1.4.11
+Version: 1.4.13
 Summary: Dynamic UniFi -> network maps in mermaid or svg
 Author: Merlijn
 License-Expression: MIT
@@ -32,7 +32,7 @@ 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: pyright==1.1.408; extra == "dev"
-Requires-Dist: ruff==0.14.13; extra == "dev"
+Requires-Dist: ruff==0.14.14; extra == "dev"
 Dynamic: license-file
 
 # unifi-network-maps
@@ -223,7 +223,7 @@ 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.
+- `--only-unifi`: only include neighbors that are UniFi devices; when clients are included, filters to UniFi-managed clients (by explicit UniFi flags or vendor/OUI).
 - `--no-cache`: disable UniFi API cache reads and writes.
 
 Mermaid:

{unifi_network_maps-1.4.11.dist-info → unifi_network_maps-1.4.13.dist-info}/RECORD

@@ -1,8 +1,8 @@
-unifi_network_maps/__init__.py,sha256=E_3GCl6XTRrqUMJy7bs7bnXqi2aoli2GL8PC4NQJkSE,23
+unifi_network_maps/__init__.py,sha256=3Jd0G1BzDzSEXU_O-VQeqAYwxMAmK7PBiIm9SYiPxoE,23
 unifi_network_maps/__main__.py,sha256=XsOjaqslAVgyVlOTokjVddZ2iT8apZXpJ_OB-9WEEe4,179
 unifi_network_maps/adapters/__init__.py,sha256=nzx1KsiYalL_YuXKE6acW8Dj5flmMg0-i4gyYO0gV54,22
-unifi_network_maps/adapters/config.py,sha256=Bx9JDZxxY7Gjxyb8FDT0dxiKfgXt_TmzTDbgvpwB53s,1548
-unifi_network_maps/adapters/unifi.py,sha256=olrs-K7EWK7Uhib8pjtPnkZg3LhnnSz-lcGuHG8RsOI,15140
+unifi_network_maps/adapters/config.py,sha256=gnvgAj9wPmYGGQfhcZSHRkcVGojODUYIINU_ztTcuUc,1671
+unifi_network_maps/adapters/unifi.py,sha256=MCW-kpLcmAF_9QZviT9T2oPfDI9hurtxALCBY8tbmfk,15601
 unifi_network_maps/assets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 unifi_network_maps/assets/icons/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 unifi_network_maps/assets/icons/access-point.svg,sha256=RJOgO2s9Ino5lWRrh4V7q8Jdwffros5bQq3UeDuQYF4,742
@@ -53,25 +53,26 @@ unifi_network_maps/assets/themes/default.yaml,sha256=F2Jj18NmdaJ_zyERvGAn8NEWBwa
 unifi_network_maps/cli/__init__.py,sha256=cds9GvFNZmYAR22Ab3TSzfriSAW--kf9jvC5U-21AoA,70
 unifi_network_maps/cli/__main__.py,sha256=nK_jh78VW3h3DRvSpjzpcf64zkCqniP2k82xUR9Hw2I,147
 unifi_network_maps/cli/args.py,sha256=lIgQDeob_SIhjXg76hJsnpgNOKupSjSYum_MqarWOkE,5552
-unifi_network_maps/cli/main.py,sha256=jQXesuHJLTQl4lBk1DD6em67Wj9oEjBmH9X-X1zA6MI,4150
-unifi_network_maps/cli/render.py,sha256=sUyDWm_I_zbEcKuNEpKUXDxhe1XptgOYsmdMP9BJ3Eg,7040
-unifi_network_maps/cli/runtime.py,sha256=Hln4LMpuTrEsy6gIBmqkOrUpMb4nTeZ-AH72KyxpZwA,4723
+unifi_network_maps/cli/main.py,sha256=Fedf93kc6f9w_V_Ik28gnrUGlB7oD0Yn5cdmHnj9nI4,5719
+unifi_network_maps/cli/render.py,sha256=wuvsC-In-ApbaQxBn8-UofB7jCiqUnjluGXRCRZpg5A,7535
+unifi_network_maps/cli/runtime.py,sha256=cMtIShERup2z2_uCcEGcaJFJptvdI0L3FDWqKFwSevY,4830
 unifi_network_maps/io/__init__.py,sha256=nzx1KsiYalL_YuXKE6acW8Dj5flmMg0-i4gyYO0gV54,22
 unifi_network_maps/io/debug.py,sha256=eUVs6GLfs6VqI6ma8ra7NLhC3q4ek2K8OSRLnpQDF9s,1745
-unifi_network_maps/io/export.py,sha256=2vURunQDja-_fKKMb-gQG-n34aeM8GFprNJqcGaP4qg,843
-unifi_network_maps/io/mkdocs_assets.py,sha256=oueDLiiIW05mN-mZ2BWV7oECX-EXDjJt8msCJHMcQwg,596
-unifi_network_maps/io/mock_data.py,sha256=uiQ8Ta8oxs5D1MUA1ONWmp09sxH0-FNlz3SJBXMeezo,714
+unifi_network_maps/io/export.py,sha256=1_RcXpPqoerCt7WsiheV4dwKgY2fFJlpjUGRs-EkHE4,1013
+unifi_network_maps/io/mkdocs_assets.py,sha256=pszCivIql3maaLw7KFcAioQaVcyLltXgg-fPXPBvvEk,716
+unifi_network_maps/io/mock_data.py,sha256=3nbg83APrdhmNW2w0Ha3FWoguMNfJy1IMtolinUPu0E,774
 unifi_network_maps/io/mock_generate.py,sha256=xiJz_qtNW7iVj7dezLNyVXAHtCHAi8U5CSXK5mrJE4U,233
+unifi_network_maps/io/paths.py,sha256=zE_kYkRXgHmPaRgzE45angYQk59aMC84JW7kcH11Qk0,5729
 unifi_network_maps/model/__init__.py,sha256=nzx1KsiYalL_YuXKE6acW8Dj5flmMg0-i4gyYO0gV54,22
 unifi_network_maps/model/labels.py,sha256=m_k8mbzWtOSDOjjHhLUqwIw93pg98HAtGtHkiERXmek,1135
 unifi_network_maps/model/lldp.py,sha256=SrPW5XC2lfJgaGeVx-KnSFNltyok7gIWWQNg1SkOaj4,3300
 unifi_network_maps/model/mock.py,sha256=kd1MSiIn-7KKu_nMVmheYPfTyAN5DHt4dzRrBifF_lI,8706
 unifi_network_maps/model/ports.py,sha256=o3NBlXcC5VV5iPWJsO4Ll1mRKJZC0f8zTHdlkkE34GU,609
-unifi_network_maps/model/topology.py,sha256=YOiLGKFEl4AQncaiM0C_uHt85lX1rsNM4n0HEZ5K-ns,28541
+unifi_network_maps/model/topology.py,sha256=rC1J1h70JIpkm6eIuFz7AjoNtKobPpVfAbiWgMyow2w,31475
 unifi_network_maps/render/__init__.py,sha256=nzx1KsiYalL_YuXKE6acW8Dj5flmMg0-i4gyYO0gV54,22
-unifi_network_maps/render/device_ports_md.py,sha256=vt5kGFSIAabMbcSxIuVVLSzdb_i58NHGi4hJM2ZLZR4,15975
+unifi_network_maps/render/device_ports_md.py,sha256=PLbP4_EDwLNkUACVJB_uM0ywaQTbEc6OWMv4QBcoJbU,16425
 unifi_network_maps/render/legend.py,sha256=TmZsxgCVOM2CZImI9zgRVyzrcg01HZFDj9F715d4CGo,772
-unifi_network_maps/render/lldp_md.py,sha256=13g9G_oQ-riTDakt-_qmGX8YtEmL0eikjFMbtiTKKVo,11672
+unifi_network_maps/render/lldp_md.py,sha256=oHPAYAfyCPJCuAJM4NJ4RIqgf52ihh555oNAlMB0DFg,14873
 unifi_network_maps/render/markdown_tables.py,sha256=VvM0fSnSmpeeDPcD5pXaL_j_PTF0STrMCaqnr2BVHn4,547
 unifi_network_maps/render/mermaid.py,sha256=xsC57Xg-nKhmlVATzEbwLkMM2BOeDYlBjZuxBIPhHeI,8324
 unifi_network_maps/render/mermaid_theme.py,sha256=7nqLlvhaUA4z0YOs0ByEx_yHWcQD_hJJjhDtRcbSpg4,1781
@@ -79,7 +80,7 @@ unifi_network_maps/render/mkdocs.py,sha256=EOST9_eP1ZoZQax-p-2fjlelrl3AKEJ9Gn-KX
 unifi_network_maps/render/svg.py,sha256=Zd6TFaBhqa92O2Z7G_k3LnRXIbuaOAj-dYu2qzEwWvI,41171
 unifi_network_maps/render/svg_theme.py,sha256=Si1ArM3v_-wAvHZyLFPiOZ0ohQRd6ezIckwC3_b-WIw,2684
 unifi_network_maps/render/templating.py,sha256=VJbXzZFBPjL8LFFPcLf_EU5Eu53GN9_vpten2Mf9A-k,576
-unifi_network_maps/render/theme.py,sha256=vKYdPhcGEOV1o_irwqzJlIXPgRvZqQEzYYV2_TxZn4E,4301
+unifi_network_maps/render/theme.py,sha256=LI-2dWaR0cRapvYBqeudGCT3tnT8B-nt-5h0yxkU8vU,4379
 unifi_network_maps/render/templates/device_port_block.md.j2,sha256=ZfyE_lEHz6ZyYRxAYhAhwpxlLczn_U9eTkRLUrwU5Io,50
 unifi_network_maps/render/templates/legend_compact.html.j2,sha256=DaY2m6N6Yd7qNKLuB5Bc395MHfrKOU9myAZvgcJrhpE,738
 unifi_network_maps/render/templates/lldp_device_section.md.j2,sha256=ewX-SBrL5Hn1kuwDKo4fqqetj9tTpR7LQavSn6No_yY,206
@@ -91,9 +92,9 @@ unifi_network_maps/render/templates/mkdocs_html_block.html.j2,sha256=5l5-BbNujOc
 unifi_network_maps/render/templates/mkdocs_legend.css.j2,sha256=tkTI-RagBSgdjUygVenlTsQFenU09ePbXOfDt_Q7YRM,612
 unifi_network_maps/render/templates/mkdocs_legend.js.j2,sha256=qMYyCKsJ84uXf1wGgzbc7Bc49RU4oyuaGK9KrgQDQEI,685
 unifi_network_maps/render/templates/mkdocs_mermaid_block.md.j2,sha256=9IncllWQpoI8BN3A7b2zOQ5cksj97ddsjHJ-aBhpw7o,66
-unifi_network_maps-1.4.11.dist-info/licenses/LICENSE,sha256=mYo1siIIfIwyfdOuK2-Zt0ij2xBTii2hnpeTu79nD80,1074
-unifi_network_maps-1.4.11.dist-info/METADATA,sha256=ihN2YNJUN-9W1RR2USmMtMGJq72XSSULMtG8k9qry4g,9851
-unifi_network_maps-1.4.11.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-unifi_network_maps-1.4.11.dist-info/entry_points.txt,sha256=cdJ7jsBgNgHxSflYUOqgz5BbvuM0Nnh-x8_Hbyh_LFg,67
-unifi_network_maps-1.4.11.dist-info/top_level.txt,sha256=G0rUX1PNfVCn1u-KtB6QjFQHopCOVLnPMczvPOoraHg,19
-unifi_network_maps-1.4.11.dist-info/RECORD,,
+unifi_network_maps-1.4.13.dist-info/licenses/LICENSE,sha256=mYo1siIIfIwyfdOuK2-Zt0ij2xBTii2hnpeTu79nD80,1074
+unifi_network_maps-1.4.13.dist-info/METADATA,sha256=HzxFdG6F9RwTXSAqF7o-Zl3a3a1dofXewvXZGYtKXlM,9952
+unifi_network_maps-1.4.13.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+unifi_network_maps-1.4.13.dist-info/entry_points.txt,sha256=cdJ7jsBgNgHxSflYUOqgz5BbvuM0Nnh-x8_Hbyh_LFg,67
+unifi_network_maps-1.4.13.dist-info/top_level.txt,sha256=G0rUX1PNfVCn1u-KtB6QjFQHopCOVLnPMczvPOoraHg,19
+unifi_network_maps-1.4.13.dist-info/RECORD,,

{unifi_network_maps-1.4.11.dist-info → unifi_network_maps-1.4.13.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.1)
 Root-Is-Purelib: true
 Tag: py3-none-any