Enable Pihole API v6 #145890

HarvsG · 2025-05-30T12:12:28Z

Proposed change

Move from #145723
The current version of the pi-hole integration does not support the the update to the pihole API, and this affects many users as can be seen by the issue below.

Some of the sensor endpoints are changed in the new API, significantly, the daily sensors no longer exist. In a sense this is breaking, but since the integrations is currently already broken, I haven't marked this as a breaking change.

Includes a dependency update of python-hole from 0.8.0 to 0.9.0 for V6 API support. The update makes the V6 API the default version and so a dependency upgrade alone would be breaking. In this PR all calls to the library declare the API version explicitly.

Considering that the V6 API was released in February, I think we should consider a deprecation procedure in another pull request after this one is merged.

Python-hole change log:

What's Changed

Type of change

Dependency upgrade
Bugfix (non-breaking change which fixes an issue)
New integration (thank you!)
New feature (which adds functionality to an existing integration)
Deprecation (breaking change to happen in the future)
Breaking change (fix/feature causing existing functionality to break)
Code quality improvements to existing code or addition of tests

Additional information

This PR fixes or closes issue: fixes Pi_hole integration doesn't work on pi_hole V6 #130245, Pi-Hole integration -- API location changed on version 6.0 #138927, Pi-Hole integration using incorrect api url #142124, Provide clarification that this integration only works with version 5.x of pi-hole or earlier. home-assistant.io#37992, no API input is requested #140306
This PR is related to issue:
Link to documentation pull request: Update pi_hole.markdown for API V6 home-assistant.io#39459
Link to developer documentation pull request:
Link to frontend pull request:

Checklist

The code change is tested and works locally.
Local tests pass. Your PR cannot be merged unless tests pass
There is no commented out code in this PR.
I have followed the development checklist
I have followed the perfect PR recommendations
The code has been formatted using Ruff (ruff format homeassistant tests)
Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

The manifest file has all fields filled out correctly.
Updated and included derived files by running: python3 -m script.hassfest.
New or updated dependencies have been added to requirements_all.txt.
Updated by running python3 -m script.gen_requirements_all.
For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.

To help with the load of incoming pull requests:

I have reviewed two other open pull requests in this repository.

home-assistant · 2025-05-30T12:12:34Z

Hey there @shenxn, mind taking a look at this pull request as it has been labeled with an integration (pi_hole) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of pi_hole can trigger bot actions by commenting:

@home-assistant close Closes the pull request.
@home-assistant rename Awesome new title Renames the pull request.
@home-assistant reopen Reopen the pull request.
@home-assistant unassign pi_hole Removes the current integration label and assignees on the pull request, add the integration domain after the command.
@home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component) to the pull request.
@home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component) on the pull request.

homeassistant/components/pi_hole/__init__.py

HarvsG · 2025-05-30T18:04:39Z

homeassistant/components/pi_hole/config_flow.py

@@ -101,25 +104,6 @@ async def async_step_user(
            errors=errors,
        )

