pihole6api 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

pihole6api/client.py

@@ -41,4 +41,8 @@ class PiHole6Client:
         :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()})
+        return self.connection.get("padd", params={"full": str(full).lower()})
+    
+    def close_session(self):
+        """Close the Pi-hole session by calling the exit method in the connection."""
+        return self.connection.exit()

pihole6api/config.py

@@ -1,4 +1,5 @@
 import json
+import urllib.parse
 
 class PiHole6Configuration:
     def __init__(self, connection):
@@ -77,3 +78,49 @@ class PiHole6Configuration:
         :return: API response confirming the deletion.
         """
         return self.connection.delete(f"config/{element}/{value}")
+
+    def add_local_a_record(self, host, ip):
+        """
+        Add a local A record to Pi-hole.
+
+        :param host: The hostname (e.g., "foo.dev")
+        :param ip: The IP address (e.g., "192.168.1.1")
+        :return: API response
+        """
+        encoded_value = urllib.parse.quote(f"{ip} {host}")
+        return self.connection.put(f"config/dns/hosts/{encoded_value}")
+
+    def remove_local_a_record(self, host, ip):
+        """
+        Remove a local A record from Pi-hole.
+
+        :param host: The hostname (e.g., "foo.dev")
+        :param ip: The IP address (e.g., "192.168.1.1")
+        :return: API response
+        """
+        encoded_value = urllib.parse.quote(f"{ip} {host}")
+        return self.connection.delete(f"config/dns/hosts/{encoded_value}")
+
+    def add_local_cname(self, host, target, ttl=300):
+        """
+        Add a local CNAME record to Pi-hole.
+
+        :param host: The CNAME alias (e.g., "bar.xyz")
+        :param target: The target hostname (e.g., "foo.dev")
+        :param ttl: Time-to-live for the record (default: 300)
+        :return: API response
+        """
+        encoded_value = urllib.parse.quote(f"{host},{target},{ttl}")
+        return self.connection.put(f"config/dns/cnameRecords/{encoded_value}")
+
+    def remove_local_cname(self, host, target, ttl=300):
+        """
+        Remove a local CNAME record from Pi-hole.
+
+        :param host: The CNAME alias (e.g., "bar.xyz")
+        :param target: The target hostname (e.g., "foo.dev")
+        :param ttl: Time-to-live for the record (default: 300)
+        :return: API response
+        """
+        encoded_value = urllib.parse.quote(f"{host},{target},{ttl}")
+        return self.connection.delete(f"config/dns/cnameRecords/{encoded_value}")

pihole6api/conn.py

@@ -124,4 +124,15 @@ class PiHole6Connection:
 
     def patch(self, endpoint, data=None):
         """Send a PATCH request."""
-        return self._do_call("PATCH", endpoint, data=data)
+        return self._do_call("PATCH", endpoint, data=data)
+    
+    def exit(self):
+        """Delete the current session."""
+        response = self.delete("auth")
+
+        # Clear stored session info
+        self.session_id = None
+        self.csrf_token = None
+        self.validity = None
+
+        return response

pihole6api/metrics.py

@@ -11,68 +11,178 @@ class PiHole6Metrics:
         """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_clients(self, clients=20):
+        """
+        Get per-client activity graph data
 
-    def get_history_database(self):
-        """Get long-term activity graph data"""
-        return self.connection.get("history/database")
+        :param num: Number of clients to return, 0 will return all clients
+        """
+        params = {"n": clients}
+        return self.connection.get("history/clients", params=params)
 
-    def get_history_database_clients(self):
-        """Get per-client long-term activity graph data"""
-        return self.connection.get("history/database/clients")
+    def get_history_database(self, start, end):
+        """
+        Get long-term activity graph data
+        
+        :param start: Start date in unix timestamp format
+        :param end: End date in unix timestamp format
+        """
+        params = {"from": start, "until": end}
+        return self.connection.get("history/database", params=params)
+
+    def get_history_database_clients(self, start, end):
+        """
+        Get per-client long-term activity graph data
+        
+        :param start: Start date in unix timestamp format
+        :param end: End date in unix timestamp format
+        """
+        params = {"from": start, "until": end}
+        return self.connection.get("history/database/clients", params=params)
 
     # Query API Endpoints
