$ show bastgau/ha-pi-hole-v6
This repository is a Home Assistant custom integration for Pi-hole V6, providing comprehensive monitoring and control of Pi-hole DNS ad-blocking directly from Home Assistant. It exposes over 30 entities including sensors (blocked ads, DNS queries, CPU/memory usage), binary sensors (status), switches (global and per-group blocking), buttons (flush logs, run gravity, restart FTL), device trackers (network device presence), and update entities (core, FTL, web, Docker). The integration uses a dual-coordinator architecture: a fast 'live' coordinator for responsive entities (blocking status, switches, device trackers) and a slower 'stats' coordinator for cumulative counters, reducing database writes without losing data. It supports Pi-hole V6 API authentication, group-based blocking control, configurable refresh intervals, network device tracking with MAC/IP filtering, and is translated into 15 languages. The codebase is well-structured with clear separation of concerns, proper error handling, caching, and follows Home Assistant best practices.
The LLM identified 3 files worth highlighting for reuse:
A self-contained async HTTP client for the Pi-hole V6 API. Handles authentication (login/logout/session management), request serialization, error mapping (via handle_status), and response caching for multiple endpoints (summary, blocking, groups, clients, DHCP leases, network devices, FTL messages). The client is designed to be reusable outside Home Assistant: it only depends on aiohttp and standard library modules. It implements a lock-based authentication sequence to prevent concurrent session issues and provides clean public methods for all Pi-hole V6 API operations.
A comprehensive exception hierarchy for Pi-hole V6 API errors. Defines base class PiHoleV6Error and specialized subclasses for every HTTP status code (BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, etc.), plus custom errors like DataStructureError, ActionExecutionError, and ClientConnectorError. The handle_status function maps HTTP status codes to exceptions, making error handling consistent across the integration. This pattern is reusable for any API client project.
Two small but reusable utility functions: create_entity_id_name normalizes entity IDs by slugifying the domain-specific part while preserving the domain prefix, and parse_mac_list parses a user-provided string of MAC/IP addresses (comma or newline separated) into a normalized set. Both are generic enough to be extracted into any Home Assistant integration or general Python project.