-    async def async_step_api_key(


I have removed the API key as a separate step for a few reasons

The info in the previous step is not required to accept an api_key

Due to the ambiguity between V5 and V6 APIs it is not easy to determine connectivity and the API version separately

HarvsG · 2025-05-30T18:06:07Z

homeassistant/components/pi_hole/config_flow.py

+                pi_hole = self._api_by_version(5)
+                await pi_hole.get_data()
+                if pi_hole.data is not None and "error" in pi_hole.data:
+                    raise HoleError(pi_hole.data["error"])  # noqa: TRY301


This lint error feels the exception should be handled in the api - I agree, but sadly it is not as the call returns a valid dictionary (which contains errors)

homeassistant/components/pi_hole/__init__.py

mitchellrj · 2025-06-14T19:19:37Z

homeassistant/components/pi_hole/config_flow.py

@@ -150,20 +135,72 @@ async def async_step_reauth_confirm(
            errors=errors,
        )

-    async def _async_try_connect(self) -> dict[str, str]:
+    def _api_by_version(


Seems like this could be factored out of setup_entry and reused here?

homeassistant/components/pi_hole/config_flow.py

mitchellrj · 2025-06-14T19:25:30Z

homeassistant/components/pi_hole/const.py

@@ -17,3 +19,9 @@
 SERVICE_DISABLE_ATTR_DURATION = "duration"

 MIN_TIME_BETWEEN_UPDATES = timedelta(minutes=5)
+
+VERSION_6_RESPONSE_TO_5_ERROR = {


I understand the reason for this being defined here like this, and that it being here is nice to have rather than essential, but it'd be nice if there was some link to the source in FTL which generated this error for reference, and to use a pattern match on the string, since pi.hole is substituted for the configured hostname.

Link to source added. Now pattern matching used.

homeassistant/components/pi_hole/sensor.py

mitchellrj · 2025-06-14T19:42:52Z

homeassistant/components/pi_hole/strings.json

+  "issues": {
+    "v5_to_v6_migration": {
+      "title": "Recent migration from Pi-hole API v5 to v6",
+      "description": "We have detected that you have likely updated you Pi-hole to a version 6 API from version 5. Some sensors are different in the new API as the daily sensors have been removed and your old API token will be invalid, please provide your new app password by following the re-authentication process in repairs or in Settings -> Devices & services -> Pi-hole"


I think you could word more simply and with less passive voice. Ref Home Assistant docs style guide

Hopefully improved now

homeassistant/components/pi_hole/const.py

mitchellrj

LGTM

HarvsG · 2025-06-20T11:41:22Z

Thanks for the approval.

I've reached the limit of my abilities regarding code coverage and mocking the API. Hopefully it is enough

mitchellrj · 2025-06-25T19:32:35Z

@zweckj could you weigh in on the code coverage aspect?

There's nothing in the developer's guide about 100% coverage being a requirement, the closest I found was "strongly consider adding tests".

mkaatman · 2025-06-25T20:51:26Z

Hopefully we're focusing on tests that add value over 100% coverage!

zweckj · 2025-06-26T18:07:19Z

homeassistant/components/pi_hole/__init__.py

+        await holeV6.authenticate()
+    # Ideally python-hole would raise a specific exception for authentication failures
+    except HoleError as ex_v6:
+        if str(ex_v6) == "Authentication failed: Invalid password":


do we really have to go by exception method here, is there no special type?

Unfortunately, yes. Issue with the upstream library I already commented on.

homeassistant/components/pi_hole/__init__.py

zweckj · 2025-06-26T18:12:21Z

homeassistant/components/pi_hole/__init__.py

+        _LOGGER.debug(
+            "No API version specified, determining Pi-hole API version for %s", host
+        )
+        version = await determine_api_version(hass, dict(entry.data))


we should probably store the determined version in the config entry. That way when it's 6 you know the user has upgraded and you don't need to check it anymore

Isn't that achieved 2 lines later with

hass.config_entries.async_update_entry( entry, data={**entry.data, CONF_API_VERSION: version} )

?

Oh yes, then we are just missing a check so we don’t do it every time unnecessarily

if version is None is the check where version is instantiated as version = entry.data.get(CONF_API_VERSION) a few lines earlier. I could use a walrus as a one liner, if you think that would be clearer?

homeassistant/components/pi_hole/__init__.py

zweckj · 2025-06-26T18:17:02Z

homeassistant/components/pi_hole/config_flow.py

+            try:
+                await pi_hole.get_data()
+                if pi_hole.data is not None and "error" in pi_hole.data:
+                    _LOGGER.debug(


we need 100% coverage for the config flow

homeassistant/components/pi_hole/config_flow.py

zweckj · 2025-06-26T18:18:42Z

homeassistant/components/pi_hole/manifest.json

@@ -6,5 +6,5 @@
  "documentation": "https://www.home-assistant.io/integrations/pi_hole",
  "iot_class": "local_polling",
  "loggers": ["hole"],
-  "requirements": ["hole==0.8.0"]
+  "requirements": ["hole==0.9.0"]


I think I've asked that before, but we can bump that in a prerequisite PR right? (This way we don't trigger the full CI run every time while we work on this rather large PR)

0.9 is a breaking change. To hell with semver apparently.

zweckj · 2025-06-26T18:19:38Z

homeassistant/components/pi_hole/sensor.py

@@ -89,6 +123,21 @@ def __init__(
    def native_value(self) -> StateType:
        """Return the state of the device."""
        try:
-            return round(self.api.data[self.entity_description.key], 2)  # type: ignore[no-any-return]
+            return round(get_nested(self.api.data, self.entity_description.key), 2)


i know this is old, but instead of rounding we shuold set suggested_display_precision in the entity description

fixed in 2eb1a21

zweckj · 2025-06-26T18:30:06Z

homeassistant/components/pi_hole/__init__.py

+                        ir.async_create_issue(
+                            hass,
+                            DOMAIN,
+                            issue_id=f"v5_to_v6_migration_{api.base_url}",
+                            is_fixable=False,
+                            severity=ir.IssueSeverity.ERROR,
+                            translation_key="v5_to_v6_migration",
+                            is_persistent=True,


let's not raise an issue here, you already get a reauth prompt and will need to act. We can log a bit more info

Happy to remove, the procedure for obtaining the auth changes from version 5 to version 6. Version 5 uses an API Key, version 6 uses an app passowrd that is found in a different settings menu. Hence, I thought it would be helpful to provide the user more specific instructions. Happy to remove if you think this is unnecessary.

HarvsG added 8 commits May 30, 2025 11:24

enable v6

92a6906

add version to config flow

735ef29

enable binary sensor

a14983d

update hole version

5af5056

tls or protocol

a925212

enable v6 sensors

4e3377d

enable swtich using common parameter

d06a3b5

strings

d08289f

home-assistant bot added cla-signed integration: pi_hole labels May 30, 2025

home-assistant bot added the Quality Scale: No score label May 30, 2025

HarvsG mentioned this pull request May 30, 2025

Pi-Hole Enable API version 6 #145723

Closed

19 tasks

HarvsG added 11 commits May 30, 2025 13:26

Merge branch 'dev' into piholev6

bb3ada5

tls vs https

56ef96d

unify icons

cf86fec

correct icon error

a73042a

determine api version by trial and errors

53ec387

fix lint

f7a2861

remove api_key step

8b9c5b5

mock v5 and v6 config flow

f8d42ca

Init tests

3dfbf4a

finish fixing tests

4419d29

update requirements

a765301

HarvsG mentioned this pull request May 30, 2025

Pi_hole integration doesn't work on pi_hole V6 #130245

Open

remove pihole from forbidden package as per hassfest

258ca52

HarvsG requested a review from a team as a code owner May 30, 2025 17:53

HarvsG commented May 30, 2025

View reviewed changes

homeassistant/components/pi_hole/__init__.py Outdated Show resolved Hide resolved

HarvsG commented May 30, 2025

View reviewed changes

zweckj added the new-feature label Jun 11, 2025

mitchellrj reviewed Jun 14, 2025

View reviewed changes

HarvsG added 7 commits June 16, 2025 13:17

Adds a comment for about generic exceptiosn

2079d01

pihole if to elif

5c984b3

Use pattern matching for error detection

0a9a510

Better string

7b49b8e

remove unused literal

e986078

Re-factor determine API version

10b6c2b

Imports hole for typing

f1d0e02

HarvsG requested a review from mitchellrj June 16, 2025 15:46

HarvsG marked this pull request as draft June 19, 2025 20:24

HarvsG marked this pull request as ready for review June 19, 2025 20:24

HarvsG added 3 commits June 19, 2025 21:59

minor changes so the tests re-run

c746e56

Merge branch 'dev' into piholev6

e0292be

cover remaining lines in sensor.py

c9b85d4

mitchellrj approved these changes Jun 20, 2025

View reviewed changes

HarvsG added 2 commits June 20, 2025 09:23

Modifies tests only, slightly improves cov

4d1de97

Merge branch 'dev' into piholev6

32da04b

mkaatman approved these changes Jun 22, 2025

View reviewed changes

zweckj requested changes Jun 26, 2025

View reviewed changes

home-assistant bot marked this pull request as draft June 26, 2025 18:49

HarvsG added 6 commits June 30, 2025 17:13

use function abstraction DNRY

6fb2948

Use more specific exceptions

c5de88c

Use try else blocks

c12076c

fix tests

fe6c3fe

set display precision per sensor

2eb1a21

fix most tests

b977d3c

Uh oh!

Enable Pihole API v6 #145890

Are you sure you want to change the base?

Enable Pihole API v6 #145890

Conversation

HarvsG commented May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed change

What's Changed

Type of change

Additional information

Checklist

Uh oh!

home-assistant bot commented May 30, 2025

Uh oh!

Uh oh!

HarvsG May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mitchellrj left a comment

Choose a reason for hiding this comment

Uh oh!

HarvsG commented Jun 20, 2025

Uh oh!

mitchellrj commented Jun 25, 2025

Uh oh!

mkaatman commented Jun 25, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

HarvsG Jun 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

HarvsG commented May 30, 2025 •

edited

Loading

HarvsG May 30, 2025 •

edited

Loading

HarvsG Jun 30, 2025 •

edited

Loading