pihole6api 0.1.0__tar.gz → 0.1.2__tar.gz

{pihole6api-0.1.0/src/pihole6api.egg-info → pihole6api-0.1.2}/PKG-INFO

@@ -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 → pihole6api-0.1.2}/README.md

@@ -1,4 +1,4 @@
-# pihole6api
+# 🍓 pihole6api
 
 This package provides a simple, modular SDK for the PiHole 6 REST API.
 
@@ -30,7 +30,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")
 ```
 
@@ -109,4 +109,4 @@ client.actions.restart_dns()
 
 ## License
 
-This project is license under the [MIT license](LICENSE).
+This project is license under the [MIT license](LICENSE).

{pihole6api-0.1.0 → pihole6api-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pihole6api"
-version = "0.1.0"
+version = "0.1.2"
 description = "Python API Client for Pi-hole 6"
 authors = [{name = "Shane Barbetta", email = "shane@barbetta.me"}]
 license = {text = "MIT"}

{pihole6api-0.1.0 → pihole6api-0.1.2}/src/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-0.1.0 → pihole6api-0.1.2}/src/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-0.1.0 → pihole6api-0.1.2}/src/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-0.1.2/src/pihole6api/metrics.py

@@ -0,0 +1,189 @@
+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, clients=20):
+        """
+        Get per-client activity graph data
+
+        :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(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, 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, 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_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_clients(self, start, end, blocked=None, count=None):
+        """
+        Get top clients (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_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, 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, 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"""
+        return self.connection.get("stats/upstreams")

{pihole6api-0.1.0 → pihole6api-0.1.2/src/pihole6api.egg-info}/PKG-INFO

@@ -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/src/pihole6api/metrics.py

@@ -1,79 +0,0 @@
-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")