-    def get_queries(self):
-        """Get query log"""
-        return self.connection.get("queries")
+    def get_queries(self, n=100, from_ts=None, until_ts=None, upstream=None, domain=None, client=None, cursor=None):
+        """
+        Get query log with optional filtering parameters.
+
+        :param int n: Number of queries to retrieve (default: 100).
+        :param int from_ts: Unix timestamp to filter queries from this time onward (optional).
+        :param int until_ts: Unix timestamp to filter queries up to this time (optional).
+        :param str upstream: Filter queries sent to a specific upstream destination (optional).
+        :param str domain: Filter queries for specific domains, supports wildcards `*` (optional).
+        :param str client: Filter queries originating from a specific client (optional).
+        :param str cursor: Cursor for pagination to fetch the next chunk of results (optional).
+        """
+        params = {
+            "n": n,
+            "from": from_ts,
+            "until": until_ts,
+            "upstream": upstream,
+            "domain": domain,
+            "client": client,
+            "cursor": cursor
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+        return self.connection.get("queries", params=params)
+
 
     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_query_types(self, start, end):
+        """
+        Get query types (long-term database)
+        
+        :param start: Start date in unix timestamp format
+        :param end: End date in unix timestamp format
+        """
+        params = {"from": start, "until": end}
+        return self.connection.get("stats/database/query_types", params=params)
 
-    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_summary(self, start, end):
+        """
+        Get database content details
+        
+        :param start: Start date in unix timestamp format
+        :param end: End date in unix timestamp format
+        """
+        params = {"from": start, "until": end}
+        return self.connection.get("stats/database/summary", params=params)
 
-    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_top_clients(self, start, end, blocked=None, count=None):
+        """
+        Get top clients (long-term database).
 
-    def get_stats_database_upstreams(self):
-        """Get upstream metrics (long-term database)"""
-        return self.connection.get("stats/database/upstreams")
+        :param int start: Start date in Unix timestamp format.
+        :param int end: End date in Unix timestamp format.
+        :param bool blocked: Return information about permitted or blocked queries (optional).
+        :param int count: Number of requested items (optional).
+        """
+        params = {
+            "from": start,
+            "until": end,
+            "blocked": str(blocked).lower() if blocked is not None else None,
+            "count": count
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+        return self.connection.get("stats/database/top_clients", params=params)
+
+    def get_stats_database_top_domains(self, start, end, blocked=None, count=None):
+        """
+        Get top domains (long-term database)
+        
+        :param int start: Start date in Unix timestamp format.
+        :param int end: End date in Unix timestamp format.
+        :param bool blocked: Return information about permitted or blocked queries (optional).
+        :param int count: Number of requested items (optional).
+        """
+        params = {
+            "from": start,
+            "until": end,
+            "blocked": str(blocked).lower() if blocked is not None else None,
+            "count": count
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+        return self.connection.get("stats/database/top_domains", params=params)
+
+    def get_stats_database_upstreams(self, start, end):
+        """
+        Get upstream metrics (long-term database)
+        
+        :param start: Start date in unix timestamp format
+        :param end: End date in unix timestamp format
+        """
+        params = {"from": start, "until": end}
+        return self.connection.get("stats/database/upstreams", params=params)
 
     # 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_recent_blocked(self, count=None):
+        """
+        Get most recently blocked domain
+        
+        :param int count: Number of requested items (optional).    
+        """
+        params = {"count": count}
+        params = {k: v for k, v in params.items() if v is not None}
+        return self.connection.get("stats/recent_blocked", params=params)  
 
     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_top_clients(self, blocked=None, count=None):
+        """
+        Get top clients
+        
+        :param bool blocked: Return information about permitted or blocked queries (optional).
+        :param int count: Number of requested items (optional).
+        """
+        params = {
+            "blocked": str(blocked).lower() if blocked is not None else None,
+            "count": count
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+        return self.connection.get("stats/top_clients", params=params)
+
+    def get_stats_top_domains(self, blocked=None, count=None):
+        """
+        Get top domains
+        
+        :param bool blocked: Return information about permitted or blocked queries (optional).
+        :param int count: Number of requested items (optional).
+        """
+        params = {
+            "blocked": str(blocked).lower() if blocked is not None else None,
+            "count": count
+        }
+        params = {k: v for k, v in params.items() if v is not None}
+        return self.connection.get("stats/top_domains", params=params)
 
     def get_stats_upstreams(self):
         """Get upstream destinations"""

{pihole6api-0.1.0.dist-info → pihole6api-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: pihole6api
-Version: 0.1.0
+Version: 0.1.2
 Summary: Python API Client for Pi-hole 6
 Author-email: Shane Barbetta <shane@barbetta.me>
 License: MIT
@@ -23,7 +23,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.26.0
 
-# pihole6api
+# 🍓 pihole6api
 
 This package provides a simple, modular SDK for the PiHole 6 REST API.
 
@@ -55,7 +55,7 @@ pip install -e .
 ### Initialize the Client
 
 ```python
-from pihole6api.client import PiHole6Client
+from pihole6api import PiHole6Client
 client = PiHole6Client("https://your-pihole.local/", "your-password")
 ```
 

{pihole6api-0.1.0.dist-info → pihole6api-0.1.2.dist-info}/RECORD

@@ -1,19 +1,19 @@
 pihole6api/__init__.py,sha256=OKDAH2I6UjXcBmcj6rn5aNg5J60GCUBVFJ-_t83GiVQ,898
 pihole6api/actions.py,sha256=8CBkr8nYfT8yfdCO6F9M9nompaYcFdsaYGiEa1eVDCw,693
-pihole6api/client.py,sha256=IgUjiBUx_EFzQujgQZcX2h9dfDfI83aVeipUeStHWY0,1855
+pihole6api/client.py,sha256=HYdRh3CSZJ0srbkpjIVnLo-iy1avqKDUne5ji2Aq394,2013
 pihole6api/client_management.py,sha256=opPYGrjuW6SiwuxuvoOxnqjpmflU2znKHsqFbGSS3Gg,2439
-pihole6api/config.py,sha256=RlTyIZ0G9K2qZxB6nZgT3HsCn03y7q1qRjVwJ4ZY5Kc,2914
-pihole6api/conn.py,sha256=sYjS8Gvk2GuA482eyvFknTKgeeesLnS5ylI9I4yUNRo,4581
+pihole6api/config.py,sha256=NdBHOudz147oIs5YVR3U4WLvqk3hU3HlZHnshy1NK4g,4680
+pihole6api/conn.py,sha256=ArXgFtb3QG2HeBeDvhEuZ7jcBDR6fW8QorlCF46Y3MM,4840
 pihole6api/dhcp.py,sha256=1A3z-3q9x51-6MOC3JMl7yR_5pHmRxZtMWtPqzWxYm0,629
 pihole6api/dns_control.py,sha256=mxV3AIuGCsx0-1ibpMXor9QUGd_fDFfeaUENPhIK_TY,853
 pihole6api/domain_management.py,sha256=vxhQSG5F8EFDGqtiNkF0H_KOWFMerXaAuJZT0nMa8ec,3492
 pihole6api/ftl_info.py,sha256=e9W9vwkF8nHzjVlHpIMe-55qhhQngMj0swMlp2QNvPg,2540
 pihole6api/group_management.py,sha256=MGHwegw-b9U9PIA-IBzqT-a1kYkpXyjfSXJJJjkyTxc,2225
 pihole6api/list_management.py,sha256=B98FdgsIZhfRJHRxtRmwWsRPJ4rGlhvN-9gFEGdbb-c,3396
-pihole6api/metrics.py,sha256=KgklFtXrO_f2ZnFd6C7tATVPuUJwMl_dGr4Ul5Wgc1k,2758
+pihole6api/metrics.py,sha256=czNyx9tUf2yZi_HnUpqykrtW51c042Rxq3zFl2_GjLY,7379
 pihole6api/network_info.py,sha256=u5NIteFoI-yav05eE6v81-9gs3MeZVBlNCSBS5gzCT8,1006
-pihole6api-0.1.0.dist-info/LICENSE,sha256=hpO6J6J9O1VZxZeHQTxKMTmuobaHbApiZxp279I4xNU,1062
-pihole6api-0.1.0.dist-info/METADATA,sha256=Fefv0L6mqT5fYsBbNLr8uHNS2XBk6bIR0KyFvdCY5Ng,3839
-pihole6api-0.1.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-pihole6api-0.1.0.dist-info/top_level.txt,sha256=Qrh46lxEC54rBR8T53em-tuZLWbmi1SDwL1rOhsgrME,11
-pihole6api-0.1.0.dist-info/RECORD,,
+pihole6api-0.1.2.dist-info/LICENSE,sha256=hpO6J6J9O1VZxZeHQTxKMTmuobaHbApiZxp279I4xNU,1062
+pihole6api-0.1.2.dist-info/METADATA,sha256=0kZSJq4RYKkx6fHMae0Tohtbwm7QVORbYnZ15GJdgPw,3837
+pihole6api-0.1.2.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+pihole6api-0.1.2.dist-info/top_level.txt,sha256=Qrh46lxEC54rBR8T53em-tuZLWbmi1SDwL1rOhsgrME,11
+pihole6api-0.1.2.dist-info/RECORD,,