pihole6api 0.1.0__tar.gz

pihole6api-0.1.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Shane Barbetta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

pihole6api-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.2
+Name: pihole6api
+Version: 0.1.0
+Summary: Python API Client for Pi-hole 6
+Author-email: Shane Barbetta <shane@barbetta.me>
+License: MIT
+Project-URL: Homepage, https://github.com/sbarbett/pihole6api
+Project-URL: Documentation, https://github.com/sbarbett/pihole6api
+Project-URL: Source, https://github.com/sbarbett/pihole6api
+Project-URL: Issues, https://github.com/sbarbett/pihole6api/issues
+Keywords: pihole,dns,adblocking,api,client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.26.0
+
+# pihole6api
+
+This package provides a simple, modular SDK for the PiHole 6 REST API.
+
+## Features
+
+* Automatically handles authentication and renewal
+* Gracefully error management
+* Logically organized modules
+* Easily maintained
+
+## Installation
+
+**Install using `pip` or `pipx`:**
+
+```bash
+pip install pihole6api
+```
+
+**Install from source:**
+
+```bash
+git clone https://github.com/sbarbett/pihole6api.git
+cd pihole6api
+pip install -e .
+```
+
+## Quick Start
+
+### Initialize the Client
+
+```python
+from pihole6api.client import PiHole6Client
+client = PiHole6Client("https://your-pihole.local/", "your-password")
+```
+
+### Example Usage
+
+#### Get Pi-Hole Metrics
+
+```python
+history = client.metrics.get_history()
+print(history)  # {'history': [{'timestamp': 1740120900, 'total': 0, 'cached': 0 ...}]}
+queries = client.metrics.get_queries()
+print(queries)
+```
+
+#### Enable/Disable Blocking
+
+```python
+client.dns_control.set_blocking_status(False, 60)
+print(client.dns_control.get_blocking_status()) # {'blocking': 'disabled', 'timer': 60 ...}
+```
+
+#### Manage Groups
+
+```python
+client.group_management.add_group("Custom Group", comment="For testing")
+client.group_management.delete_group("Custom Group")
+```
+
+#### Manage Domains
+
+```python
+client.domain_management.add_domain("ads.example.com", "deny", "exact")
+client.domain_management.delete_domain("ads.example.com", "deny", "exact")
+```
+
+#### Manage Links
+
+```python
+client.list_management.add_list("https://example.com/blocklist.txt", "block")
+client.list_management.delete_list("https://example.com/blocklist.txt", "block")
+```
+
+#### Export/Import PiHole Settings
+
+```python
+# Export settings and save as a .zip file
+with open("pihole-settings.zip", "wb") as f:
+    f.write(client.config.export_settings())
+
+client.config.import_settings("pihole-settings.zip", {"config": True, "gravity": {"group": True}})
+```
+
+#### Flush Logs & Restart DNS
+
+```python
+client.actions.flush_logs()
+client.actions.restart_dns()
+```
+
+## API Modules
+
+| Module                | Description |
+|----------------------|-------------|
+| `metrics`           | Query history, top clients/domains, DNS stats |
+| `dns_control`       | Enable/disable blocking |
+| `group_management`  | Create, update, and delete groups |
+| `domain_management` | Allow/block domains (exact & regex) |
+| `client_management` | Manage client-specific rules |
+| `list_management`   | Manage blocklists (Adlists) |
+| `config`            | Modify Pi-hole configuration |
+| `ftl_info`          | Get Pi-hole core process (FTL) info |
+| `dhcp`              | Manage DHCP leases |
+| `network_info`      | View network devices, interfaces, routes |
+| `actions`           | Flush logs, restart services |
+| `padd`              | Fetch summarized data for PADD |
+
+## License
+
+This project is license under the [MIT license](LICENSE).

pihole6api-0.1.0/README.md

