API Wrapper: Pi-hole

A basic API wrapper for Pi-hole

Usage Pihole v6 (PiholeAPI.py)

still in progress...

base usage

pih = PiholeAPI() # if pihole.json exists
pih = PiholeAPI(host='10.10.10.10', password='mypassword') # without conf file

auth handling

pih.need_auth() # get a valid session if no auth required
pih._check_auth() # check if wrapper has a valid session stored
pih.do_auth() # (runs automaticly if need) do a auth with password
pih.get_sessions() # get all known sessions (webgui sessions too...)
pih.delete_session() # delet a session by id (collect from get_sessions) - withour parameters it will clear it own sessions
pih.clear_sessions() # delete all sessions without it own
pih.get_app_password() # generate a app password. good for use without TOTP. clears all sessions! (Hint: must be set in config, not implementet at now)

metric handling

pih.get_history() # Get activity graph data of dns querys
pih.get_history_timerange() # bugged!
pih.get_client_history() # Get per-client activity graph data of dns querys
pih.get_client_history_timerange() # bugged!
pih.get_queries() # Request query details.

config handling

pih.get_config() # get full running config
pih.get_config('dns/hosts') # get full tree but only ['dns']['hosts'] be filled
pih.patch_config(config) # send config update, all given elemnts will be overriden. config from get_config can be use.

custom dns handling

pih.get_dns_host(['ip', 'fqdn']) # get a custom dns hosts als list
# return: [[ip, fqdn], [ip, fqdn]]
pih.remove_dns_host(['', 'fqdn'], match_ip=False) # get all custom dns hosts als list which match fqdn only
pih.remove_dns_host(['ip', ''], match_fqdn=False) # get all custom dns hosts als list which match ip only
pih.add_dns_host(['ip', 'fqdn']) # add new custom dns host. checks fist if identical host exists
pih.remove_dns_host(['ip', 'fqdn']) # remove a host which match ip and fqdn
pih.remove_dns_host(['', 'fqdn'], match_ip=False) # remove all hosts which match fqdn only
pih.remove_dns_host(['ip', ''], match_fqdn=False) # remove all hosts which match ip only

Usage Pihole v5 and below (Pihole.py)

Custom DNS

Read, add or delete a custom dns entry (no cname's!)

get_custom_dns()
add_custom_dns(domain, ip)
del_custom_dns(domain, ip)

Custom CNAMES

Same as Custom DNS but for CNAMES only.

get_custom_cname()
add_custom_cname(domain, target)
del_custom_cname(domain, target)

Filter Lists

Read, add or delete a filter list.
Availible lists:

• white
• black
• regex_white
• regex_black

white and black only match exact machtes!

get_list(list, entry)
""" aliases """ 
get_whitelist(entry)
get_regex_whitelist(entry)
get_blacklist(entry)
get_regex_blacklist(entry)

add_to_list(list, entry)
""" aliases """ 
add_to_whitelist(entry)
add_to_regex_whitelist(entry)
add_to_blacklist(entry)
add_to_regex_blacklist(entry)

del_from_list(list, entry)
""" aliases """ 
del_from_whitelist(entry)
del_from_regex_whitelist(entry)
del_from_blacklist(entry)
del_from_regex_blacklist(entry)

Misc

Misc functions for:

• enable / disable filter
• get / check update status
• set temp unit from cpu

enable()
disable()
get_version()
check_updates()
set_tmp_unit(unit)