unifi-topology 1.0.7

Python library for UniFi network topology discovery and SVG rendering

unifi-topology

Python library for UniFi network topology discovery and SVG diagram rendering.

Extracted from unifi-network-maps to provide a clean library API for programmatic use, including the Home Assistant integration.

Installation

pip install unifi-topology

Quick Start

from unifi_topology import (
    Config,
    fetch_devices,
    fetch_networks,
    normalize_devices,
    build_topology,
    extract_wan_info,
    render_svg,
    resolve_svg_themes,
    SvgOptions,
)

# Connect to UniFi controller
config = Config.from_env()
api_devices = fetch_devices(config)
networks = fetch_networks(config)

# Build topology model
devices = normalize_devices(api_devices)
result = build_topology(devices, include_ports=True, only_unifi=False)
wan_info = extract_wan_info(devices, list(networks))

# Render SVG
theme = resolve_svg_themes(theme_name="unifi")
options = SvgOptions(include_ports=True)
svg = render_svg(result.devices, result.edges, theme=theme, options=options, wan_info=wan_info)

API Overview

Adapters

• Config -- Configuration from environment variables (UNIFI_URL, UNIFI_USER, UNIFI_PASS, etc.)
• fetch_devices(config) -- Fetch device list from UniFi controller
• fetch_clients(config) -- Fetch active clients
• fetch_networks(config) -- Fetch network/VLAN configuration
• fetch_firewall_zones(config) -- Fetch firewall zone definitions
• fetch_firewall_policies(config) -- Fetch zone-based firewall policies
• fetch_firewall_groups(config) -- Fetch firewall address/port groups
• resolve_hostnames(ips, dns_server) -- Reverse DNS resolution

Model

• normalize_devices(raw) -- Convert raw API data to Device objects
• normalize_firewall_zones(raw) -- Convert raw zone data to FirewallZone objects
• normalize_firewall_policies(raw) -- Convert raw policy data to FirewallPolicy objects
• normalize_firewall_groups(raw) -- Convert raw group data to FirewallGroup objects
• build_topology(devices, ...) -- Build topology graph (TopologyResult with devices + edges)
• build_device_inventory(devices) -- Build device info table (list[DeviceInfo])
• extract_wan_info(devices, networks) -- Extract WAN upstream info

Rendering

• render_svg(devices, edges, theme, options, ...) -- Orthogonal SVG diagram
• render_svg_isometric(devices, edges, theme, options, ...) -- Isometric 3D-style SVG
• render_dual(devices, edges, themes, options, ...) -- Dual light/dark theme SVG
• resolve_svg_themes(theme_name, theme_file) -- Load built-in or custom SVG theme

Built-in themes: unifi, unifi-dark, minimal, minimal-dark, classic, classic-dark

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

make lint        # ruff check
make format      # ruff format
make typecheck   # pyright
make test        # pytest
make ci          # all checks

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT -- see LICENSE. Third-party licenses in LICENSES.md.