lfanew / pihole-client Goto Github PK

Before using this Pihole API client, ensure you have Python and the requests library installed. You can install requests using pip:

pip install requests

or use the requirements file

pip install -r requirements.txt

First, import the PiholeClient from the module:

from pihole_client import PiholeClient

Then, create an instance of the PiholeClient by providing the address of your Pihole server and, optionally, your API token:

client = PiholeClient('http://pi.hole', api_token='YourApiToken')

These methods are used to enable or disable the Pihole ad filtering.

Enables the Pihole filtering.

Example:

client.enable()

Disables the Pihole filtering for a specified duration. If no duration is provided, filtering is disabled indefinitely.

Example:

client.disable(300)  # Disables for 5 minutes

This method checks for updates to the Pihole software.

Example:

client.check_updates()

This method sets the temperature unit displayed in the Pihole interface.

Valid units are 'c', 'f', and 'k'.

Example:

client.set_temperature_unit('f')

These methods are used to add, remove, and retrieve domains from Pihole's various lists.

Adds a domain to one of the specified lists: 'black', 'regex_black', 'white', or 'regex_white'.

Example:

client.add_to_list('black', 'example.com')

Removes a domain from one of the specified lists.

Example:

client.remove_from_list('white', 'example.com')

Retrieves all domains in a specified list.

Example:

domains = client.get_lists('black')

These methods are used to manage custom DNS settings, allowing for specific domain-to-IP address mappings.

Retrieves all custom DNS settings.

Example:

custom_dns = client.get_custom_dns()

Adds a custom DNS entry.

Example:

client.add_custom_dns('example.com', '192.168.1.100')

Deletes a custom DNS entry.

Example:

client.delete_custom_dns('example.com', '192.168.1.100')

These methods are used to manage custom CNAME records, facilitating domain aliasing within the network.

Retrieves all custom CNAME settings.

Example:

custom_cname = client.get_custom_cname()

Adds a custom CNAME entry.

Example:

client.add_custom_cname('portal.example.com', 'internal.example.com')

Deletes a custom CNAME entry.

Example:

client.delete_custom_cname('portal.example.com', 'internal.example.com')

Each of these groups provides a coherent set of functionalities that you can use to manage your Pihole's behavior and settings effectively. Remember to handle any exceptions these methods may throw, especially when dealing with network or API issues.

The software is released under the MIT License. See the LICENSE file for more details.