@@ -0,0 +1,112 @@
+# pihole6api
+
+This package provides a simple, modular SDK for the PiHole 6 REST API.
+
+## Features
+
+* Automatically handles authentication and renewal
+* Gracefully error management
+* Logically organized modules
+* Easily maintained
+
+## Installation
+
+**Install using `pip` or `pipx`:**
+
+```bash
+pip install pihole6api
+```
+
+**Install from source:**
+
+```bash
+git clone https://github.com/sbarbett/pihole6api.git
+cd pihole6api
+pip install -e .
+```
+
+## Quick Start
+
+### Initialize the Client
+
+```python
+from pihole6api.client import PiHole6Client
+client = PiHole6Client("https://your-pihole.local/", "your-password")
+```
+
+### Example Usage
+
+#### Get Pi-Hole Metrics
+
+```python
+history = client.metrics.get_history()
+print(history)  # {'history': [{'timestamp': 1740120900, 'total': 0, 'cached': 0 ...}]}
+queries = client.metrics.get_queries()
+print(queries)
+```
+
+#### Enable/Disable Blocking
+
+```python
+client.dns_control.set_blocking_status(False, 60)
+print(client.dns_control.get_blocking_status()) # {'blocking': 'disabled', 'timer': 60 ...}
+```
+
+#### Manage Groups
+
+```python
+client.group_management.add_group("Custom Group", comment="For testing")
+client.group_management.delete_group("Custom Group")
+```
+
+#### Manage Domains
+
+```python
+client.domain_management.add_domain("ads.example.com", "deny", "exact")
+client.domain_management.delete_domain("ads.example.com", "deny", "exact")
+```
+
+#### Manage Links
+
+```python
+client.list_management.add_list("https://example.com/blocklist.txt", "block")
+client.list_management.delete_list("https://example.com/blocklist.txt", "block")
+```
+
+#### Export/Import PiHole Settings
+
+```python
+# Export settings and save as a .zip file
+with open("pihole-settings.zip", "wb") as f:
+    f.write(client.config.export_settings())
+
+client.config.import_settings("pihole-settings.zip", {"config": True, "gravity": {"group": True}})
+```
+
+#### Flush Logs & Restart DNS
+
+```python
+client.actions.flush_logs()
+client.actions.restart_dns()
+```
+
+## API Modules
+
+| Module                | Description |
+|----------------------|-------------|
+| `metrics`           | Query history, top clients/domains, DNS stats |
+| `dns_control`       | Enable/disable blocking |
+| `group_management`  | Create, update, and delete groups |
+| `domain_management` | Allow/block domains (exact & regex) |
+| `client_management` | Manage client-specific rules |
+| `list_management`   | Manage blocklists (Adlists) |
+| `config`            | Modify Pi-hole configuration |
+| `ftl_info`          | Get Pi-hole core process (FTL) info |
+| `dhcp`              | Manage DHCP leases |
+| `network_info`      | View network devices, interfaces, routes |
+| `actions`           | Flush logs, restart services |
+| `padd`              | Fetch summarized data for PADD |
+
+## License
+
+This project is license under the [MIT license](LICENSE).

