Skip to content

Fix jsonpath namespace collision by vendoring the full jsonpath engine - #324

Open
HenkSnavel wants to merge 2 commits into
vincentwolsink:mainfrom
HenkSnavel:fix/jsonpath-namespace-collision-full-engine
Open

Fix jsonpath namespace collision by vendoring the full jsonpath engine#324
HenkSnavel wants to merge 2 commits into
vincentwolsink:mainfrom
HenkSnavel:fix/jsonpath-namespace-collision-full-engine

Conversation

@HenkSnavel

Copy link
Copy Markdown

Problem

On Home Assistant core 2026.7 (Python 3.14) the integration fails to set up: the
config flow shows a generic "Unexpected error", and even when an entry loads,
only the handful of non-filter sensors get values.

Root cause is a Python import-name collision:

File ".../enphase_envoy/envoy_reader.py", line 410, in _resolve_path
    result = jsonpath(self.data, path)
TypeError: 'module' object is not callable

jsonpath-python is now pulled in transitively by HA core, and it owns the same
top-level jsonpath import name as the PyPI jsonpath (0.82) package this
integration requires. from jsonpath import jsonpath then resolves to a module
instead of the callable. The two packages cannot coexist.

Why not a small dotted-path shim

A minimal key.key[0] resolver is not sufficient — the endpoint paths rely on
filter expressions, e.g.:

production[?(@.type=='inverters' && @.activeCount > 0)].wNow
consumption[?(@.measurementType == 'net-consumption' && @.state == 'enabled')].wNow

These need the real engine's [?(...)] filtering and flattening semantics.

Fix

Vendor the full Goessner jsonpath 0.82 engine (MIT licensed) in-tree as
normalize() + jsonpath(), and drop jsonpath from manifest.json
requirements. No external dependency, no name collision.

The vendored copy was behaviour-tested 1:1 against the original jsonpath
0.82.2 package
across every filter expression the integration uses, so all
existing path strings keep working unchanged.

Notes

`from jsonpath import jsonpath` resolves to a module instead of the callable
when `jsonpath-python` is installed (pulled in transitively by Home Assistant
core 2026.7 / Python 3.14), raising `TypeError: 'module' object is not callable`
and breaking all data fetching. The config flow then fails with a generic
"Unexpected error" and the integration cannot be added; when it does load, only
the few non-filter sensors populate.

PyPI `jsonpath` (0.82) and `jsonpath-python` both own the top-level `jsonpath`
import name and cannot coexist. A simple dotted-path replacement is not enough
because endpoint paths rely on filter expressions such as
`production[?(@.type=='inverters' && @.activeCount > 0)].wNow`.

Vendor the full Goessner `jsonpath` 0.82 engine (MIT) in-tree and drop the
`jsonpath` requirement from the manifest. The vendored copy was behaviour-tested
1:1 against the original package across every filter expression the integration
uses, so all existing path strings work unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@mnederlof

mnederlof commented Jun 30, 2026

Copy link
Copy Markdown
Collaborator

I would suggest putting the vendored jsonpath in a separate file and include that one. then we keep it separate from code we maintain ourselves.

Other than that, great suggestion and thanks!

Per review feedback, keep the vendored Goessner jsonpath engine in a
separate file (jsonpath_vendor.py) so it stays isolated from code we
maintain ourselves. envoy_reader now imports it with
`from .jsonpath_vendor import jsonpath`. No behaviour change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@HenkSnavel

Copy link
Copy Markdown
Author

Done — moved the vendored engine into its own jsonpath_vendor.py and import it via from .jsonpath_vendor import jsonpath. envoy_reader.py no longer carries the engine. Re-tested the filter expressions against the new module; output unchanged.

@vincentwolsink

Copy link
Copy Markdown
Owner

I will first look into just using the library that Home Assistant nowadays imports. At first glance that should not be a problem.

As an alternative we can use the solution proposed here. Thanks.

@vincentwolsink

vincentwolsink commented Jun 30, 2026

Copy link
Copy Markdown
Owner

#326 and #328

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants