pihole_lib package

Subpackages

Submodules

pihole_lib.actions module

Pi-hole Actions API client.

class pihole_lib.actions.PiHoleActions(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole Actions API client.

Handles action endpoints that perform operations on Pi-hole.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Update gravity database with streaming output
    for line in client.actions.update_gravity():
        print(line.strip())

    # Restart DNS service
    if client.actions.restart_dns():
        print("DNS restarted successfully")
BASE_URL: str = '/api/action'
update_gravity(color=False)[source]

Update Pi-hole’s gravity database (adlists).

Triggers Pi-hole’s gravity update process, which downloads and processes all configured adlists. The output is streamed with chunked encoding.

Parameters:

color (bool) – Include ANSI color escape codes in output. Defaults to False.

Yields:

Lines of output from the gravity update process.

Return type:

Iterator[str]

restart_dns()[source]

Restart Pi-hole’s DNS service (pihole-FTL).

Return type:

bool

Returns:

True if the restart was successful.

flush_logs()[source]

Flush Pi-hole’s DNS logs.

Empties the DNS log file and purges the most recent 24 hours from both the database and FTL’s internal memory.

Return type:

bool

Returns:

True if the flush was successful.

flush_network()[source]

Flush Pi-hole’s network table.

Removes all known devices and their associated addresses.

Return type:

bool

Returns:

True if the flush was successful.

pihole_lib.backup module

Pi-hole Backup API client.

class pihole_lib.backup.PiHoleBackup(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole Backup API client.

Handles backup and restore operations using the Teleporter endpoint.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Export backup
    backup_file = client.backup.export_backup("/path/to/backups")
    print(f"Backup saved to: {backup_file}")

    # Import backup
    imported_files = client.backup.import_backup("/path/to/backup.zip")
    print(f"Imported {len(imported_files)} files")
BASE_URL: str = '/api/teleporter'
export_backup(backup_dir)[source]

Export Pi-hole settings to a backup file.

Parameters:

backup_dir (str) – Directory where the backup file should be saved.

Return type:

str

Returns:

The full path to the created backup file.

import_backup(file_path, import_options=None)[source]

Import Pi-hole settings from a backup file.

Note: This will overwrite your current configuration and restart Pi-hole.

Parameters:

  • file_path (str) – Full path to the backup ZIP file to import.

  • import_options (Optional[TeleporterImportOptions]) – Options specifying which elements to restore. If None, all items will be restored.

Return type:

list[str]

Returns:

List of imported backup files/components.

pihole_lib.base module

Base classes for Pi-hole API clients.

class pihole_lib.base.BasePiHoleAPIClient(client)[source]

Bases: object

Base class for Pi-hole API clients.

Provides common functionality for all API client classes.

BASE_URL: str = ''
__init__(client)[source]

Initialize the API client.

Parameters:

client (PiHoleClient) – PiHoleClient instance to use for requests.

pihole_lib.client module

Pi-hole API client.

class pihole_lib.client.PiHoleClient(base_url, password, timeout=30, verify_ssl=True)[source]

Bases: object

Pi-hole API client.

Handles authentication and session management for Pi-hole API interactions. Can be used as a context manager for automatic cleanup.

Examples:

# Basic usage with property access
with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get system information
    login_info = client.info.get_login_info()

    # Perform actions
    for line in client.actions.update_gravity():
        print(line.strip())

    # Manage lists
    all_lists = client.lists.get_lists()

    # Configuration management
    current_config = client.config.get_config()

# Alternative usage with explicit class imports
from pihole_lib import PiHoleInfo, PiHoleActions

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    info = PiHoleInfo(client)
    actions = PiHoleActions(client)
DEFAULT_TIMEOUT = 30
HEADER_SESSION_ID = 'X-FTL-SID'
__init__(base_url, password, timeout=30, verify_ssl=True)[source]

Initialize a Pi-hole client.

Parameters:

  • base_url (str) – Pi-hole base URL (e.g., “http://192.168.1.100”).

  • password (str) – Pi-hole admin password.

  • timeout (int | None) – Request timeout in seconds. Defaults to 30.

  • verify_ssl (bool) – Whether to verify SSL certificates. Defaults to True.

__enter__()[source]

Enter context manager and authenticate.

Return type:

PiHoleClient

__exit__(exc_type, exc_val, exc_tb)[source]

Exit context manager and clean up resources.

Return type:

None

close()[source]

Close session and clean up resources.

Return type:

None

is_authenticated()[source]

Check if client is authenticated.

Return type:

bool

get_session_id()[source]

Get current session ID.

Return type:

str | None

property info: PiHoleInfo

Get Pi-hole info API client.

property actions: PiHoleActions

Get Pi-hole actions API client.

property backup: PiHoleBackup

Get Pi-hole backup API client.

property config: PiHoleConfig

Get Pi-hole config API client.

property dhcp: PiHoleDHCP

Get Pi-hole DHCP API client.

property dns: PiHoleDNS

Get Pi-hole DNS API client.

property lists: PiHoleLists

Get Pi-hole lists API client.

property groups: PiHoleGroups

Get Pi-hole groups API client.

property padd: PiHolePADD

Get Pi-hole PADD API client.

property stats: PiHoleStats

Get Pi-hole stats API client.

property domains: PiHoleDomains

Get Pi-hole domains API client.

property network: PiHoleNetwork

Get Pi-hole network API client.

property clients: PiHoleClients

Get Pi-hole clients API client.

pihole_lib.clients module

Pi-hole Clients API client.

class pihole_lib.clients.PiHoleClients(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole Clients API client.

Handles client management operations. Clients can be identified by IP address, MAC address, hostname, or interface.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get all clients
    all_clients = client.clients.get_clients()

    # Add a new client
    client.clients.add_client(
        client="192.168.1.50",
        comment="John's laptop",
        groups=[0, 1]
    )

    # Get client suggestions
    suggestions = client.clients.get_client_suggestions()
BASE_URL: str = '/api/clients'
get_clients(client=None)[source]

Get Pi-hole clients.

Parameters:

client (Optional[str]) – Optional specific client identifier to retrieve.

Return type:

list[Client]

Returns:

List of Client objects.

add_client(client, comment=None, groups=None)[source]

Add a new client to Pi-hole.

Parameters:

  • client (str) – Client identifier (IP, MAC, hostname, or interface).

  • comment (Optional[str]) – Optional comment for this client.

  • groups (Optional[list[int]]) – Group IDs to assign (defaults to [0]).

Return type:

list[Client]

Returns:

List of Client objects containing the created client.

update_client(client, comment=None, groups=None)[source]

Update an existing client in Pi-hole.

Parameters:

  • client (str) – Client identifier to update.

  • comment (Optional[str]) – Optional comment for this client.

  • groups (Optional[list[int]]) – Group IDs to assign (defaults to [0]).

Return type:

ClientsResponse

Returns:

ClientsResponse with the updated client and processing results.

delete_client(client)[source]

Delete a client from Pi-hole.

Parameters:

client (str) – Client identifier to delete.

Return type:

bool

Returns:

True if the client was successfully deleted.

batch_delete_clients(items)[source]

Delete multiple clients from Pi-hole.

Parameters:

items (list[ClientBatchDeleteItem]) – List of ClientBatchDeleteItem objects.

Return type:

bool

Returns:

True if all clients were successfully deleted.

get_client_suggestions()[source]

Get client suggestions from Pi-hole.

Returns unconfigured clients that have been seen by Pi-hole.

Return type:

list[Client]

Returns:

List of Client objects representing unconfigured clients.

pihole_lib.config module

Pi-hole Config API client.

class pihole_lib.config.PiHoleConfig(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole Config API client.

Handles configuration endpoints for Pi-hole settings.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get current configuration
    config = client.config.get_config()
    print(f"DNS upstreams: {config['dns']['upstreams']}")

    # Update configuration
    client.config.update_config({"dns": {"upstreams": ["1.1.1.1"]}})

    # Add/remove config items
    client.config.add_config_item("dns/upstreams", "8.8.8.8")
    client.config.remove_config_item("dns/upstreams", "8.8.8.8")
BASE_URL: str = '/api/config'
get_config(element=None, detailed=True)[source]

Get Pi-hole configuration.

Parameters:

  • element (Optional[str]) – Optional configuration element path (e.g., ‘dns’, ‘dhcp’). If None, returns the complete configuration.

  • detailed (bool) – Return detailed information (defaults to True).

Return type:

dict[str, Any]

Returns:

Dictionary containing the Pi-hole configuration.

update_config(config, restart=True)[source]

Update Pi-hole configuration.

Parameters:

  • config (dict[str, Any]) – Configuration dictionary with settings to update.

  • restart (bool) – Whether to restart FTL after the change (defaults to True).

Return type:

dict[str, Any]

Returns:

Dictionary containing the updated configuration.

add_config_item(element, value, restart=True)[source]

Add an item to a configuration array.

Parameters:

  • element (str) – Configuration element path (e.g., ‘dns/upstreams’).

  • value (str) – Value to add to the configuration array.

  • restart (bool) – Whether to restart FTL after the change (defaults to True).

Return type:

bool

Returns:

True if the item was successfully added.

remove_config_item(element, value, restart=True)[source]

Remove an item from a configuration array.

Parameters:

  • element (str) – Configuration element path (e.g., ‘dns/upstreams’).

  • value (str) – Value to remove from the configuration array.

  • restart (bool) – Whether to restart FTL after the change (defaults to True).

Return type:

bool

Returns:

True if the item was successfully removed.

pihole_lib.dhcp module

Pi-hole DHCP management.

class pihole_lib.dhcp.PiHoleDHCP(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole DHCP management client.

Provides methods to interact with Pi-hole’s DHCP functionality.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get active DHCP leases
    leases = client.dhcp.get_leases()
    for lease in leases.leases:
        print(f"{lease.name} ({lease.ip}) - {lease.hwaddr}")

    # Delete a lease
    client.dhcp.delete_lease("192.168.1.100")
BASE_URL: str = '/api/dhcp'
get_leases()[source]

Get currently active DHCP leases.

Return type:

DHCPLeasesInfo

Returns:

DHCPLeasesInfo containing active lease information.

delete_lease(ip)[source]

Delete a currently active DHCP lease.

Parameters:

ip (str) – IP address of the lease to delete.

Return type:

bool

Returns:

True if the lease was successfully deleted.

pihole_lib.dns module

Pi-hole DNS management.

class pihole_lib.dns.PiHoleDNS(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole DNS management client.

Provides methods to manage custom DNS records, retrieve DNS configuration, and control DNS blocking status.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get DNS configuration
    config = client.dns.get_config()
    print(f"Upstream servers: {config.upstreams}")

    # Manage DNS records
    client.dns.add_a_record("server.local", "192.168.1.100")
    client.dns.add_cname_record("www.local", "server.local")

    # Control blocking
    client.dns.disable_blocking(timer=300)  # 5 minutes
    client.dns.enable_blocking()
BASE_URL: str = '/api/dns'
CONFIG_URL = '/api/config/dns'
get_config()[source]

Get Pi-hole DNS configuration.

Return type:

DNSConfig

Returns:

DNSConfig with upstream servers, custom records, and settings.

get_records(record_type=None)[source]

Get all custom DNS records.

Parameters:

record_type (Optional[str]) – Filter by “A” or “CNAME”, or None for all records.

Return type:

list[DNSRecord]

Returns:

List of DNSRecord objects.

Raises:

ValueError – If an invalid record type is specified.

add_a_record(domain, ip)[source]

Add a custom A record.

Parameters:

  • domain (str) – Domain name (e.g., “server.local”).

  • ip (str) – IPv4 address (e.g., “192.168.1.100”).

Return type:

bool

Returns:

True if the record was added successfully.

remove_a_record(domain, ip)[source]

Remove a custom A record.

Parameters:

  • domain (str) – Domain name of the record to remove.

  • ip (str) – IPv4 address of the record to remove.

Return type:

bool

Returns:

True if the record was removed successfully.

add_cname_record(domain, target)[source]

Add a custom CNAME record.

Parameters:

  • domain (str) – Source domain name (the alias).

  • target (str) – Target domain name.

Return type:

bool

Returns:

True if the record was added successfully.

remove_cname_record(domain, target)[source]

Remove a custom CNAME record.

Parameters:

  • domain (str) – Source domain name of the record to remove.

  • target (str) – Target domain name of the record to remove.

Return type:

bool

Returns:

True if the record was removed successfully.

get_blocking_status()[source]

Get DNS blocking status.

Return type:

DNSBlockingStatus

Returns:

DNSBlockingStatus with current blocking state and timer info.

set_blocking_status(blocking=True, timer=None)[source]

Change DNS blocking status.

Parameters:

  • blocking (bool) – Whether to enable (True) or disable (False) blocking.

  • timer (Optional[int]) – Optional timer in seconds. Status reverts after timer expires.

Return type:

DNSBlockingStatus

Returns:

DNSBlockingStatus with updated state.

enable_blocking(timer=None)[source]

Enable DNS blocking.

Parameters:

timer (Optional[int]) – Optional timer in seconds to auto-disable after.

Return type:

DNSBlockingStatus

Returns:

DNSBlockingStatus with updated state.

disable_blocking(timer=None)[source]

Disable DNS blocking.

Parameters:

timer (Optional[int]) – Optional timer in seconds to auto-enable after.

Return type:

DNSBlockingStatus

Returns:

DNSBlockingStatus with updated state.

pihole_lib.domains module

Pi-hole domain management operations.

class pihole_lib.domains.PiHoleDomains(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole domain management operations.

This class provides methods to manage domains on your Pi-hole instance, including adding, updating, deleting, and retrieving domains with various filtering options.

Examples:

from pihole_lib import PiHoleClient, DomainType, DomainKind

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    domains = client.domains

    # Get all domains
    all_domains = domains.get_domains()

    # Get only allowed domains
    allowed_domains = domains.get_domains(domain_type=DomainType.ALLOW)

    # Get specific domain
    domain = domains.get_domain("example.com", DomainType.ALLOW, DomainKind.EXACT)

    # Add a new domain
    result = domains.add_domain(
        domain="badsite.com",
        domain_type=DomainType.DENY,
        domain_kind=DomainKind.EXACT,
        comment="Blocked site",
        groups=[0],
        enabled=True
    )

    # Update a domain
    updated = domains.update_domain(
        domain="example.com",
        domain_type=DomainType.ALLOW,
        domain_kind=DomainKind.EXACT,
        comment="Updated comment",
        enabled=False
    )

    # Delete a domain
    domains.delete_domain("badsite.com", DomainType.DENY, DomainKind.EXACT)

    # Batch delete domains
    domains.batch_delete_domains([
        DomainBatchDeleteItem(
            item="site1.com",
            type=DomainType.DENY,
            kind=DomainKind.EXACT
        ),
        DomainBatchDeleteItem(
            item="site2.com",
            type=DomainType.DENY,
            kind=DomainKind.EXACT
        )
    ])
BASE_URL: str = '/api/domains'
get_domains(domain_type=None, domain_kind=None, domain=None)[source]

Get domains with optional filtering.

Parameters:
Return type:

list[Domain]

Returns:

List of Domain objects matching the filters.

Raises:

Examples:

# Get all domains
all_domains = domains.get_domains()

# Get only allowed domains
allowed = domains.get_domains(domain_type=DomainType.ALLOW)

# Get only exact domains
exact = domains.get_domains(domain_kind=DomainKind.EXACT)

# Get specific domain across all types/kinds
specific = domains.get_domains(domain="example.com")

# Get allowed exact domains
allowed_exact = domains.get_domains(
    domain_type=DomainType.ALLOW,
    domain_kind=DomainKind.EXACT
)
get_domain(domain, domain_type, domain_kind)[source]

Get a specific domain by exact match.

Parameters:

  • domain (str) – The domain name to retrieve.

  • domain_type (DomainType) – Type of domain (allow/deny).

  • domain_kind (DomainKind) – Kind of domain (exact/regex).

Return type:

Domain | None

Returns:

Domain object if found, None otherwise.

Raises:

Examples:

# Get specific allowed exact domain
domain = domains.get_domain(
    "example.com",
    DomainType.ALLOW,
    DomainKind.EXACT
)

if domain:
    print(f"Found domain: {domain.domain}")
else:
    print("Domain not found")
add_domain(domain, domain_type, domain_kind, comment=None, groups=None, enabled=True)[source]

Add a new domain.

Parameters:

  • domain (str) – The domain name or regex pattern to add.

  • domain_type (DomainType) – Type of domain (allow/deny).

  • domain_kind (DomainKind) – Kind of domain (exact/regex).

  • comment (Optional[str]) – Optional comment for the domain.

  • groups (Optional[list[int]]) – List of group IDs. Defaults to [0] if not provided.

  • enabled (bool) – Whether the domain is enabled. Defaults to True.

Return type:

DomainMutationResponse

Returns:

DomainMutationResponse with the operation results.

Raises:

Examples:

# Add an exact blocked domain
result = domains.add_domain(
    domain="badsite.com",
    domain_type=DomainType.DENY,
    domain_kind=DomainKind.EXACT,
    comment="Malicious site",
    groups=[0, 1],
    enabled=True
)

# Add a regex pattern
result = domains.add_domain(
    domain=r".*\.ads\..*",
    domain_type=DomainType.DENY,
    domain_kind=DomainKind.REGEX,
    comment="Block ads subdomains"
)
update_domain(domain, domain_type, domain_kind, new_type=None, new_kind=None, comment=None, groups=None, enabled=None)[source]

Update an existing domain.

Parameters:

  • domain (str) – The domain name to update.

  • domain_type (DomainType) – Current type of domain (allow/deny).

  • domain_kind (DomainKind) – Current kind of domain (exact/regex).

  • new_type (Optional[DomainType]) – New type to move domain to (optional).

  • new_kind (Optional[DomainKind]) – New kind to move domain to (optional).

  • comment (Optional[str]) – New comment for the domain.

  • groups (Optional[list[int]]) – New list of group IDs.

  • enabled (Optional[bool]) – New enabled status.

Return type:

DomainMutationResponse

Returns:

DomainMutationResponse with the operation results.

Raises:

Examples:

# Update domain comment and disable it
result = domains.update_domain(
    domain="example.com",
    domain_type=DomainType.ALLOW,
    domain_kind=DomainKind.EXACT,
    comment="Updated comment",
    enabled=False
)

# Move domain from allow to deny
result = domains.update_domain(
    domain="example.com",
    domain_type=DomainType.ALLOW,
    domain_kind=DomainKind.EXACT,
    new_type=DomainType.DENY,
    new_kind=DomainKind.EXACT
)
delete_domain(domain, domain_type, domain_kind)[source]

Delete a domain.

Parameters:

  • domain (str) – The domain name to delete.

  • domain_type (DomainType) – Type of domain (allow/deny).

  • domain_kind (DomainKind) – Kind of domain (exact/regex).

Raises:
Return type:

None

Examples:

# Delete an exact blocked domain
domains.delete_domain(
    "badsite.com",
    DomainType.DENY,
    DomainKind.EXACT
)

# Delete a regex pattern
domains.delete_domain(
    r".*\.ads\..*",
    DomainType.DENY,
    DomainKind.REGEX
)
batch_delete_domains(domains)[source]

Delete multiple domains in a single request.

Parameters:

domains (list[DomainBatchDeleteItem]) – List of DomainBatchDeleteItem objects specifying domains to delete.

Return type:

bool

Returns:

True if successful.

Raises:

Examples:

# Delete multiple domains
success = domains.batch_delete_domains([
    DomainBatchDeleteItem(
        item="site1.com",
        type=DomainType.DENY,
        kind=DomainKind.EXACT
    ),
    DomainBatchDeleteItem(
        item="site2.com",
        type=DomainType.DENY,
        kind=DomainKind.EXACT
    ),
    DomainBatchDeleteItem(
        item=r".*\.ads\..*",
        type=DomainType.DENY,
        kind=DomainKind.REGEX
    )
])
print(f"Batch delete successful: {success}")

pihole_lib.exceptions module

Exceptions for Pi-hole API interactions.

exception pihole_lib.exceptions.PiHoleAPIError(message, status_code=None)[source]

Bases: Exception

Base exception for Pi-hole API errors.

message

Error description.

status_code

HTTP status code if available.

__init__(message, status_code=None)[source]

Initialize API error.

Parameters:

  • message (str) – Error description.

  • status_code (Optional[int]) – HTTP status code if available.

exception pihole_lib.exceptions.PiHoleConnectionError(message, status_code=None)[source]

Bases: PiHoleAPIError

Connection-related error.

exception pihole_lib.exceptions.PiHoleAuthenticationError(message, status_code=None)[source]

Bases: PiHoleAPIError

Authentication-related error.

exception pihole_lib.exceptions.PiHoleServerError(message, status_code=None)[source]

Bases: PiHoleAPIError

Server-side error.

pihole_lib.groups module

Pi-hole Groups management.

class pihole_lib.groups.PiHoleGroups(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole Groups management client.

Provides methods to create, read, update, and delete groups.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get all groups
    all_groups = client.groups.get_groups()
    for group in all_groups:
        print(f"Group: {group.name}")

    # Create a new group
    client.groups.create_group(name="family_devices", comment="Family")

    # Delete a group
    client.groups.delete_group("family_devices")
BASE_URL: str = '/api/groups'
get_groups(name=None)[source]

Get groups from Pi-hole.

Parameters:

name (Optional[str]) – Optional group name to filter by.

Return type:

list[Group]

Returns:

List of Group objects.

create_group(name, comment=None, enabled=True)[source]

Create a new group.

Parameters:

  • name (str) – Group name.

  • comment (Optional[str]) – Optional comment for the group.

  • enabled (bool) – Whether the group should be enabled. Defaults to True.

Return type:

list[Group]

Returns:

List of Group objects returned by the API.

update_group(name, new_name=None, comment=None, enabled=True)[source]

Update an existing group.

Parameters:

  • name (str) – Current name of the group to update.

  • new_name (Optional[str]) – New name for the group. If None, keeps current name.

  • comment (Optional[str]) – New comment for the group.

  • enabled (bool) – Whether the group should be enabled.

Return type:

GroupsResponse

Returns:

GroupsResponse containing the updated group.

delete_group(name)[source]

Delete a group.

Parameters:

name (str) – Name of the group to delete.

Return type:

bool

Returns:

True if the group was deleted successfully.

pihole_lib.info module

Pi-hole Info API client.

class pihole_lib.info.PiHoleInfo(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole Info API client.

Handles information endpoints for system status and diagnostics.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get login info
    login_info = client.info.get_login_info()
    print(f"DNS running: {login_info.dns}")

    # Get system info
    system_info = client.info.get_system_info()
    print(f"Uptime: {system_info.system.uptime}s")

    # Get version info
    version = client.info.get_version_info()
    print(f"Pi-hole: {version.version.core.local.version}")
BASE_URL: str = '/api/info'
get_login_info()[source]

Get login page related information.

Return type:

LoginInfo

Returns:

LoginInfo with HTTPS port and DNS status.

get_client_info()[source]

Get client request information.

Return type:

ClientInfo

Returns:

ClientInfo with remote address, HTTP version, method, and headers.

get_database_info()[source]

Get database information.

Return type:

DatabaseInfo

Returns:

DatabaseInfo with file size, permissions, query counts, etc.

get_ftl_info()[source]

Get FTL runtime information.

Return type:

FTLInfo

Returns:

FTLInfo with database stats, process info, and resource usage.

get_host_info()[source]

Get host system information.

Return type:

HostInfo

Returns:

HostInfo with uname details, hardware model, and DMI data.

get_version_info()[source]

Get Pi-hole version information.

Return type:

VersionInfo

Returns:

VersionInfo for all Pi-hole components.

get_system_info()[source]

Get system resource information.

Return type:

SystemInfo

Returns:

SystemInfo with uptime, memory, CPU, and FTL resource usage.

get_messages()[source]

Get system messages.

Return type:

MessagesInfo

Returns:

MessagesInfo with diagnosis messages.

get_messages_count()[source]

Get system messages count.

Return type:

MessagesCountInfo

Returns:

MessagesCountInfo with message count.

pihole_lib.lists module

Pi-hole Lists API client.

class pihole_lib.lists.PiHoleLists(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole Lists API client.

Handles domain list operations for blocklists and allowlists.

Examples:

from pihole_lib import PiHoleClient, ListType

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get all lists
    all_lists = client.lists.get_lists()

    # Add a blocklist
    client.lists.add_list(
        address="https://example.com/domains.txt",
        list_type=ListType.BLOCK,
        comment="Ad servers"
    )

    # Search for domains
    results = client.lists.search_domains("example.com")
BASE_URL: str = '/api/lists'
get_lists(list_name=None, list_type=None)[source]

Get Pi-hole domain lists.

Parameters:

  • list_name (Optional[str]) – Optional specific list name to retrieve.

  • list_type (Optional[ListType]) – Optional list type filter (allow or block).

Return type:

list[PiHoleList]

Returns:

List of PiHoleList objects.

add_list(address, list_type, comment=None, groups=None, enabled=True)[source]

Add a new domain list to Pi-hole.

Parameters:

  • address (str) – Address of the list.

  • list_type (ListType) – Type of list (ALLOW or BLOCK).

  • comment (Optional[str]) – Optional comment for this list.

  • groups (Optional[list[int]]) – Group IDs to assign (defaults to [0]).

  • enabled (bool) – Whether the list should be enabled (defaults to True).

Return type:

list[PiHoleList]

Returns:

List of PiHoleList objects containing the created list.

delete_list(address, list_type)[source]

Delete a domain list from Pi-hole.

Parameters:

  • address (str) – Address of the list to delete.

  • list_type (ListType) – Type of list (ALLOW or BLOCK).

Return type:

bool

Returns:

True if the list was successfully deleted.

batch_delete_lists(items)[source]

Delete multiple domain lists from Pi-hole.

Parameters:

items (list[BatchDeleteItem]) – List of BatchDeleteItem objects specifying lists to delete.

Return type:

bool

Returns:

True if all lists were successfully deleted.

update_list(address, list_type, comment=None, groups=None, enabled=True)[source]

Update an existing domain list in Pi-hole.

Parameters:

  • address (str) – Address of the list to update.

  • list_type (ListType) – Type of list (ALLOW or BLOCK).

  • comment (Optional[str]) – Optional comment for this list.

  • groups (Optional[list[int]]) – Group IDs to assign (defaults to [0]).

  • enabled (bool) – Whether the list should be enabled (defaults to True).

Return type:

ListsResponse

Returns:

ListsResponse with the updated list and processing results.

search_domains(domain, partial=False, max_results=20, debug=False)[source]

Search for domains in Pi-hole’s lists.

Parameters:

  • domain (str) – Domain (or part of domain) to search for.

  • partial (bool) – Whether to enable partial matching (defaults to False).

  • max_results (int) – Maximum number of results (defaults to 20).

  • debug (bool) – Whether to include debug information (defaults to False).

Return type:

SearchResponse

Returns:

SearchResponse with search results and metadata.

pihole_lib.network module

Pi-hole network API client.

class pihole_lib.network.PiHoleNetwork(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole network API client.

Provides methods to gather network information as seen by Pi-hole.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get network devices
    devices = client.network.get_devices()
    for device in devices.devices:
        print(f"{device.name}: {device.hwaddr}")

    # Get gateway info
    gateway = client.network.get_gateway()

    # Get interfaces
    interfaces = client.network.get_interfaces()
BASE_URL: str = '/api/network'
get_devices(max_devices=None, max_addresses=None)[source]

Get info about devices in your local network.

Parameters:

  • max_devices (Optional[int]) – Maximum number of devices to show (optional).

  • max_addresses (Optional[int]) – Maximum addresses per device (optional).

Return type:

NetworkDevicesResponse

Returns:

NetworkDevicesResponse containing device information.

get_gateway(detailed=False)[source]

Get info about the gateway.

Parameters:

detailed (bool) – If True, include detailed interface and route info.

Return type:

NetworkGatewayResponse | NetworkGatewayDetailedResponse

Returns:

NetworkGatewayResponse or NetworkGatewayDetailedResponse.

get_interfaces(detailed=False)[source]

Get info about network interfaces.

Parameters:

detailed (bool) – If True, include more detailed information.

Return type:

NetworkInterfacesResponse

Returns:

NetworkInterfacesResponse containing interface information.

get_routes(detailed=False)[source]

Get info about network routes.

Parameters:

detailed (bool) – If True, include more detailed information.

Return type:

NetworkRoutesResponse

Returns:

NetworkRoutesResponse containing route information.

delete_device(device_id)[source]

Delete a device from the network table.

Parameters:

device_id (int) – Device ID to delete.

Return type:

NetworkDeviceDeleteResponse

Returns:

NetworkDeviceDeleteResponse containing operation result.

pihole_lib.padd module

Pi-hole PADD (Pi-hole API Dashboard Data) management.

class pihole_lib.padd.PiHolePADD(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole PADD (Pi-hole API Dashboard Data) client.

Provides comprehensive dashboard data including statistics, system information, network details, and configuration summaries.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    dashboard = client.padd.get_dashboard_data()
    print(f"Active clients: {dashboard.active_clients}")
    print(f"Total queries: {dashboard.queries.total}")
    print(f"Blocked: {dashboard.queries.blocked}")
BASE_URL: str = '/api/padd'
get_dashboard_data()[source]

Get comprehensive Pi-hole dashboard data.

Return type:

PADDInfo

Returns:

PADDInfo with statistics, system info, network details, and config.

pihole_lib.stats module

Pi-hole Stats API client.

class pihole_lib.stats.PiHoleStats(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole Stats API client.

Handles statistics and history endpoints for Pi-hole data analysis.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get activity history
    history = client.stats.get_history()

    # Get summary
    summary = client.stats.get_summary()
    print(f"Total queries: {summary.queries.total}")

    # Get top domains
    top_domains = client.stats.get_top_domains(count=10)
BASE_URL: str = '/api'
get_history()[source]

Get activity graph data.

Return type:

HistoryResponse

Returns:

HistoryResponse with timestamps and query counts.

get_client_history()[source]

Get per-client activity graph data.

Return type:

ClientHistoryResponse

Returns:

ClientHistoryResponse with per-client activity data.

get_database_history(from_timestamp, until_timestamp)[source]

Get activity graph data from long-term database.

Parameters:

  • from_timestamp (int) – Unix timestamp from when to request data.

  • until_timestamp (int) – Unix timestamp until when to request data.

Return type:

DatabaseHistoryResponse

Returns:

DatabaseHistoryResponse with long-term activity data.

get_database_client_history(from_timestamp, until_timestamp)[source]

Get per-client activity data from long-term database.

Parameters:

  • from_timestamp (int) – Unix timestamp from when to request data.

  • until_timestamp (int) – Unix timestamp until when to request data.

Return type:

DatabaseClientHistoryResponse

Returns:

DatabaseClientHistoryResponse with long-term per-client data.

get_queries(length=100, cursor=None, from_timestamp=None, until_timestamp=None, upstream=None, domain=None, client=None)[source]

Get query details with optional filtering.

Parameters:

  • length (int) – Number of queries to return (default: 100).

  • cursor (Optional[int]) – Cursor for pagination (optional).

  • from_timestamp (Optional[int]) – Only show queries from this timestamp (optional).

  • until_timestamp (Optional[int]) – Only show queries until this timestamp (optional).

  • upstream (Optional[str]) – Filter by specific upstream (optional).

  • domain (Optional[str]) – Filter by specific domain (optional).

  • client (Optional[str]) – Filter by specific client (optional).

Return type:

QueriesResponse

Returns:

QueriesResponse with query details and pagination info.

get_query_suggestions()[source]

Get query filter suggestions.

Return type:

QuerySuggestionsResponse

Returns:

QuerySuggestionsResponse with available filter suggestions.

get_query_types()[source]

Get query types statistics.

Return type:

QueryTypesResponse

Returns:

QueryTypesResponse with query types and counts.

get_recent_blocked(count=10)[source]

Get most recently blocked domains.

Parameters:

count (int) – Number of blocked domains to return (default: 10).

Return type:

RecentBlockedResponse

Returns:

RecentBlockedResponse with recently blocked domains.

get_summary()[source]

Get overview of Pi-hole activity.

Return type:

SummaryResponse

Returns:

SummaryResponse with comprehensive activity summary.

get_top_clients(blocked=None, count=10)[source]

Get top clients by query count.

Parameters:

  • blocked (Optional[bool]) – Filter by permitted (False) or blocked (True) queries.

  • count (int) – Number of clients to return (default: 10).

Return type:

TopClientsResponse

Returns:

TopClientsResponse with top clients and query counts.

get_top_domains(blocked=None, count=10)[source]

Get top domains by query count.

Parameters:

  • blocked (Optional[bool]) – Filter by permitted (False) or blocked (True) queries.

  • count (int) – Number of domains to return (default: 10).

Return type:

TopDomainsResponse

Returns:

TopDomainsResponse with top domains and query counts.

get_upstreams()[source]

Get metrics about upstream destinations.

Return type:

UpstreamsResponse

Returns:

UpstreamsResponse with upstream server metrics.

get_database_query_types(from_timestamp, until_timestamp)[source]

Get query types from long-term database.

Parameters:

  • from_timestamp (int) – Unix timestamp from when to request data.

  • until_timestamp (int) – Unix timestamp until when to request data.

Return type:

QueryTypesResponse

Returns:

QueryTypesResponse with query types for the time range.

get_database_summary(from_timestamp, until_timestamp)[source]

Get database content details for a time range.

Parameters:

  • from_timestamp (int) – Unix timestamp from when to request data.

  • until_timestamp (int) – Unix timestamp until when to request data.

Return type:

DatabaseSummaryResponse

Returns:

DatabaseSummaryResponse with summary statistics.

get_database_top_clients(from_timestamp, until_timestamp)[source]

Get top clients from long-term database.

Parameters:

  • from_timestamp (int) – Unix timestamp from when to request data.

  • until_timestamp (int) – Unix timestamp until when to request data.

Return type:

TopClientsResponse

Returns:

TopClientsResponse with top clients for the time range.

get_database_top_domains(from_timestamp, until_timestamp)[source]

Get top domains from long-term database.

Parameters:

  • from_timestamp (int) – Unix timestamp from when to request data.

  • until_timestamp (int) – Unix timestamp until when to request data.

Return type:

TopDomainsResponse

Returns:

TopDomainsResponse with top domains for the time range.

get_database_upstreams(from_timestamp, until_timestamp)[source]

Get upstream metrics from long-term database.

Parameters:

  • from_timestamp (int) – Unix timestamp from when to request data.

  • until_timestamp (int) – Unix timestamp until when to request data.

Return type:

UpstreamsResponse

Returns:

UpstreamsResponse with upstream metrics for the time range.

pihole_lib.utils module

Utility functions for Pi-hole API interactions.

pihole_lib.utils.handle_pihole_response(response)[source]

Handle Pi-hole API response and raise appropriate exceptions.

Parameters:

response (Response) – The HTTP response from Pi-hole API.

Raises:
Return type:

None

pihole_lib.utils.make_pihole_request(client, method, endpoint, json=None, files=None, params=None, stream=False)[source]

Make a request to Pi-hole API with error handling.

Parameters:

  • client (PiHoleClient) – The PiHoleClient instance to use for the request.

  • method (str) – HTTP method (GET, POST, etc.).

  • endpoint (str) – The API endpoint path (e.g., “/api/info/login”).

  • json (Union[dict[str, Any], list[dict[str, Any]], None]) – Optional JSON data to send in the request body.

  • files (Optional[dict[str, Any]]) – Optional files to upload.

  • params (Optional[dict[str, Any]]) – Optional query parameters to include in the URL.

  • stream (bool) – Whether to stream the response. Defaults to False.

Return type:

Response

Returns:

The HTTP response object.

Raises:
pihole_lib.utils.check_api_errors(response_data, item_name, operation='process')[source]

Check for API errors in the response and raise appropriate exceptions.

Parameters:

  • response_data (dict) – The response data from the API.

  • item_name (str) – The item name that was being processed.

  • operation (str) – The operation being performed (e.g., “create”, “add”).

Raises:

PiHoleServerError – If Pi-hole reports an error.

Return type:

None

Module contents

Pi-hole API Python Library.

A Python library for interacting with Pi-hole through its API. Handles authentication and session management.

class pihole_lib.PiHoleClient(base_url, password, timeout=30, verify_ssl=True)[source]

Bases: object

Pi-hole API client.

Handles authentication and session management for Pi-hole API interactions. Can be used as a context manager for automatic cleanup.

Examples:

# Basic usage with property access
with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get system information
    login_info = client.info.get_login_info()

    # Perform actions
    for line in client.actions.update_gravity():
        print(line.strip())

    # Manage lists
    all_lists = client.lists.get_lists()

    # Configuration management
    current_config = client.config.get_config()

# Alternative usage with explicit class imports
from pihole_lib import PiHoleInfo, PiHoleActions

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    info = PiHoleInfo(client)
    actions = PiHoleActions(client)
DEFAULT_TIMEOUT = 30
HEADER_SESSION_ID = 'X-FTL-SID'
__init__(base_url, password, timeout=30, verify_ssl=True)[source]

Initialize a Pi-hole client.

Parameters:

  • base_url (str) – Pi-hole base URL (e.g., “http://192.168.1.100”).

  • password (str) – Pi-hole admin password.

  • timeout (int | None) – Request timeout in seconds. Defaults to 30.

  • verify_ssl (bool) – Whether to verify SSL certificates. Defaults to True.

__enter__()[source]

Enter context manager and authenticate.

Return type:

PiHoleClient

__exit__(exc_type, exc_val, exc_tb)[source]

Exit context manager and clean up resources.

Return type:

None

close()[source]

Close session and clean up resources.

Return type:

None

is_authenticated()[source]

Check if client is authenticated.

Return type:

bool

get_session_id()[source]

Get current session ID.

Return type:

str | None

property info: PiHoleInfo

Get Pi-hole info API client.

property actions: PiHoleActions

Get Pi-hole actions API client.

property backup: PiHoleBackup

Get Pi-hole backup API client.

property config: PiHoleConfig

Get Pi-hole config API client.

property dhcp: PiHoleDHCP

Get Pi-hole DHCP API client.

property dns: PiHoleDNS

Get Pi-hole DNS API client.

property lists: PiHoleLists

Get Pi-hole lists API client.

property groups: PiHoleGroups

Get Pi-hole groups API client.

property padd: PiHolePADD

Get Pi-hole PADD API client.

property stats: PiHoleStats

Get Pi-hole stats API client.

property domains: PiHoleDomains

Get Pi-hole domains API client.

property network: PiHoleNetwork

Get Pi-hole network API client.

property clients: PiHoleClients

Get Pi-hole clients API client.

class pihole_lib.PiHoleInfo(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole Info API client.

Handles information endpoints for system status and diagnostics.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get login info
    login_info = client.info.get_login_info()
    print(f"DNS running: {login_info.dns}")

    # Get system info
    system_info = client.info.get_system_info()
    print(f"Uptime: {system_info.system.uptime}s")

    # Get version info
    version = client.info.get_version_info()
    print(f"Pi-hole: {version.version.core.local.version}")
BASE_URL: str = '/api/info'
get_login_info()[source]

Get login page related information.

Return type:

LoginInfo

Returns:

LoginInfo with HTTPS port and DNS status.

get_client_info()[source]

Get client request information.

Return type:

ClientInfo

Returns:

ClientInfo with remote address, HTTP version, method, and headers.

get_database_info()[source]

Get database information.

Return type:

DatabaseInfo

Returns:

DatabaseInfo with file size, permissions, query counts, etc.

get_ftl_info()[source]

Get FTL runtime information.

Return type:

FTLInfo

Returns:

FTLInfo with database stats, process info, and resource usage.

get_host_info()[source]

Get host system information.

Return type:

HostInfo

Returns:

HostInfo with uname details, hardware model, and DMI data.

get_version_info()[source]

Get Pi-hole version information.

Return type:

VersionInfo

Returns:

VersionInfo for all Pi-hole components.

get_system_info()[source]

Get system resource information.

Return type:

SystemInfo

Returns:

SystemInfo with uptime, memory, CPU, and FTL resource usage.

get_messages()[source]

Get system messages.

Return type:

MessagesInfo

Returns:

MessagesInfo with diagnosis messages.

get_messages_count()[source]

Get system messages count.

Return type:

MessagesCountInfo

Returns:

MessagesCountInfo with message count.

class pihole_lib.PiHoleBackup(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole Backup API client.

Handles backup and restore operations using the Teleporter endpoint.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Export backup
    backup_file = client.backup.export_backup("/path/to/backups")
    print(f"Backup saved to: {backup_file}")

    # Import backup
    imported_files = client.backup.import_backup("/path/to/backup.zip")
    print(f"Imported {len(imported_files)} files")
BASE_URL: str = '/api/teleporter'
export_backup(backup_dir)[source]

Export Pi-hole settings to a backup file.

Parameters:

backup_dir (str) – Directory where the backup file should be saved.

Return type:

str

Returns:

The full path to the created backup file.

import_backup(file_path, import_options=None)[source]

Import Pi-hole settings from a backup file.

Note: This will overwrite your current configuration and restart Pi-hole.

Parameters:

  • file_path (str) – Full path to the backup ZIP file to import.

  • import_options (Optional[TeleporterImportOptions]) – Options specifying which elements to restore. If None, all items will be restored.

Return type:

list[str]

Returns:

List of imported backup files/components.

class pihole_lib.PiHoleLists(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole Lists API client.

Handles domain list operations for blocklists and allowlists.

Examples:

from pihole_lib import PiHoleClient, ListType

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get all lists
    all_lists = client.lists.get_lists()

    # Add a blocklist
    client.lists.add_list(
        address="https://example.com/domains.txt",
        list_type=ListType.BLOCK,
        comment="Ad servers"
    )

    # Search for domains
    results = client.lists.search_domains("example.com")
BASE_URL: str = '/api/lists'
get_lists(list_name=None, list_type=None)[source]

Get Pi-hole domain lists.

Parameters:

  • list_name (Optional[str]) – Optional specific list name to retrieve.

  • list_type (Optional[ListType]) – Optional list type filter (allow or block).

Return type:

list[PiHoleList]

Returns:

List of PiHoleList objects.

add_list(address, list_type, comment=None, groups=None, enabled=True)[source]

Add a new domain list to Pi-hole.

Parameters:

  • address (str) – Address of the list.

  • list_type (ListType) – Type of list (ALLOW or BLOCK).

  • comment (Optional[str]) – Optional comment for this list.

  • groups (Optional[list[int]]) – Group IDs to assign (defaults to [0]).

  • enabled (bool) – Whether the list should be enabled (defaults to True).

Return type:

list[PiHoleList]

Returns:

List of PiHoleList objects containing the created list.

delete_list(address, list_type)[source]

Delete a domain list from Pi-hole.

Parameters:

  • address (str) – Address of the list to delete.

  • list_type (ListType) – Type of list (ALLOW or BLOCK).

Return type:

bool

Returns:

True if the list was successfully deleted.

batch_delete_lists(items)[source]

Delete multiple domain lists from Pi-hole.

Parameters:

items (list[BatchDeleteItem]) – List of BatchDeleteItem objects specifying lists to delete.

Return type:

bool

Returns:

True if all lists were successfully deleted.

update_list(address, list_type, comment=None, groups=None, enabled=True)[source]

Update an existing domain list in Pi-hole.

Parameters:

  • address (str) – Address of the list to update.

  • list_type (ListType) – Type of list (ALLOW or BLOCK).

  • comment (Optional[str]) – Optional comment for this list.

  • groups (Optional[list[int]]) – Group IDs to assign (defaults to [0]).

  • enabled (bool) – Whether the list should be enabled (defaults to True).

Return type:

ListsResponse

Returns:

ListsResponse with the updated list and processing results.

search_domains(domain, partial=False, max_results=20, debug=False)[source]

Search for domains in Pi-hole’s lists.

Parameters:

  • domain (str) – Domain (or part of domain) to search for.

  • partial (bool) – Whether to enable partial matching (defaults to False).

  • max_results (int) – Maximum number of results (defaults to 20).

  • debug (bool) – Whether to include debug information (defaults to False).

Return type:

SearchResponse

Returns:

SearchResponse with search results and metadata.

class pihole_lib.PiHoleActions(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole Actions API client.

Handles action endpoints that perform operations on Pi-hole.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Update gravity database with streaming output
    for line in client.actions.update_gravity():
        print(line.strip())

    # Restart DNS service
    if client.actions.restart_dns():
        print("DNS restarted successfully")
BASE_URL: str = '/api/action'
update_gravity(color=False)[source]

Update Pi-hole’s gravity database (adlists).

Triggers Pi-hole’s gravity update process, which downloads and processes all configured adlists. The output is streamed with chunked encoding.

Parameters:

color (bool) – Include ANSI color escape codes in output. Defaults to False.

Yields:

Lines of output from the gravity update process.

Return type:

Iterator[str]

restart_dns()[source]

Restart Pi-hole’s DNS service (pihole-FTL).

Return type:

bool

Returns:

True if the restart was successful.

flush_logs()[source]

Flush Pi-hole’s DNS logs.

Empties the DNS log file and purges the most recent 24 hours from both the database and FTL’s internal memory.

Return type:

bool

Returns:

True if the flush was successful.

flush_network()[source]

Flush Pi-hole’s network table.

Removes all known devices and their associated addresses.

Return type:

bool

Returns:

True if the flush was successful.

class pihole_lib.PiHoleConfig(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole Config API client.

Handles configuration endpoints for Pi-hole settings.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get current configuration
    config = client.config.get_config()
    print(f"DNS upstreams: {config['dns']['upstreams']}")

    # Update configuration
    client.config.update_config({"dns": {"upstreams": ["1.1.1.1"]}})

    # Add/remove config items
    client.config.add_config_item("dns/upstreams", "8.8.8.8")
    client.config.remove_config_item("dns/upstreams", "8.8.8.8")
BASE_URL: str = '/api/config'
get_config(element=None, detailed=True)[source]

Get Pi-hole configuration.

Parameters:

  • element (Optional[str]) – Optional configuration element path (e.g., ‘dns’, ‘dhcp’). If None, returns the complete configuration.

  • detailed (bool) – Return detailed information (defaults to True).

Return type:

dict[str, Any]

Returns:

Dictionary containing the Pi-hole configuration.

update_config(config, restart=True)[source]

Update Pi-hole configuration.

Parameters:

  • config (dict[str, Any]) – Configuration dictionary with settings to update.

  • restart (bool) – Whether to restart FTL after the change (defaults to True).

Return type:

dict[str, Any]

Returns:

Dictionary containing the updated configuration.

add_config_item(element, value, restart=True)[source]

Add an item to a configuration array.

Parameters:

  • element (str) – Configuration element path (e.g., ‘dns/upstreams’).

  • value (str) – Value to add to the configuration array.

  • restart (bool) – Whether to restart FTL after the change (defaults to True).

Return type:

bool

Returns:

True if the item was successfully added.

remove_config_item(element, value, restart=True)[source]

Remove an item from a configuration array.

Parameters:

  • element (str) – Configuration element path (e.g., ‘dns/upstreams’).

  • value (str) – Value to remove from the configuration array.

  • restart (bool) – Whether to restart FTL after the change (defaults to True).

Return type:

bool

Returns:

True if the item was successfully removed.

class pihole_lib.PiHoleDHCP(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole DHCP management client.

Provides methods to interact with Pi-hole’s DHCP functionality.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get active DHCP leases
    leases = client.dhcp.get_leases()
    for lease in leases.leases:
        print(f"{lease.name} ({lease.ip}) - {lease.hwaddr}")

    # Delete a lease
    client.dhcp.delete_lease("192.168.1.100")
BASE_URL: str = '/api/dhcp'
get_leases()[source]

Get currently active DHCP leases.

Return type:

DHCPLeasesInfo

Returns:

DHCPLeasesInfo containing active lease information.

delete_lease(ip)[source]

Delete a currently active DHCP lease.

Parameters:

ip (str) – IP address of the lease to delete.

Return type:

bool

Returns:

True if the lease was successfully deleted.

class pihole_lib.PiHoleDNS(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole DNS management client.

Provides methods to manage custom DNS records, retrieve DNS configuration, and control DNS blocking status.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get DNS configuration
    config = client.dns.get_config()
    print(f"Upstream servers: {config.upstreams}")

    # Manage DNS records
    client.dns.add_a_record("server.local", "192.168.1.100")
    client.dns.add_cname_record("www.local", "server.local")

    # Control blocking
    client.dns.disable_blocking(timer=300)  # 5 minutes
    client.dns.enable_blocking()
BASE_URL: str = '/api/dns'
CONFIG_URL = '/api/config/dns'
get_config()[source]

Get Pi-hole DNS configuration.

Return type:

DNSConfig

Returns:

DNSConfig with upstream servers, custom records, and settings.

get_records(record_type=None)[source]

Get all custom DNS records.

Parameters:

record_type (Optional[str]) – Filter by “A” or “CNAME”, or None for all records.

Return type:

list[DNSRecord]

Returns:

List of DNSRecord objects.

Raises:

ValueError – If an invalid record type is specified.

add_a_record(domain, ip)[source]

Add a custom A record.

Parameters:

  • domain (str) – Domain name (e.g., “server.local”).

  • ip (str) – IPv4 address (e.g., “192.168.1.100”).

Return type:

bool

Returns:

True if the record was added successfully.

remove_a_record(domain, ip)[source]

Remove a custom A record.

Parameters:

  • domain (str) – Domain name of the record to remove.

  • ip (str) – IPv4 address of the record to remove.

Return type:

bool

Returns:

True if the record was removed successfully.

add_cname_record(domain, target)[source]

Add a custom CNAME record.

Parameters:

  • domain (str) – Source domain name (the alias).

  • target (str) – Target domain name.

Return type:

bool

Returns:

True if the record was added successfully.

remove_cname_record(domain, target)[source]

Remove a custom CNAME record.

Parameters:

  • domain (str) – Source domain name of the record to remove.

  • target (str) – Target domain name of the record to remove.

Return type:

bool

Returns:

True if the record was removed successfully.

get_blocking_status()[source]

Get DNS blocking status.

Return type:

DNSBlockingStatus

Returns:

DNSBlockingStatus with current blocking state and timer info.

set_blocking_status(blocking=True, timer=None)[source]

Change DNS blocking status.

Parameters:

  • blocking (bool) – Whether to enable (True) or disable (False) blocking.

  • timer (Optional[int]) – Optional timer in seconds. Status reverts after timer expires.

Return type:

DNSBlockingStatus

Returns:

DNSBlockingStatus with updated state.

enable_blocking(timer=None)[source]

Enable DNS blocking.

Parameters:

timer (Optional[int]) – Optional timer in seconds to auto-disable after.

Return type:

DNSBlockingStatus

Returns:

DNSBlockingStatus with updated state.

disable_blocking(timer=None)[source]

Disable DNS blocking.

Parameters:

timer (Optional[int]) – Optional timer in seconds to auto-enable after.

Return type:

DNSBlockingStatus

Returns:

DNSBlockingStatus with updated state.

class pihole_lib.PiHoleDomains(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole domain management operations.

This class provides methods to manage domains on your Pi-hole instance, including adding, updating, deleting, and retrieving domains with various filtering options.

Examples:

from pihole_lib import PiHoleClient, DomainType, DomainKind

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    domains = client.domains

    # Get all domains
    all_domains = domains.get_domains()

    # Get only allowed domains
    allowed_domains = domains.get_domains(domain_type=DomainType.ALLOW)

    # Get specific domain
    domain = domains.get_domain("example.com", DomainType.ALLOW, DomainKind.EXACT)

    # Add a new domain
    result = domains.add_domain(
        domain="badsite.com",
        domain_type=DomainType.DENY,
        domain_kind=DomainKind.EXACT,
        comment="Blocked site",
        groups=[0],
        enabled=True
    )

    # Update a domain
    updated = domains.update_domain(
        domain="example.com",
        domain_type=DomainType.ALLOW,
        domain_kind=DomainKind.EXACT,
        comment="Updated comment",
        enabled=False
    )

    # Delete a domain
    domains.delete_domain("badsite.com", DomainType.DENY, DomainKind.EXACT)

    # Batch delete domains
    domains.batch_delete_domains([
        DomainBatchDeleteItem(
            item="site1.com",
            type=DomainType.DENY,
            kind=DomainKind.EXACT
        ),
        DomainBatchDeleteItem(
            item="site2.com",
            type=DomainType.DENY,
            kind=DomainKind.EXACT
        )
    ])
BASE_URL: str = '/api/domains'
get_domains(domain_type=None, domain_kind=None, domain=None)[source]

Get domains with optional filtering.

Parameters:
Return type:

list[Domain]

Returns:

List of Domain objects matching the filters.

Raises:

Examples:

# Get all domains
all_domains = domains.get_domains()

# Get only allowed domains
allowed = domains.get_domains(domain_type=DomainType.ALLOW)

# Get only exact domains
exact = domains.get_domains(domain_kind=DomainKind.EXACT)

# Get specific domain across all types/kinds
specific = domains.get_domains(domain="example.com")

# Get allowed exact domains
allowed_exact = domains.get_domains(
    domain_type=DomainType.ALLOW,
    domain_kind=DomainKind.EXACT
)
get_domain(domain, domain_type, domain_kind)[source]

Get a specific domain by exact match.

Parameters:

  • domain (str) – The domain name to retrieve.

  • domain_type (DomainType) – Type of domain (allow/deny).

  • domain_kind (DomainKind) – Kind of domain (exact/regex).

Return type:

Domain | None

Returns:

Domain object if found, None otherwise.

Raises:

Examples:

# Get specific allowed exact domain
domain = domains.get_domain(
    "example.com",
    DomainType.ALLOW,
    DomainKind.EXACT
)

if domain:
    print(f"Found domain: {domain.domain}")
else:
    print("Domain not found")
add_domain(domain, domain_type, domain_kind, comment=None, groups=None, enabled=True)[source]

Add a new domain.

Parameters:

  • domain (str) – The domain name or regex pattern to add.

  • domain_type (DomainType) – Type of domain (allow/deny).

  • domain_kind (DomainKind) – Kind of domain (exact/regex).

  • comment (Optional[str]) – Optional comment for the domain.

  • groups (Optional[list[int]]) – List of group IDs. Defaults to [0] if not provided.

  • enabled (bool) – Whether the domain is enabled. Defaults to True.

Return type:

DomainMutationResponse

Returns:

DomainMutationResponse with the operation results.

Raises:

Examples:

# Add an exact blocked domain
result = domains.add_domain(
    domain="badsite.com",
    domain_type=DomainType.DENY,
    domain_kind=DomainKind.EXACT,
    comment="Malicious site",
    groups=[0, 1],
    enabled=True
)

# Add a regex pattern
result = domains.add_domain(
    domain=r".*\.ads\..*",
    domain_type=DomainType.DENY,
    domain_kind=DomainKind.REGEX,
    comment="Block ads subdomains"
)
update_domain(domain, domain_type, domain_kind, new_type=None, new_kind=None, comment=None, groups=None, enabled=None)[source]

Update an existing domain.

Parameters:

  • domain (str) – The domain name to update.

  • domain_type (DomainType) – Current type of domain (allow/deny).

  • domain_kind (DomainKind) – Current kind of domain (exact/regex).

  • new_type (Optional[DomainType]) – New type to move domain to (optional).

  • new_kind (Optional[DomainKind]) – New kind to move domain to (optional).

  • comment (Optional[str]) – New comment for the domain.

  • groups (Optional[list[int]]) – New list of group IDs.

  • enabled (Optional[bool]) – New enabled status.

Return type:

DomainMutationResponse

Returns:

DomainMutationResponse with the operation results.

Raises:

Examples:

# Update domain comment and disable it
result = domains.update_domain(
    domain="example.com",
    domain_type=DomainType.ALLOW,
    domain_kind=DomainKind.EXACT,
    comment="Updated comment",
    enabled=False
)

# Move domain from allow to deny
result = domains.update_domain(
    domain="example.com",
    domain_type=DomainType.ALLOW,
    domain_kind=DomainKind.EXACT,
    new_type=DomainType.DENY,
    new_kind=DomainKind.EXACT
)
delete_domain(domain, domain_type, domain_kind)[source]

Delete a domain.

Parameters:

  • domain (str) – The domain name to delete.

  • domain_type (DomainType) – Type of domain (allow/deny).

  • domain_kind (DomainKind) – Kind of domain (exact/regex).

Raises:
Return type:

None

Examples:

# Delete an exact blocked domain
domains.delete_domain(
    "badsite.com",
    DomainType.DENY,
    DomainKind.EXACT
)

# Delete a regex pattern
domains.delete_domain(
    r".*\.ads\..*",
    DomainType.DENY,
    DomainKind.REGEX
)
batch_delete_domains(domains)[source]

Delete multiple domains in a single request.

Parameters:

domains (list[DomainBatchDeleteItem]) – List of DomainBatchDeleteItem objects specifying domains to delete.

Return type:

bool

Returns:

True if successful.

Raises:

Examples:

# Delete multiple domains
success = domains.batch_delete_domains([
    DomainBatchDeleteItem(
        item="site1.com",
        type=DomainType.DENY,
        kind=DomainKind.EXACT
    ),
    DomainBatchDeleteItem(
        item="site2.com",
        type=DomainType.DENY,
        kind=DomainKind.EXACT
    ),
    DomainBatchDeleteItem(
        item=r".*\.ads\..*",
        type=DomainType.DENY,
        kind=DomainKind.REGEX
    )
])
print(f"Batch delete successful: {success}")
class pihole_lib.PiHoleGroups(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole Groups management client.

Provides methods to create, read, update, and delete groups.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get all groups
    all_groups = client.groups.get_groups()
    for group in all_groups:
        print(f"Group: {group.name}")

    # Create a new group
    client.groups.create_group(name="family_devices", comment="Family")

    # Delete a group
    client.groups.delete_group("family_devices")
BASE_URL: str = '/api/groups'
get_groups(name=None)[source]

Get groups from Pi-hole.

Parameters:

name (Optional[str]) – Optional group name to filter by.

Return type:

list[Group]

Returns:

List of Group objects.

create_group(name, comment=None, enabled=True)[source]

Create a new group.

Parameters:

  • name (str) – Group name.

  • comment (Optional[str]) – Optional comment for the group.

  • enabled (bool) – Whether the group should be enabled. Defaults to True.

Return type:

list[Group]

Returns:

List of Group objects returned by the API.

update_group(name, new_name=None, comment=None, enabled=True)[source]

Update an existing group.

Parameters:

  • name (str) – Current name of the group to update.

  • new_name (Optional[str]) – New name for the group. If None, keeps current name.

  • comment (Optional[str]) – New comment for the group.

  • enabled (bool) – Whether the group should be enabled.

Return type:

GroupsResponse

Returns:

GroupsResponse containing the updated group.

delete_group(name)[source]

Delete a group.

Parameters:

name (str) – Name of the group to delete.

Return type:

bool

Returns:

True if the group was deleted successfully.

class pihole_lib.PiHoleNetwork(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole network API client.

Provides methods to gather network information as seen by Pi-hole.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get network devices
    devices = client.network.get_devices()
    for device in devices.devices:
        print(f"{device.name}: {device.hwaddr}")

    # Get gateway info
    gateway = client.network.get_gateway()

    # Get interfaces
    interfaces = client.network.get_interfaces()
BASE_URL: str = '/api/network'
get_devices(max_devices=None, max_addresses=None)[source]

Get info about devices in your local network.

Parameters:

  • max_devices (Optional[int]) – Maximum number of devices to show (optional).

  • max_addresses (Optional[int]) – Maximum addresses per device (optional).

Return type:

NetworkDevicesResponse

Returns:

NetworkDevicesResponse containing device information.

get_gateway(detailed=False)[source]

Get info about the gateway.

Parameters:

detailed (bool) – If True, include detailed interface and route info.

Return type:

NetworkGatewayResponse | NetworkGatewayDetailedResponse

Returns:

NetworkGatewayResponse or NetworkGatewayDetailedResponse.

get_interfaces(detailed=False)[source]

Get info about network interfaces.

Parameters:

detailed (bool) – If True, include more detailed information.

Return type:

NetworkInterfacesResponse

Returns:

NetworkInterfacesResponse containing interface information.

get_routes(detailed=False)[source]

Get info about network routes.

Parameters:

detailed (bool) – If True, include more detailed information.

Return type:

NetworkRoutesResponse

Returns:

NetworkRoutesResponse containing route information.

delete_device(device_id)[source]

Delete a device from the network table.

Parameters:

device_id (int) – Device ID to delete.

Return type:

NetworkDeviceDeleteResponse

Returns:

NetworkDeviceDeleteResponse containing operation result.

class pihole_lib.PiHolePADD(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole PADD (Pi-hole API Dashboard Data) client.

Provides comprehensive dashboard data including statistics, system information, network details, and configuration summaries.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    dashboard = client.padd.get_dashboard_data()
    print(f"Active clients: {dashboard.active_clients}")
    print(f"Total queries: {dashboard.queries.total}")
    print(f"Blocked: {dashboard.queries.blocked}")
BASE_URL: str = '/api/padd'
get_dashboard_data()[source]

Get comprehensive Pi-hole dashboard data.

Return type:

PADDInfo

Returns:

PADDInfo with statistics, system info, network details, and config.

class pihole_lib.PiHoleStats(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole Stats API client.

Handles statistics and history endpoints for Pi-hole data analysis.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get activity history
    history = client.stats.get_history()

    # Get summary
    summary = client.stats.get_summary()
    print(f"Total queries: {summary.queries.total}")

    # Get top domains
    top_domains = client.stats.get_top_domains(count=10)
BASE_URL: str = '/api'
get_history()[source]

Get activity graph data.

Return type:

HistoryResponse

Returns:

HistoryResponse with timestamps and query counts.

get_client_history()[source]

Get per-client activity graph data.

Return type:

ClientHistoryResponse

Returns:

ClientHistoryResponse with per-client activity data.

get_database_history(from_timestamp, until_timestamp)[source]

Get activity graph data from long-term database.

Parameters:

  • from_timestamp (int) – Unix timestamp from when to request data.

  • until_timestamp (int) – Unix timestamp until when to request data.

Return type:

DatabaseHistoryResponse

Returns:

DatabaseHistoryResponse with long-term activity data.

get_database_client_history(from_timestamp, until_timestamp)[source]

Get per-client activity data from long-term database.

Parameters:

  • from_timestamp (int) – Unix timestamp from when to request data.

  • until_timestamp (int) – Unix timestamp until when to request data.

Return type:

DatabaseClientHistoryResponse

Returns:

DatabaseClientHistoryResponse with long-term per-client data.

get_queries(length=100, cursor=None, from_timestamp=None, until_timestamp=None, upstream=None, domain=None, client=None)[source]

Get query details with optional filtering.

Parameters:

  • length (int) – Number of queries to return (default: 100).

  • cursor (Optional[int]) – Cursor for pagination (optional).

  • from_timestamp (Optional[int]) – Only show queries from this timestamp (optional).

  • until_timestamp (Optional[int]) – Only show queries until this timestamp (optional).

  • upstream (Optional[str]) – Filter by specific upstream (optional).

  • domain (Optional[str]) – Filter by specific domain (optional).

  • client (Optional[str]) – Filter by specific client (optional).

Return type:

QueriesResponse

Returns:

QueriesResponse with query details and pagination info.

get_query_suggestions()[source]

Get query filter suggestions.

Return type:

QuerySuggestionsResponse

Returns:

QuerySuggestionsResponse with available filter suggestions.

get_query_types()[source]

Get query types statistics.

Return type:

QueryTypesResponse

Returns:

QueryTypesResponse with query types and counts.

get_recent_blocked(count=10)[source]

Get most recently blocked domains.

Parameters:

count (int) – Number of blocked domains to return (default: 10).

Return type:

RecentBlockedResponse

Returns:

RecentBlockedResponse with recently blocked domains.

get_summary()[source]

Get overview of Pi-hole activity.

Return type:

SummaryResponse

Returns:

SummaryResponse with comprehensive activity summary.

get_top_clients(blocked=None, count=10)[source]

Get top clients by query count.

Parameters:

  • blocked (Optional[bool]) – Filter by permitted (False) or blocked (True) queries.

  • count (int) – Number of clients to return (default: 10).

Return type:

TopClientsResponse

Returns:

TopClientsResponse with top clients and query counts.

get_top_domains(blocked=None, count=10)[source]

Get top domains by query count.

Parameters:

  • blocked (Optional[bool]) – Filter by permitted (False) or blocked (True) queries.

  • count (int) – Number of domains to return (default: 10).

Return type:

TopDomainsResponse

Returns:

TopDomainsResponse with top domains and query counts.

get_upstreams()[source]

Get metrics about upstream destinations.

Return type:

UpstreamsResponse

Returns:

UpstreamsResponse with upstream server metrics.

get_database_query_types(from_timestamp, until_timestamp)[source]

Get query types from long-term database.

Parameters:

  • from_timestamp (int) – Unix timestamp from when to request data.

  • until_timestamp (int) – Unix timestamp until when to request data.

Return type:

QueryTypesResponse

Returns:

QueryTypesResponse with query types for the time range.

get_database_summary(from_timestamp, until_timestamp)[source]

Get database content details for a time range.

Parameters:

  • from_timestamp (int) – Unix timestamp from when to request data.

  • until_timestamp (int) – Unix timestamp until when to request data.

Return type:

DatabaseSummaryResponse

Returns:

DatabaseSummaryResponse with summary statistics.

get_database_top_clients(from_timestamp, until_timestamp)[source]

Get top clients from long-term database.

Parameters:

  • from_timestamp (int) – Unix timestamp from when to request data.

  • until_timestamp (int) – Unix timestamp until when to request data.

Return type:

TopClientsResponse

Returns:

TopClientsResponse with top clients for the time range.

get_database_top_domains(from_timestamp, until_timestamp)[source]

Get top domains from long-term database.

Parameters:

  • from_timestamp (int) – Unix timestamp from when to request data.

  • until_timestamp (int) – Unix timestamp until when to request data.

Return type:

TopDomainsResponse

Returns:

TopDomainsResponse with top domains for the time range.

get_database_upstreams(from_timestamp, until_timestamp)[source]

Get upstream metrics from long-term database.

Parameters:

  • from_timestamp (int) – Unix timestamp from when to request data.

  • until_timestamp (int) – Unix timestamp until when to request data.

Return type:

UpstreamsResponse

Returns:

UpstreamsResponse with upstream metrics for the time range.

class pihole_lib.PiHoleClients(client)[source]

Bases: BasePiHoleAPIClient

Pi-hole Clients API client.

Handles client management operations. Clients can be identified by IP address, MAC address, hostname, or interface.

Examples:

from pihole_lib import PiHoleClient

with PiHoleClient("http://192.168.1.100", password="secret") as client:
    # Get all clients
    all_clients = client.clients.get_clients()

    # Add a new client
    client.clients.add_client(
        client="192.168.1.50",
        comment="John's laptop",
        groups=[0, 1]
    )

    # Get client suggestions
    suggestions = client.clients.get_client_suggestions()
BASE_URL: str = '/api/clients'
get_clients(client=None)[source]

Get Pi-hole clients.

Parameters:

client (Optional[str]) – Optional specific client identifier to retrieve.

Return type:

list[Client]

Returns:

List of Client objects.

add_client(client, comment=None, groups=None)[source]

Add a new client to Pi-hole.

Parameters:

  • client (str) – Client identifier (IP, MAC, hostname, or interface).

  • comment (Optional[str]) – Optional comment for this client.

  • groups (Optional[list[int]]) – Group IDs to assign (defaults to [0]).

Return type:

list[Client]

Returns:

List of Client objects containing the created client.

update_client(client, comment=None, groups=None)[source]

Update an existing client in Pi-hole.

Parameters:

  • client (str) – Client identifier to update.

  • comment (Optional[str]) – Optional comment for this client.

  • groups (Optional[list[int]]) – Group IDs to assign (defaults to [0]).

Return type:

ClientsResponse

Returns:

ClientsResponse with the updated client and processing results.

delete_client(client)[source]

Delete a client from Pi-hole.

Parameters:

client (str) – Client identifier to delete.

Return type:

bool

Returns:

True if the client was successfully deleted.

batch_delete_clients(items)[source]

Delete multiple clients from Pi-hole.

Parameters:

items (list[ClientBatchDeleteItem]) – List of ClientBatchDeleteItem objects.

Return type:

bool

Returns:

True if all clients were successfully deleted.

get_client_suggestions()[source]

Get client suggestions from Pi-hole.

Returns unconfigured clients that have been seen by Pi-hole.

Return type:

list[Client]

Returns:

List of Client objects representing unconfigured clients.

class pihole_lib.BasePiHoleAPIClient(client)[source]

Bases: object

Base class for Pi-hole API clients.

Provides common functionality for all API client classes.

BASE_URL: str = ''
__init__(client)[source]

Initialize the API client.

Parameters:

client (PiHoleClient) – PiHoleClient instance to use for requests.

exception pihole_lib.PiHoleAPIError(message, status_code=None)[source]

Bases: Exception

Base exception for Pi-hole API errors.

message

Error description.

status_code

HTTP status code if available.

__init__(message, status_code=None)[source]

Initialize API error.

Parameters:

  • message (str) – Error description.

  • status_code (Optional[int]) – HTTP status code if available.

exception pihole_lib.PiHoleAuthenticationError(message, status_code=None)[source]

Bases: PiHoleAPIError

Authentication-related error.

exception pihole_lib.PiHoleConnectionError(message, status_code=None)[source]

Bases: PiHoleAPIError

Connection-related error.

exception pihole_lib.PiHoleServerError(message, status_code=None)[source]

Bases: PiHoleAPIError

Server-side error.

class pihole_lib.ProcessedSuccess(**data)[source]

Bases: StrictModel

Generic success item in processing result.

item: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ProcessedError(**data)[source]

Bases: StrictModel

Generic error item in processing result.

item: str
error: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ProcessedResult(**data)[source]

Bases: StrictModel

Generic processing result.

success: list[ProcessedSuccess]
errors: list[ProcessedError]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ListType(value)[source]

Bases: str, Enum

Pi-hole list types.

ALLOW = 'allow'
BLOCK = 'block'
__format__(format_spec)

Returns format using actual value type unless __str__ has been overridden.

class pihole_lib.DomainType(value)[source]

Bases: str, Enum

Pi-hole domain types.

ALLOW = 'allow'
DENY = 'deny'
__format__(format_spec)

Returns format using actual value type unless __str__ has been overridden.

class pihole_lib.DomainKind(value)[source]

Bases: str, Enum

Pi-hole domain kinds.

EXACT = 'exact'
REGEX = 'regex'
__format__(format_spec)

Returns format using actual value type unless __str__ has been overridden.

class pihole_lib.RAMStats(**data)[source]

Bases: MemoryStats

RAM statistics with available memory.

available: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.MemoryStats(**data)[source]

Bases: StrictModel

Memory statistics (RAM or Swap).

total: int
free: int
used: int
percent_used: float
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.Memory(**data)[source]

Bases: StrictModel

Combined RAM and swap memory information.

ram: RAMStats
swap: MemoryStats
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.CPULoad(**data)[source]

Bases: StrictModel

CPU load averages.

raw: list[float]
percent: list[float]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.CPUStats(**data)[source]

Bases: StrictModel

CPU statistics.

nprocs: int
percent_cpu: float
load: CPULoad
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.FTLResourceUsage(**data)[source]

Bases: StrictModel

FTL process resource usage.

percent_mem: float
percent_cpu: float
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.SystemDetails(**data)[source]

Bases: StrictModel

System resource details.

uptime: int
memory: Memory
procs: int
cpu: CPUStats
ftl: FTLResourceUsage
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.SystemInfo(**data)[source]

Bases: StrictModel

Pi-hole system information wrapper.

system: SystemDetails
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.VersionLocal(**data)[source]

Bases: StrictModel

Local version information.

version: str
branch: str | None
hash: str
date: str | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.VersionRemote(**data)[source]

Bases: StrictModel

Remote version information.

version: str | None
hash: str | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ComponentVersion(**data)[source]

Bases: StrictModel

Component version information.

local: VersionLocal
remote: VersionRemote
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DockerVersion(**data)[source]

Bases: StrictModel

Docker version information.

local: str | None
remote: str | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.VersionDetails(**data)[source]

Bases: StrictModel

Pi-hole version details for all components.

core: ComponentVersion
web: ComponentVersion
ftl: ComponentVersion
docker: DockerVersion
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.VersionInfo(**data)[source]

Bases: TimedResponse

Pi-hole version information response.

version: VersionDetails
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.LoginInfo(**data)[source]

Bases: StrictModel

Pi-hole login page information.

https_port: int
dns: bool
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PiHoleAuthSession(**data)[source]

Bases: StrictModel

Pi-hole authentication session data.

valid: bool
totp: bool
sid: str
csrf: str
validity: int
message: str | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ClientHeader(**data)[source]

Bases: StrictModel

HTTP header from client request.

name: str
value: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ClientInfo(**data)[source]

Bases: StrictModel

Pi-hole client request information.

remote_addr: str
http_version: str
method: str
headers: list[ClientHeader]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DatabaseUser(**data)[source]

Bases: StrictModel

Database file user information.

uid: int
name: str
info: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DatabaseGroup(**data)[source]

Bases: StrictModel

Database file group information.

gid: int
name: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DatabaseOwner(**data)[source]

Bases: StrictModel

Database file ownership information.

user: DatabaseUser
group: DatabaseGroup
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DatabaseInfo(**data)[source]

Bases: StrictModel

Pi-hole database information.

size: int
type: str
mode: str
atime: int
mtime: int
ctime: int
owner: DatabaseOwner
queries: int
earliest_timestamp: int
queries_disk: int
earliest_timestamp_disk: int
sqlite_version: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.FTLDatabaseStats(**data)[source]

Bases: StrictModel

FTL database statistics.

gravity: int
groups: int
lists: int
clients: int
domains: dict
regex: dict
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.FTLClientStats(**data)[source]

Bases: StrictModel

FTL client statistics.

total: int
active: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.FTLDnsmasqStats(**data)[source]

Bases: StrictModel

FTL dnsmasq statistics.

dns_cache_inserted: int
dns_cache_live_freed: int
dns_queries_forwarded: int
dns_auth_answered: int
dns_local_answered: int
dns_stale_answered: int
dns_unanswered: int
dnssec_max_crypto_use: int
dnssec_max_sig_fail: int
dnssec_max_work: int
bootp: int
pxe: int
dhcp_ack: int
dhcp_decline: int
dhcp_discover: int
dhcp_inform: int
dhcp_nak: int
dhcp_offer: int
dhcp_release: int
dhcp_request: int
noanswer: int
leases_allocated_4: int
leases_pruned_4: int
leases_allocated_6: int
leases_pruned_6: int
tcp_connections: int
dhcp_leasequery: int
dhcp_lease_unassigned: int
dhcp_lease_actve: int
dhcp_lease_unknown: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.FTLStats(**data)[source]

Bases: StrictModel

FTL statistics.

database: FTLDatabaseStats
privacy_level: int
query_frequency: int
clients: FTLClientStats
pid: int
uptime: float
mem_percent: float
cpu_percent: float
allow_destructive: bool
dnsmasq: FTLDnsmasqStats
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.FTLInfo(**data)[source]

Bases: StrictModel

Pi-hole FTL information wrapper.

ftl: FTLStats
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.HostUname(**data)[source]

Bases: StrictModel

Host system uname information.

domainname: str
machine: str
nodename: str
release: str
sysname: str
version: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.HostDMIBios(**data)[source]

Bases: StrictModel

Host DMI BIOS information.

vendor: str | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.HostDMIBoard(**data)[source]

Bases: StrictModel

Host DMI board information.

name: str | None
vendor: str | None
version: str | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.HostDMIProduct(**data)[source]

Bases: StrictModel

Host DMI product information.

name: str | None
family: str | None
version: str | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.HostDMISystem(**data)[source]

Bases: StrictModel

Host DMI system information.

vendor: str | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.HostDMI(**data)[source]

Bases: StrictModel

Host DMI/SMBIOS information.

bios: HostDMIBios
board: HostDMIBoard
product: HostDMIProduct
sys: HostDMISystem
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.HostDetails(**data)[source]

Bases: StrictModel

Host system details.

uname: HostUname
model: str | None
dmi: HostDMI
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.HostInfo(**data)[source]

Bases: StrictModel

Pi-hole host system information wrapper.

host: HostDetails
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PiHoleList(**data)[source]

Bases: StrictModel

Pi-hole domain list.

address: str
type: ListType
comment: str | None
groups: list[int]
enabled: bool
id: int
date_added: int
date_modified: int
date_updated: int
number: int
invalid_domains: int
abp_entries: int
status: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.AddListRequest(**data)[source]

Bases: StrictModel

Request model for adding a new Pi-hole list.

address: str
comment: str | None
groups: list[int]
enabled: bool
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.UpdateListRequest(**data)[source]

Bases: StrictModel

Request model for updating an existing Pi-hole list.

comment: str | None
type: ListType
groups: list[int]
enabled: bool
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.BatchDeleteItem(**data)[source]

Bases: StrictModel

Item for batch delete operation.

item: str
type: ListType
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ListProcessedSuccess(**data)[source]

Bases: StrictModel

Success item in list processing result.

item: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ListProcessedError(**data)[source]

Bases: StrictModel

Error item in list processing result.

item: str
error: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ListProcessedResult(**data)[source]

Bases: StrictModel

Processing result for list operations.

success: list[ListProcessedSuccess]
errors: list[ListProcessedError]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ListsResponse(**data)[source]

Bases: TimedResponse

Response model for list operations.

lists: list[PiHoleList]
processed: ListProcessedResult | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.SearchResultCounts(**data)[source]

Bases: StrictModel

Search result counts.

exact: int
regex: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.SearchGravityCounts(**data)[source]

Bases: StrictModel

Search gravity result counts.

allow: int
block: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.SearchResults(**data)[source]

Bases: StrictModel

Search results summary.

domains: SearchResultCounts
gravity: SearchGravityCounts
total: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.SearchParameters(**data)[source]

Bases: StrictModel

Search parameters used.

N: int
partial: bool
domain: str
debug: bool
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.SearchData(**data)[source]

Bases: StrictModel

Search data container.

domains: list[PiHoleList]
gravity: list[PiHoleList]
results: SearchResults
parameters: SearchParameters
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.SearchResponse(**data)[source]

Bases: TimedResponse

Response for domain search operations.

search: SearchData
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.Message(**data)[source]

Bases: StrictModel

Pi-hole system message.

id: int
timestamp: int
type: str
plain: str
html: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.MessagesInfo(**data)[source]

Bases: StrictModel

Pi-hole messages information.

messages: list[Message]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.MessagesCountInfo(**data)[source]

Bases: StrictModel

Pi-hole messages count information.

count: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DHCPLease(**data)[source]

Bases: StrictModel

DHCP lease information.

expires: int
name: str
hwaddr: str
ip: str
clientid: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DHCPLeasesInfo(**data)[source]

Bases: StrictModel

DHCP leases information.

leases: list[DHCPLease]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PADDQueries(**data)[source]

Bases: StrictModel

PADD queries information.

total: int
blocked: int
percent_blocked: float
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PADDCache(**data)[source]

Bases: StrictModel

PADD cache information.

size: int
inserted: int
evicted: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PADDMemory(**data)[source]

Bases: StrictModel

PADD memory information.

ram: RAMStats
swap: MemoryStats
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PADDSystem(**data)[source]

Bases: StrictModel

PADD system information.

uptime: int
memory: PADDMemory
procs: int
cpu: CPUStats
ftl: FTLResourceUsage
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.NetworkBytes(**data)[source]

Bases: StrictModel

Network byte count with unit.

value: float
unit: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PADDNetworkBytes(**data)[source]

Bases: StrictModel

PADD network bytes information.

value: float
unit: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PADDNetworkInterface(**data)[source]

Bases: StrictModel

PADD network interface information.

addr: str | None
rx_bytes: PADDNetworkBytes | None
tx_bytes: PADDNetworkBytes | None
num_addrs: int
name: str
gw_addr: str | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PADDInterface(**data)[source]

Bases: StrictModel

PADD interface information.

v4: PADDNetworkInterface
v6: PADDNetworkInterface
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PADDVersionComponent(**data)[source]

Bases: StrictModel

PADD version component information.

version: str
branch: str | None
hash: str
date: str | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PADDVersionRemote(**data)[source]

Bases: StrictModel

PADD remote version information.

version: str | None
hash: str | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PADDVersionInfo(**data)[source]

Bases: StrictModel

PADD version component info.

local: PADDVersionComponent
remote: PADDVersionRemote
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PADDVersionDocker(**data)[source]

Bases: StrictModel

PADD Docker version information.

local: str
remote: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PADDVersion(**data)[source]

Bases: StrictModel

PADD version information.

core: PADDVersionInfo
web: PADDVersionInfo
ftl: PADDVersionInfo
docker: PADDVersionDocker
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PADDConfig(**data)[source]

Bases: StrictModel

PADD configuration information.

dhcp_active: bool
dhcp_start: str
dhcp_end: str
dhcp_ipv6: bool
dns_domain: str
dns_port: int
dns_num_upstreams: int
dns_dnssec: bool
dns_revServer_active: bool
privacy_level: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PADDSensors(**data)[source]

Bases: StrictModel

PADD sensors information.

cpu_temp: float | None
hot_limit: int
unit: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.PADDInfo(**data)[source]

Bases: StrictModel

Pi-hole PADD (Pi-hole API Dashboard Data) information.

active_clients: int
gravity_size: int
top_domain: str | None
top_blocked: str | None
top_client: str | None
recent_blocked: str | None
blocking: str
queries: PADDQueries
cache: PADDCache
system: PADDSystem
node_name: str
host_model: str | None
iface: PADDInterface
version: PADDVersion
config: PADDConfig
percent_mem: float
percent_cpu: float
pid: int
sensors: PADDSensors
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DNSRecord(**data)[source]

Bases: StrictModel

DNS record information.

domain: str
target: str
record_type: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DNSConfig(**data)[source]

Bases: StrictModel

DNS configuration information.

upstreams: list[str]
records: list[DNSRecord]
port: int
query_logging: bool
dnssec: bool
blocking: dict[str, Any]
property blocking_active: bool

Whether DNS blocking is active.

property hosts: list[DNSRecord]

List of A records (host entries).

property cname_records: list[DNSRecord]

List of CNAME records.

classmethod from_raw_config(raw_config)[source]

Create DNSConfig from raw API response.

Return type:

DNSConfig

model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DNSConfigInfo(**data)[source]

Bases: StrictModel

DNS configuration response information.

config: dict
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DNSBlockingStatus(**data)[source]

Bases: TimedResponse

DNS blocking status information.

blocking: str
timer: int | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.Group(**data)[source]

Bases: StrictModel

Pi-hole group information.

name: str
comment: str | None
enabled: bool
id: int
date_added: int
date_modified: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.GroupRequest(**data)[source]

Bases: StrictModel

Request model for creating or updating a group.

name: str
comment: str | None
enabled: bool
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.GroupProcessedSuccess(**data)[source]

Bases: StrictModel

Success item in group processing result.

item: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.GroupProcessedError(**data)[source]

Bases: StrictModel

Error item in group processing result.

item: str
error: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.GroupProcessedResult(**data)[source]

Bases: StrictModel

Processing result for group operations.

success: list[GroupProcessedSuccess]
errors: list[GroupProcessedError]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.GroupsResponse(**data)[source]

Bases: TimedResponse

Response model for group operations.

groups: list[Group]
processed: GroupProcessedResult | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.HistoryEntry(**data)[source]

Bases: StrictModel

History entry for activity graph data.

timestamp: int
total: int
cached: int
blocked: int
forwarded: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.HistoryResponse(**data)[source]

Bases: TimedResponse

Response for history endpoints.

history: list[HistoryEntry]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ClientHistoryEntry(**data)[source]

Bases: StrictModel

Client history entry for per-client activity data.

timestamp: int
data: dict[str, int]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ClientHistoryResponse(**data)[source]

Bases: TimedResponse

Response for client history endpoints.

history: list[ClientHistoryEntry]
clients: dict[str, str]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DatabaseHistoryResponse(**data)[source]

Bases: TimedResponse

Response for database history endpoints.

history: list[HistoryEntry]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DatabaseClientHistoryResponse(**data)[source]

Bases: TimedResponse

Response for database client history endpoints.

history: list[ClientHistoryEntry]
clients: dict[str, str]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.QueryEntry(**data)[source]

Bases: StrictModel

Individual query entry.

timestamp: int
type: str
domain: str
client: str
status: str
destination: str
reply_type: str
response_time: float
dnssec: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.QueriesResponse(**data)[source]

Bases: TimedResponse

Response for queries endpoint.

queries: list[QueryEntry]
cursor: int
records_total: int
records_filtered: int
draw: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.QuerySuggestions(**data)[source]

Bases: StrictModel

Query filter suggestions.

domain: list[str]
client_ip: list[str]
client_name: list[str]
upstream: list[str]
type: list[str]
status: list[str]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.QuerySuggestionsResponse(**data)[source]

Bases: TimedResponse

Response for query suggestions endpoint.

suggestions: QuerySuggestions
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.QueryTypesResponse(**data)[source]

Bases: TimedResponse

Response for query types endpoints.

types: dict[str, int]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DatabaseSummaryResponse(**data)[source]

Bases: TimedResponse

Response for database summary endpoint.

sum_queries: int
sum_blocked: int
percent_blocked: float
total_clients: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.TopClient(**data)[source]

Bases: StrictModel

Top client entry.

ip: str
name: str | None
count: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.TopClientsResponse(**data)[source]

Bases: TimedResponse

Response for top clients endpoints.

clients: list[TopClient]
total_queries: int
blocked_queries: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.TopDomain(**data)[source]

Bases: StrictModel

Top domain entry.

domain: str
count: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.TopDomainsResponse(**data)[source]

Bases: TimedResponse

Response for top domains endpoints.

domains: list[TopDomain]
total_queries: int
blocked_queries: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.UpstreamStatistics(**data)[source]

Bases: StrictModel

Upstream server statistics.

response: float
variance: float
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.UpstreamServer(**data)[source]

Bases: StrictModel

Upstream server information.

ip: str
name: str
port: int
count: int
statistics: UpstreamStatistics | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.UpstreamsResponse(**data)[source]

Bases: TimedResponse

Response for upstreams endpoints.

upstreams: list[UpstreamServer]
total_queries: int
forwarded_queries: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.RecentBlockedResponse(**data)[source]

Bases: TimedResponse

Response for recent blocked domains endpoint.

blocked: list[str]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.SummaryQueries(**data)[source]

Bases: StrictModel

Summary queries information.

total: int
blocked: int
percent_blocked: float
unique_domains: int
forwarded: int
cached: int
frequency: float
types: dict[str, int]
status: dict[str, int]
replies: dict[str, int]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.SummaryClients(**data)[source]

Bases: StrictModel

Summary clients information.

total: int
active: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.SummaryGravity(**data)[source]

Bases: StrictModel

Summary gravity information.

domains_being_blocked: int
last_update: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.SummaryResponse(**data)[source]

Bases: TimedResponse

Response for summary endpoint.

queries: SummaryQueries
clients: SummaryClients
gravity: SummaryGravity
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.Domain(**data)[source]

Bases: StrictModel

Pi-hole domain entry.

domain: str
unicode: str
type: DomainType
kind: DomainKind
comment: str | None
groups: list[int]
enabled: bool
id: int
date_added: int
date_modified: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DomainsResponse(**data)[source]

Bases: TimedResponse

Response for domains endpoints.

domains: list[Domain]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DomainRequest(**data)[source]

Bases: StrictModel

Request for adding/updating domains.

domain: str | None
type: DomainType | None
kind: DomainKind | None
comment: str | None
groups: list[int] | None
enabled: bool | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DomainBatchDeleteItem(**data)[source]

Bases: StrictModel

Item for batch domain deletion.

item: str
type: DomainType
kind: DomainKind
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DomainProcessedSuccess(**data)[source]

Bases: StrictModel

Successful domain processing result.

item: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DomainProcessedError(**data)[source]

Bases: StrictModel

Failed domain processing result.

item: str
error: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DomainProcessedResult(**data)[source]

Bases: StrictModel

Domain processing results.

success: list[DomainProcessedSuccess]
errors: list[DomainProcessedError]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DomainMutationResponse(**data)[source]

Bases: TimedResponse

Response for domain mutation operations.

domains: list[Domain]
processed: DomainProcessedResult
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.DomainBatchDeleteResponse(**data)[source]

Bases: TimedResponse

Response for batch domain deletion.

model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.NetworkDeviceAddress(**data)[source]

Bases: StrictModel

Network device address information.

ip: str
hostname: str | None
last_query: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.NetworkDevice(**data)[source]

Bases: StrictModel

Network device information.

id: int
hwaddr: str
interface: str
name: str
first_seen: int
last_query: int
num_queries: int
addresses: list[NetworkDeviceAddress]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.NetworkDevicesResponse(**data)[source]

Bases: TimedResponse

Response for network devices endpoint.

devices: list[NetworkDevice]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.NetworkGateway(**data)[source]

Bases: StrictModel

Network gateway information.

family: str
interface: str
address: str
local: list[str]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.NetworkGatewayResponse(**data)[source]

Bases: TimedResponse

Response for network gateway endpoint.

gateway: list[NetworkGateway]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.NetworkGatewayDetailedResponse(**data)[source]

Bases: TimedResponse

Response for detailed network gateway endpoint.

gateway: list[NetworkGateway]
routes: list[dict]
interfaces: list[dict]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.NetworkInterfaceStats(**data)[source]

Bases: StrictModel

Network interface statistics.

rx_bytes: dict[str, str | float]
tx_bytes: dict[str, str | float]
bits: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.NetworkInterfaceAddress(**data)[source]

Bases: StrictModel

Network interface address information.

family: str
scope: str
flags: list[str]
prefixlen: int
address: str
address_type: str
local: str | None
local_type: str | None
broadcast: str | None
broadcast_type: str | None
label: str | None
prefered: int
valid: int
cstamp: float
tstamp: float
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.NetworkInterface(**data)[source]

Bases: StrictModel

Network interface information.

name: str
speed: int | None
type: str
flags: list[str]
state: str
carrier: bool
proto_down: bool
address: str
broadcast: str
perm_address: str | None
stats: NetworkInterfaceStats
addresses: list[NetworkInterfaceAddress] | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.NetworkInterfacesResponse(**data)[source]

Bases: TimedResponse

Response for network interfaces endpoint.

interfaces: list[NetworkInterface]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.NetworkRoute(**data)[source]

Bases: StrictModel

Network route information.

table: int
family: str
protocol: str
scope: str
type: str
flags: list[str]
gateway: str | None
oif: str
dst: str
prefsrc: str | None
priority: int | None
pref: int | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.NetworkRoutesResponse(**data)[source]

Bases: TimedResponse

Response for network routes endpoint.

routes: list[NetworkRoute]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.NetworkDeviceDeleteResponse(**data)[source]

Bases: TimedResponse

Response for network device deletion.

model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.Client(**data)[source]

Bases: StrictModel

Pi-hole client entry.

client: str
name: str
comment: str | None
groups: list[int]
id: int
date_added: int
date_modified: int
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ClientRequest(**data)[source]

Bases: StrictModel

Request model for creating or updating a client.

client: str | None
comment: str | None
groups: list[int]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ClientUpdateRequest(**data)[source]

Bases: StrictModel

Request model for updating an existing client.

comment: str | None
groups: list[int]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ClientBatchDeleteItem(**data)[source]

Bases: StrictModel

Item for batch client deletion.

item: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ClientProcessedSuccess(**data)[source]

Bases: StrictModel

Success item in client processing result.

item: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ClientProcessedError(**data)[source]

Bases: StrictModel

Error item in client processing result.

item: str
error: str
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ClientProcessedResult(**data)[source]

Bases: StrictModel

Processing result for client operations.

success: list[ClientProcessedSuccess]
errors: list[ClientProcessedError]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ClientsResponse(**data)[source]

Bases: TimedResponse

Response model for client operations.

clients: list[Client]
processed: ClientProcessedResult | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.ClientSuggestionsResponse(**data)[source]

Bases: TimedResponse

Response model for client suggestions.

clients: list[Client]
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.TeleporterGravityOptions(**data)[source]

Bases: StrictModel

Teleporter gravity database import options.

group: bool
adlist: bool
adlist_by_group: bool
domainlist: bool
domainlist_by_group: bool
client: bool
client_by_group: bool
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pihole_lib.TeleporterImportOptions(**data)[source]

Bases: StrictModel

Pi-hole Teleporter import options.

config: bool
dhcp_leases: bool
gravity: TeleporterGravityOptions
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].