APiHole

A small Python client for the Pi-hole v6 REST API.

Still on Pi-hole v5? Version 1.0 and later only work with Pi-hole v6. Pin the old release with pip install 'APiHole==0.0.3'. Its source stays on the v5-legacy branch. It is frozen, since Pi-hole v5 is end-of-life.

Install

pip install APiHole

Requires Python 3.9+.

Authentication: use an app password

Pi-hole v6 authenticates with sessions. APiHole logs in with a password, sends the session id with every request, and logs out when you are done.

Don't give scripts your admin password. Create an app password instead:

1. In the Pi-hole web interface, open Settings → Web interface / API.
2. Click Configure app password, copy the generated password, and click Enable new app password.

An app password also skips two-factor authentication. If your Pi-hole has no password at all, pass password=None and APiHole does not log in.

Pi-hole allows only a limited number of API sessions at once. Always use with (or call close()) so the session is released. Scripts that leak sessions eventually get RateLimitError (HTTP 429) until the old sessions expire.

Usage

from APiHole import PiHole

with PiHole("pi.hole", "your-app-password") as ph:
    print(ph.version()["ftl"]["local"]["version"])
    print(ph.summary()["queries"]["blocked"])

    ph.disable(30)          # pause blocking for 30 seconds
    ph.enable()

    ph.deny("ads.example.com", comment="added from script")
    ph.remove_deny("ads.example.com")

Connection options:

PiHole(
    host="192.168.1.2:8080",   # hostname or IP, optional port
    password="...",            # None if the Pi-hole has no password
    https=True,                # default False
    verify=False,              # TLS verification, or a path to a CA bundle
    timeout=10,                # seconds per request
    totp=None,                 # 2FA code, only if not using an app password
)

Methods

For anything else, request(method, path, **kwargs) calls any endpoint under /api with the same session handling and returns the requests.Response. Your Pi-hole documents every endpoint at http://pi.hole/api/docs.

Errors

Every error is a subclass of PiHoleError:

If a session expires in the middle of a script, APiHole logs in again once and retries the request.

APiHole logs to the APiHole logger and never configures logging itself.

Migrating from 0.0.3

1.0 is a clean break. Create a client once, not a static call per request. Whitelist/blacklist are now called allow/deny, as in Pi-hole itself.

Other changes:

• Failures raise exceptions instead of returning None or True.
• The API token from setupVars.conf no longer exists. Use an app password.
• Response shapes follow the v6 API, so dict keys differ from v5.

Development

python -m venv .venv
.venv/bin/pip install -e ".[test]"
.venv/bin/pytest

example.py is a smoke test against a real Pi-hole: PIHOLE_HOST=pi.hole PIHOLE_PASSWORD=... python example.py.

Feedback

Open an issue on GitHub or email shmulik.debby@gmail.com.