pihole6api-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pihole6api"
+version = "0.1.0"
+description = "Python API Client for Pi-hole 6"
+authors = [{name = "Shane Barbetta", email = "shane@barbetta.me"}]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.8"
+keywords = ["pihole", "dns", "adblocking", "api", "client"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "requests >=2.26.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/sbarbett/pihole6api"
+Documentation = "https://github.com/sbarbett/pihole6api"
+Source = "https://github.com/sbarbett/pihole6api"
+Issues = "https://github.com/sbarbett/pihole6api/issues"

pihole6api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pihole6api-0.1.0/src/pihole6api/__init__.py

@@ -0,0 +1,29 @@
+from .client import PiHole6Client
+from .conn import PiHole6Connection
+from .actions import PiHole6Actions
+from .config import PiHole6Configuration
+from .dhcp import PiHole6Dhcp
+from .domain_management import PiHole6DomainManagement
+from .group_management import PiHole6GroupManagement
+from .list_management import PiHole6ListManagement
+from .metrics import PiHole6Metrics
+from .network_info import PiHole6NetworkInfo
+from .ftl_info import PiHole6FtlInfo
+from .dns_control import PiHole6DnsControl
+from .client_management import PiHole6ClientManagement
+
+__all__ = [
+    "PiHole6Client",
+    "PiHole6Connection",
+    "PiHole6Actions",
+    "PiHole6Configuration",
+    "PiHole6Dhcp",
+    "PiHole6DomainManagement",
+    "PiHole6GroupManagement",
+    "PiHole6ListManagement",
+    "PiHole6Metrics",
+    "PiHole6NetworkInfo",
+    "PiHole6FtlInfo",
+    "PiHole6DnsControl",
+    "PiHole6ClientManagement",
+]

pihole6api-0.1.0/src/pihole6api/actions.py

@@ -0,0 +1,20 @@
+class PiHole6Actions:
+    def __init__(self, connection):
+        """Handles Pi-hole system action API endpoints."""
+        self.connection = connection
+
+    def flush_arp(self):
+        """Flush the network table (ARP cache)."""
+        return self.connection.post("action/flush/arp")
+
+    def flush_logs(self):
+        """Flush the DNS logs."""
+        return self.connection.post("action/flush/logs")
+
+    def run_gravity(self):
+        """Run gravity (updates blocklists and reprocesses them)."""
+        return self.connection.post("action/gravity")
+
+    def restart_dns(self):
+        """Restart the Pi-hole FTL DNS resolver."""
+        return self.connection.post("action/restartdns")

pihole6api-0.1.0/src/pihole6api/client.py

@@ -0,0 +1,44 @@
+from .conn import PiHole6Connection
+from .metrics import PiHole6Metrics
+from .dns_control import PiHole6DnsControl
+from .group_management import PiHole6GroupManagement
+from .domain_management import PiHole6DomainManagement
+from .client_management import PiHole6ClientManagement
+from .list_management import PiHole6ListManagement
+from .ftl_info import PiHole6FtlInfo
+from .config import PiHole6Configuration
+from .network_info import PiHole6NetworkInfo
+from .actions import PiHole6Actions
+from .dhcp import PiHole6Dhcp
+
+class PiHole6Client:
+    def __init__(self, base_url, password):
+        """
+        Initialize the Pi-hole client wrapper.
+
+        :param base_url: Pi-hole API base URL
+        :param password: Pi-hole password (or application password)
+        """
+        self.connection = PiHole6Connection(base_url, password)
+
+        # Attach API Modules
+        self.metrics = PiHole6Metrics(self.connection)
+        self.dns_control = PiHole6DnsControl(self.connection)
+        self.group_management = PiHole6GroupManagement(self.connection)
+        self.domain_management = PiHole6DomainManagement(self.connection)
+        self.client_management = PiHole6ClientManagement(self.connection)
+        self.list_management = PiHole6ListManagement(self.connection)
+        self.ftl_info = PiHole6FtlInfo(self.connection)
+        self.config = PiHole6Configuration(self.connection)
+        self.network_info = PiHole6NetworkInfo(self.connection)
+        self.actions = PiHole6Actions(self.connection)
+        self.dhcp = PiHole6Dhcp(self.connection)
+
+    def get_padd_summary(self, full=False):
+        """
+        Get summarized data for PADD.
+
+        :param full: Boolean flag to get the full dataset.
+        :return: API response containing PADD summary.
+        """
+        return self.connection.get("padd", params={"full": str(full).lower()})

pihole6api-0.1.0/src/pihole6api/client_management.py

@@ -0,0 +1,72 @@
+class PiHole6ClientManagement:
+    def __init__(self, connection):
+        """
+        Handles Pi-hole client management API endpoints.
+        :param connection: Instance of PiHole6Connection for API requests.
+        """
+        self.connection = connection
+
+    def add_client(self, client, comment=None, groups=None):
+        """
+        Add a new client to Pi-hole.
+
+        :param client: Client identifier (IP, MAC, hostname, or interface).
+        :param comment: Optional comment for the client.
+        :param groups: Optional list of group IDs.
+        """
+        payload = {
+            "client": client if isinstance(client, list) else [client],
+            "comment": comment,
+            "groups": groups if groups else []
+        }
+
+        return self.connection.post("clients", data=payload)
+
+    def batch_delete_clients(self, clients):
+        """
+        Delete multiple clients.
+
+        :param clients: List of client identifiers (IP, MAC, hostname, or interface).
+                        Example: [{"item": "192.168.1.100"}, {"item": "12:34:56:78:9A:BC"}]
+        """
+        if not isinstance(clients, list):
+            raise ValueError("clients must be a list of dictionaries.")
+
+        return self.connection.post("clients:batchDelete", data=clients)
+
+    def get_client_suggestions(self):
+        """
+        Retrieve suggested client entries based on known devices.
+        """
+        return self.connection.get("clients/_suggestions")
+
+    def get_client(self, client):
+        """
+        Retrieve information about a specific client.
+
+        :param client: Client identifier (IP, MAC, hostname, or interface).
+        """
+        return self.connection.get(f"clients/{client}")
+
+    def update_client(self, client, comment=None, groups=None):
+        """
+        Update an existing client.
+
+        :param client: Client identifier (IP, MAC, hostname, or interface).
+        :param comment: Updated comment (optional).
+        :param groups: Updated list of group IDs (optional).
+        """
+        payload = {
+            "comment": comment,
+            "groups": groups if groups else []
+        }
+
+        return self.connection.put(f"clients/{client}", data=payload)
+
+    def delete_client(self, client):
+        """
+        Delete a single client.
+
+        :param client: Client identifier (IP, MAC, hostname, or interface).
+        """
+        return self.connection.delete(f"clients/{client}")

pihole6api-0.1.0/src/pihole6api/config.py

@@ -0,0 +1,79 @@
+import json
+
+class PiHole6Configuration:
+    def __init__(self, connection):
+        """
+        Handles Pi-hole configuration API endpoints.
+        :param connection: Instance of PiHole6Connection for API requests.
+        """
+        self.connection = connection
+
+    def export_settings(self):
+        """
+        Export Pi-hole settings via the Teleporter API.
+        :return: Binary content of the exported settings archive.
+        """
+        return self.connection.get("teleporter", is_binary=True)
+
+    def import_settings(self, file_path, import_options=None):
+        """
+        Import Pi-hole settings using a Teleporter archive.
+
+        :param file_path: Path to the .tar.gz Teleporter file.
+        :param import_options: Dictionary of import options (default: import everything).
+        :return: API response.
+        """
+        with open(file_path, "rb") as file:
+            files = {"file": (file_path, file, "application/gzip")}
+            data = {"import": json.dumps(import_options)} if import_options else {}
+
+            return self.connection.post("teleporter", files=files, data=data)
+
+    def get_config(self, detailed=False):
+        """
+        Get the current configuration of Pi-hole.
+
+        :param detailed: Boolean flag to get detailed configuration.
+        :return: API response containing configuration data.
+        """
+        return self.connection.get("config", params={"detailed": str(detailed).lower()})
+
+    def update_config(self, config_changes):
+        """
+        Modify the Pi-hole configuration.
+
+        :param config_changes: Dictionary containing configuration updates.
+        :return: API response confirming changes.
+        """
+        payload = {"config": config_changes}
+        return self.connection.patch("config", data=payload)
+
+    def get_config_section(self, element, detailed=False):
+        """
+        Get a specific part of the Pi-hole configuration.
+
+        :param element: The section of the configuration to retrieve.
+        :param detailed: Boolean flag for detailed output.
+        :return: API response with the requested config section.
+        """
+        return self.connection.get(f"config/{element}", params={"detailed": str(detailed).lower()})
+
+    def add_config_item(self, element, value):
+        """
+        Add an item to a configuration array.
+
+        :param element: The config section to modify.
+        :param value: The value to add.
+        :return: API response confirming the addition.
+        """
+        return self.connection.put(f"config/{element}/{value}")
+
+    def delete_config_item(self, element, value):
+        """
+        Delete an item from a configuration array.
+
+        :param element: The config section to modify.
+        :param value: The value to remove.
+        :return: API response confirming the deletion.
+        """
+        return self.connection.delete(f"config/{element}/{value}")

pihole6api-0.1.0/src/pihole6api/conn.py

@@ -0,0 +1,127 @@
+import requests
+import urllib3
+from urllib.parse import urljoin
+import warnings
+
+# Suppress InsecureRequestWarning
+urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+warnings.simplefilter("ignore", category=urllib3.exceptions.InsecureRequestWarning)
+
+class PiHole6Connection:
+    def __init__(self, base_url, password):
+        """
+        Initialize the Pi-hole connection client.
+
+        :param base_url: The base URL of the Pi-hole API (e.g., "http://pi.hole/api/")
+        :param password: The password for authentication (or an application password)
+        """
+        self.base_url = base_url.rstrip("/") + "/api/"
+        self.password = password
+        self.session_id = None
+        self.csrf_token = None
+        self.validity = None
+
+        # Authenticate upon initialization
+        self._authenticate()
+
+    def _authenticate(self):
+        """Authenticate with the Pi-hole API and store session ID and CSRF token."""
+        auth_url = urljoin(self.base_url, "auth")
+        payload = {"password": self.password}
+
+        response = requests.post(auth_url, json=payload, verify=False)
+        
+        if response.status_code == 200:
+            data = response.json()
+            if "session" in data and data["session"]["valid"]:
+                self.session_id = data["session"]["sid"]
+                self.csrf_token = data["session"]["csrf"]
+                self.validity = data["session"]["validity"]
+            else:
+                raise Exception("Authentication failed: Invalid session response")
+        else:
+            raise Exception(f"Authentication failed: {response.json().get('error', {}).get('message', 'Unknown error')}")
+
+    def _get_headers(self):
+        """Return headers including the authentication SID and CSRF token."""
+        if not self.session_id or not self.csrf_token:
+            self._authenticate()
+
+        return {
+            "X-FTL-SID": self.session_id,
+            "X-FTL-CSRF": self.csrf_token
+        }
+
+    def _do_call(self, method, endpoint, params=None, data=None, files=None, is_binary=False):
+        """Internal method to send an authenticated request to the Pi-hole API."""
+        url = f"{self.base_url}{endpoint}"
+        headers = self._get_headers()
+
+        # Convert dictionary to form-encoded string if sending multipart
+        request_data = None if files else data
+        form_data = data if files else None  # Ensure correct encoding
+
+        response = requests.request(
+            method,
+            url,
+            headers=headers,
+            params=params,
+            json=request_data,
+            files=files,
+            data=form_data,
+            verify=False
+        )
+
+        if response.status_code == 401:
+            self._authenticate()
+            headers = self._get_headers()
+            response = requests.request(
+                method,
+                url,
+                headers=headers,
+                params=params,
+                json=request_data,
+                files=files,
+                data=form_data,
+                verify=False
+            )
+
+        # Handle 4xx responses gracefully
+        if 400 <= response.status_code < 500:
+            try:
+                return response.json()
+            except requests.exceptions.JSONDecodeError:
+                return {"error": f"HTTP {response.status_code}: {response.reason}"}
+
+        response.raise_for_status()
+
+        if is_binary:
+            return response.content  # Return raw binary content (e.g., for file exports)
+
+        if not response.content.strip():
+            return {}  # Handle empty response
+
+        try:
+            return response.json()  # Attempt to parse JSON
+        except requests.exceptions.JSONDecodeError:
+            return response.text  # Return raw text as fallback
+
+    def get(self, endpoint, params=None, is_binary=False):
+        """Send a GET request."""
+        return self._do_call("GET", endpoint, params=params, is_binary=is_binary)
+
+    def post(self, endpoint, data=None, files=None):
+        """Send a POST request."""
+        return self._do_call("POST", endpoint, data=data, files=files)
+
+    def put(self, endpoint, data=None):
+        """Send a PUT request."""
+        return self._do_call("PUT", endpoint, data=data)
+
+    def delete(self, endpoint, params=None, data=None):
+        """Send a DELETE request."""
+        return self._do_call("DELETE", endpoint, params=params, data=data)
+
+    def patch(self, endpoint, data=None):
+        """Send a PATCH request."""
+        return self._do_call("PATCH", endpoint, data=data)

pihole6api-0.1.0/src/pihole6api/dhcp.py

@@ -0,0 +1,21 @@
+class PiHole6Dhcp:
+    def __init__(self, connection):
+        """Handles Pi-hole DHCP API endpoints."""
+        self.connection = connection
+
+    def get_leases(self):
+        """
+        Retrieve currently active DHCP leases.
+
+        :return: API response containing active DHCP leases.
+        """
+        return self.connection.get("dhcp/leases")
+
+    def remove_lease(self, ip):
+        """
+        Remove a specific DHCP lease by IP address.
+
+        :param ip: The IP address of the lease to remove.
+        :return: API response confirming removal.
+        """
+        return self.connection.delete(f"dhcp/leases/{ip}")

pihole6api-0.1.0/src/pihole6api/dns_control.py

@@ -0,0 +1,24 @@
+class PiHole6DnsControl:
+    def __init__(self, connection):
+        """
+        Handles Pi-hole DNS control API endpoints.
+        :param connection: Instance of PiHole6Connection for API requests.
+        """
+        self.connection = connection
+
+    def get_blocking_status(self):
+        """Get current blocking status."""
+        return self.connection.get("dns/blocking")
+
+    def set_blocking_status(self, blocking: bool, timer: int = None):
+        """
+        Change current blocking status.
+
+        :param blocking: True to enable blocking, False to disable blocking.
+        :param timer: (Optional) Set a timer in seconds. If None, change is permanent.
+        """
+        payload = {"blocking": blocking}
+        if timer is not None:
+            payload["timer"] = timer
+
+        return self.connection.post("dns/blocking", data=payload)

pihole6api-0.1.0/src/pihole6api/domain_management.py

@@ -0,0 +1,87 @@
+class PiHole6DomainManagement:
+    def __init__(self, connection):
+        """
+        Handles Pi-hole domain management API endpoints.
+        :param connection: Instance of PiHole6Connection for API requests.
+        """
+        self.connection = connection
+
+    def batch_delete_domains(self, domains):
+        """
+        Delete multiple domains.
+
+        :param domains: List of dictionaries with keys "item", "type", and "kind".
+                        Example: [{"item": "example.com", "type": "allow", "kind": "exact"}]
+        """
+        if not isinstance(domains, list):
+            raise ValueError("domains must be a list of dictionaries.")
+
+        return self.connection.post("domains:batchDelete", data=domains)
+
+    def add_domain(self, domain, domain_type, kind, comment=None, groups=None, enabled=True):
+        """
+        Add a new domain to Pi-hole.
+
+        :param domain: Domain name (string or list of strings)
+        :param domain_type: Type of domain ("allow" or "deny")
+        :param kind: Kind of domain ("exact" or "regex")
+        :param comment: Optional comment for the domain
+        :param groups: Optional list of group IDs
+        :param enabled: Whether the domain is enabled (default: True)
+        """
+        if domain_type not in ["allow", "deny"]:
+            raise ValueError("domain_type must be 'allow' or 'deny'.")
+        if kind not in ["exact", "regex"]:
+            raise ValueError("kind must be 'exact' or 'regex'.")
+
+        payload = {
+            "domain": domain if isinstance(domain, list) else [domain],
+            "comment": comment,
+            "groups": groups if groups else [],
+            "enabled": enabled
+        }
+
+        return self.connection.post(f"domains/{domain_type}/{kind}", data=payload)
+
+    def get_domain(self, domain, domain_type, kind):
+        """
+        Retrieve information about a specific domain.
+
+        :param domain: Domain name
+        :param domain_type: Type of domain ("allow" or "deny")
+        :param kind: Kind of domain ("exact" or "regex")
+        """
+        return self.connection.get(f"domains/{domain_type}/{kind}/{domain}")
+
+    def update_domain(self, domain, domain_type, kind, new_type=None, new_kind=None, comment=None, groups=None, enabled=True):
+        """
+        Update or move an existing domain entry.
+
+        :param domain: Domain name
+        :param domain_type: Current type of domain ("allow" or "deny")
+        :param kind: Current kind of domain ("exact" or "regex")
+        :param new_type: New type of domain (optional)
+        :param new_kind: New kind of domain (optional)
+        :param comment: Updated comment (optional)
+        :param groups: Updated list of group IDs (optional)
+        :param enabled: Whether the domain is enabled (default: True)
+        """
+        payload = {
+            "type": new_type if new_type else domain_type,
+            "kind": new_kind if new_kind else kind,
+            "comment": comment,
+            "groups": groups if groups else [],
+            "enabled": enabled
+        }
+
+        return self.connection.put(f"domains/{domain_type}/{kind}/{domain}", data=payload)
+
+    def delete_domain(self, domain, domain_type, kind):
+        """
+        Delete a single domain.
+
+        :param domain: Domain name
+        :param domain_type: Type of domain ("allow" or "deny")
+        :param kind: Kind of domain ("exact" or "regex")
+        """
+        return self.connection.delete(f"domains/{domain_type}/{kind}/{domain}")

pihole6api-0.1.0/src/pihole6api/ftl_info.py

@@ -0,0 +1,75 @@
+class PiHole6FtlInfo:
+    def __init__(self, connection):
+        """
+        Handles Pi-hole FTL and system diagnostics API endpoints.
+        :param connection: Instance of PiHole6Connection for API requests.
+        """
+        self.connection = connection
+
+    def get_endpoints(self):
+        """Retrieve a list of all available API endpoints."""
+        return self.connection.get("endpoints")
+
+    def get_client_info(self):
+        """Retrieve information about the requesting client."""
+        return self.connection.get("info/client")
+
+    def get_database_info(self):
+        """Retrieve long-term database statistics."""
+        return self.connection.get("info/database")
+
+    def get_ftl_info(self):
+        """Retrieve various FTL parameters."""
+        return self.connection.get("info/ftl")
+
+    def get_host_info(self):
+        """Retrieve various host parameters."""
+        return self.connection.get("info/host")
+
+    def get_login_info(self):
+        """Retrieve login page related information."""
+        return self.connection.get("info/login")
+
+    def get_diagnosis_messages(self):
+        """Retrieve all Pi-hole diagnosis messages."""
+        return self.connection.get("info/messages")
+
+    def delete_diagnosis_message(self, message_id):
+        """
+        Delete a specific Pi-hole diagnosis message.
+
+        :param message_id: ID of the diagnosis message to delete.
+        """
+        return self.connection.delete(f"info/messages/{message_id}")
+
+    def get_diagnosis_message_count(self):
+        """Retrieve the count of Pi-hole diagnosis messages."""
+        return self.connection.get("info/messages/count")
+
+    def get_metrics_info(self):
+        """Retrieve various system metrics."""
+        return self.connection.get("info/metrics")
+
+    def get_sensors_info(self):
+        """Retrieve various sensor data."""
+        return self.connection.get("info/sensors")
+
+    def get_system_info(self):
+        """Retrieve various system parameters."""
+        return self.connection.get("info/system")
+
+    def get_version(self):
+        """Retrieve Pi-hole version details."""
+        return self.connection.get("info/version")
+
+    def get_dnsmasq_logs(self):
+        """Retrieve DNS log content."""
+        return self.connection.get("logs/dnsmasq")
+
+    def get_ftl_logs(self):
+        """Retrieve FTL log content."""
+        return self.connection.get("logs/ftl")
+
+    def get_webserver_logs(self):
+        """Retrieve webserver log content."""
+        return self.connection.get("logs/webserver")

pihole6api-0.1.0/src/pihole6api/group_management.py

@@ -0,0 +1,67 @@
+class PiHole6GroupManagement:
+    def __init__(self, connection):
+        """
+        Handles Pi-hole group management API endpoints.
+        :param connection: Instance of PiHole6Connection for API requests.
+        """
+        self.connection = connection
+
+    def add_group(self, name, comment=None, enabled=True):
+        """
+        Create a new group.
+
+        :param name: Name of the new group (string or list of strings).
+        :param comment: Optional comment describing the group.
+        :param enabled: Whether the group is enabled (default: True).
+        """
+        payload = {
+            "name": name if isinstance(name, list) else [name],
+            "comment": comment,
+            "enabled": enabled
+        }
+        return self.connection.post("groups", data=payload)
+
+    def batch_delete_groups(self, group_names):
+        """
+        Delete multiple groups.
+
+        :param group_names: List of group names to delete.
+        """
+        if not isinstance(group_names, list):
+            raise ValueError("group_names must be a list of group names.")
+        
+        payload = [{"item": name} for name in group_names]
+        return self.connection.post("groups:batchDelete", data=payload)
+
+
+    def get_group(self, name):
+        """
+        Retrieve information about a specific group.
+
+        :param name: Name of the group to fetch.
+        """
+        return self.connection.get(f"groups/{name}")
+
+    def update_group(self, name, new_name=None, comment=None, enabled=True):
+        """
+        Update or rename an existing group.
+
+        :param name: Current name of the group.
+        :param new_name: New name for the group (optional).
+        :param comment: Updated comment for the group (optional).
+        :param enabled: Whether the group is enabled (default: True).
+        """
+        payload = {
+            "name": new_name if new_name else name,
+            "comment": comment,
+            "enabled": enabled
+        }
+        return self.connection.put(f"groups/{name}", data=payload)
+
+    def delete_group(self, name):
+        """
+        Delete a group.
+
+        :param name: Name of the group to delete.
+        """
+        return self.connection.delete(f"groups/{name}")

pihole6api-0.1.0/src/pihole6api/list_management.py

@@ -0,0 +1,94 @@
+import urllib.parse
+
+class PiHole6ListManagement:
+    def __init__(self, connection):
+        """
+        Handles Pi-hole list management API endpoints.
+        :param connection: Instance of PiHole6Connection for API requests.
+        """
+        self.connection = connection
+
+    def add_list(self, address, list_type, comment=None, groups=None, enabled=True):
+        """
+        Add a new list to Pi-hole.
+
+        :param address: URL of the blocklist/allowlist.
+        :param list_type: Type of list ("allow" or "block").
+        :param comment: Optional comment for the list.
+        :param groups: Optional list of group IDs.
+        :param enabled: Whether the list is enabled (default: True).
+        """
+        if list_type not in ["allow", "block"]:
+            raise ValueError("list_type must be 'allow' or 'block'.")
+
+        payload = {
+            "address": address if isinstance(address, list) else [address],
+            "type": list_type,
+            "comment": comment,
+            "groups": groups if groups else [],
+            "enabled": enabled
+        }
+
+        return self.connection.post("lists", data=payload)
+
+    def batch_delete_lists(self, lists):
+        """
+        Delete multiple lists.
+
+        :param lists: List of dictionaries with keys "address" and "type".
+                      Example: [{"address": "https://example.com/blocklist.txt", "type": "block"}]
+        """
+        if not isinstance(lists, list):
+            raise ValueError("lists must be a list of dictionaries.")
+
+        return self.connection.post("lists:batchDelete", data=lists)
+
+    def get_list(self, address, list_type):
+        """
+        Retrieve information about a specific list.
+
+        :param address: URL of the blocklist/allowlist.
+        :param list_type: The type of list ("allow" or "block").
+        """
+        encoded_address = urllib.parse.quote(address, safe="")
+        params = {"type": list_type}
+        return self.connection.get(f"lists/{encoded_address}")
+
+    def update_list(self, address, list_type=None, comment=None, groups=None, enabled=True):
+        """
+        Update an existing list.
+
+        :param address: URL of the blocklist/allowlist.
+        :param list_type: Type of list ("allow" or "block") (optional).
+        :param comment: Updated comment (optional).
+        :param groups: Updated list of group IDs (optional).
+        :param enabled: Whether the list is enabled (default: True).
+        """
+        encoded_address = urllib.parse.quote(address, safe="")
+        payload = {
+            "type": list_type,
+            "comment": comment,
+            "groups": groups if groups else [],
+            "enabled": enabled
+        }
+
+        return self.connection.put(f"lists/{encoded_address}", data=payload)
+
+    def delete_list(self, address, list_type):
+        """
+        Delete a specific list entry.
+
+        :param address: The URL of the list to delete.
+        :param list_type: The type of list ("allow" or "block").
+        """
+        encoded_address = urllib.parse.quote(address, safe="")
+        params = {"type": list_type}
+        return self.connection.delete(f"lists/{encoded_address}", params=params)
+
+    def search_list(self, domain):
+        """
+        Search for a domain in Pi-hole's lists.
+
+        :param domain: Domain to search for.
+        """
+        return self.connection.get(f"search/{domain}")

pihole6api-0.1.0/src/pihole6api/metrics.py

@@ -0,0 +1,79 @@
+class PiHole6Metrics:
+    def __init__(self, connection):
+        """
+        Handles Pi-hole metrics and stats API endpoints.
+        :param connection: Instance of PiHole6Connection for API requests.
+        """
+        self.connection = connection
+
+    # History API Endpoints
+    def get_history(self):
+        """Get activity graph data"""
+        return self.connection.get("history")
+
+    def get_history_clients(self):
+        """Get per-client activity graph data"""
+        return self.connection.get("history/clients")
+
+    def get_history_database(self):
+        """Get long-term activity graph data"""
+        return self.connection.get("history/database")
+
+    def get_history_database_clients(self):
+        """Get per-client long-term activity graph data"""
+        return self.connection.get("history/database/clients")
+
+    # Query API Endpoints
+    def get_queries(self):
+        """Get query log"""
+        return self.connection.get("queries")
+
+    def get_query_suggestions(self):
+        """Get query filter suggestions"""
+        return self.connection.get("queries/suggestions")
+
+    # Stats Database API Endpoints
+    def get_stats_database_query_types(self):
+        """Get query types (long-term database)"""
+        return self.connection.get("stats/database/query_types")
+
+    def get_stats_database_summary(self):
+        """Get database content details"""
+        return self.connection.get("stats/database/summary")
+
+    def get_stats_database_top_clients(self):
+        """Get top clients (long-term database)"""
+        return self.connection.get("stats/database/top_clients")
+
+    def get_stats_database_top_domains(self):
+        """Get top domains (long-term database)"""
+        return self.connection.get("stats/database/top_domains")
+
+    def get_stats_database_upstreams(self):
+        """Get upstream metrics (long-term database)"""
+        return self.connection.get("stats/database/upstreams")
+
+    # Stats API Endpoints
+    def get_stats_query_types(self):
+        """Get current query types"""
+        return self.connection.get("stats/query_types")
+
+    def get_stats_recent_blocked(self):
+        """Get most recently blocked domain"""
+        return self.connection.get("stats/recent_blocked")
+
+    def get_stats_summary(self):
+        """Get an overview of Pi-hole activity"""
+        return self.connection.get("stats/summary")
+
+    def get_stats_top_clients(self):
+        """Get top clients"""
+        return self.connection.get("stats/top_clients")
+
+    def get_stats_top_domains(self):
+        """Get top domains"""
+        return self.connection.get("stats/top_domains")
+
+    def get_stats_upstreams(self):
+        """Get upstream destinations"""
+        return self.connection.get("stats/upstreams")

pihole6api-0.1.0/src/pihole6api/network_info.py

@@ -0,0 +1,28 @@
+class PiHole6NetworkInfo:
+    def __init__(self, connection):
+        """Handles Pi-hole network information API endpoints."""
+        self.connection = connection
+
+    def get_devices(self):
+        """Get information about devices on the local network."""
+        return self.connection.get("network/devices")
+
+    def delete_device(self, device_id):
+        """
+        Delete a device from the network table.
+
+        :param device_id: The ID of the device to delete.
+        """
+        return self.connection.delete(f"network/devices/{device_id}")
+
+    def get_gateway(self):
+        """Get information about the gateway of the Pi-hole."""
+        return self.connection.get("network/gateway")
+
+    def get_interfaces(self):
+        """Get information about network interfaces of the Pi-hole."""
+        return self.connection.get("network/interfaces")
+
+    def get_routes(self):
+        """Get information about network routes of the Pi-hole."""
+        return self.connection.get("network/routes")

pihole6api-0.1.0/src/pihole6api.egg-info/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.2
+Name: pihole6api
+Version: 0.1.0
+Summary: Python API Client for Pi-hole 6
+Author-email: Shane Barbetta <shane@barbetta.me>
+License: MIT
+Project-URL: Homepage, https://github.com/sbarbett/pihole6api
+Project-URL: Documentation, https://github.com/sbarbett/pihole6api
+Project-URL: Source, https://github.com/sbarbett/pihole6api
+Project-URL: Issues, https://github.com/sbarbett/pihole6api/issues
+Keywords: pihole,dns,adblocking,api,client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.26.0
+
+# pihole6api
+
+This package provides a simple, modular SDK for the PiHole 6 REST API.
+
+## Features
+
+* Automatically handles authentication and renewal
+* Gracefully error management
+* Logically organized modules
+* Easily maintained
+
+## Installation
+
+**Install using `pip` or `pipx`:**
+
+```bash
+pip install pihole6api
+```
+
+**Install from source:**
+
+```bash
+git clone https://github.com/sbarbett/pihole6api.git
+cd pihole6api
+pip install -e .
+```
+
+## Quick Start
+
+### Initialize the Client
+
+```python
+from pihole6api.client import PiHole6Client
+client = PiHole6Client("https://your-pihole.local/", "your-password")
+```
+
+### Example Usage
+
+#### Get Pi-Hole Metrics
+
+```python
+history = client.metrics.get_history()
+print(history)  # {'history': [{'timestamp': 1740120900, 'total': 0, 'cached': 0 ...}]}
+queries = client.metrics.get_queries()
+print(queries)
+```
+
+#### Enable/Disable Blocking
+
+```python
+client.dns_control.set_blocking_status(False, 60)
+print(client.dns_control.get_blocking_status()) # {'blocking': 'disabled', 'timer': 60 ...}
+```
+
+#### Manage Groups
+
+```python
+client.group_management.add_group("Custom Group", comment="For testing")
+client.group_management.delete_group("Custom Group")
+```
+
+#### Manage Domains
+
+```python
+client.domain_management.add_domain("ads.example.com", "deny", "exact")
+client.domain_management.delete_domain("ads.example.com", "deny", "exact")
+```
+
+#### Manage Links
+
+```python
+client.list_management.add_list("https://example.com/blocklist.txt", "block")
+client.list_management.delete_list("https://example.com/blocklist.txt", "block")
+```
+
+#### Export/Import PiHole Settings
+
+```python
+# Export settings and save as a .zip file
+with open("pihole-settings.zip", "wb") as f:
+    f.write(client.config.export_settings())
+
+client.config.import_settings("pihole-settings.zip", {"config": True, "gravity": {"group": True}})
+```
+
+#### Flush Logs & Restart DNS
+
+```python
+client.actions.flush_logs()
+client.actions.restart_dns()
+```
+
+## API Modules
+
+| Module                | Description |
+|----------------------|-------------|
+| `metrics`           | Query history, top clients/domains, DNS stats |
+| `dns_control`       | Enable/disable blocking |
+| `group_management`  | Create, update, and delete groups |
+| `domain_management` | Allow/block domains (exact & regex) |
+| `client_management` | Manage client-specific rules |
+| `list_management`   | Manage blocklists (Adlists) |
+| `config`            | Modify Pi-hole configuration |
+| `ftl_info`          | Get Pi-hole core process (FTL) info |
+| `dhcp`              | Manage DHCP leases |
+| `network_info`      | View network devices, interfaces, routes |
+| `actions`           | Flush logs, restart services |
+| `padd`              | Fetch summarized data for PADD |
+
+## License
+
+This project is license under the [MIT license](LICENSE).

pihole6api-0.1.0/src/pihole6api.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+LICENSE
+README.md
+pyproject.toml
+src/pihole6api/__init__.py
+src/pihole6api/actions.py
+src/pihole6api/client.py
+src/pihole6api/client_management.py
+src/pihole6api/config.py
+src/pihole6api/conn.py
+src/pihole6api/dhcp.py
+src/pihole6api/dns_control.py
+src/pihole6api/domain_management.py
+src/pihole6api/ftl_info.py
+src/pihole6api/group_management.py
+src/pihole6api/list_management.py
+src/pihole6api/metrics.py
+src/pihole6api/network_info.py
+src/pihole6api.egg-info/PKG-INFO
+src/pihole6api.egg-info/SOURCES.txt
+src/pihole6api.egg-info/dependency_links.txt
+src/pihole6api.egg-info/requires.txt
+src/pihole6api.egg-info/top_level.txt

pihole6api-0.1.0/src/pihole6api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pihole6api-0.1.0/src/pihole6api.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.26.0

pihole6api-0.1.0/src/pihole6api.egg-info/top_level.txt

@@ -0,0 +1 @@
+pihole6api