feat(python-client): get_network_topology + network_topology_updated (schema 13) - #917
Open
MindFreeze wants to merge 4 commits into
Open
feat(python-client): get_network_topology + network_topology_updated (schema 13)#917MindFreeze wants to merge 4 commits into
MindFreeze wants to merge 4 commits into
Conversation
…ted (schema 13) Client counterpart of the server-side network topology API: typed NetworkTopology / node / connection / direction dataclasses (kind, role and strength stay open string sets so newer servers can't break parsing), get_network_topology(refresh=) gated on require_schema=13, and typed parsing of the network_topology_updated event.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds schema-13 network topology support to the Python client, matching the server-side get_network_topology API and typed network_topology_updated event so downstream consumers (e.g., Home Assistant) can consume a parsed topology graph.
Changes:
- Introduces typed wire dataclasses for the schema-13 network topology payload (
NetworkTopology*,TopologyDirectionInfo) and adds the new command/event constants. - Adds
MatterClient.get_network_topology(refresh=False)gated withrequire_schema=13, returning a typedNetworkTopology. - Parses
network_topology_updatedinto a typedNetworkTopologyin event dispatch, with unit tests covering gating, passthrough, forward-compat parsing, and typed event delivery.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| python_client/matter_server/common/models.py | Adds schema-13 network topology dataclasses and registers new EventType / APICommand values. |
| python_client/matter_server/client/client.py | Implements get_network_topology() (schema-gated) and typed parsing/dispatch of network_topology_updated. |
| python_client/tests/test_network_topology.py | Adds unit tests for command construction, schema gating behavior, forward-compatible parsing, and typed event handling. |
MindFreeze
marked this pull request as ready for review
July 23, 2026 13:00
Apollon77
reviewed
Jul 30, 2026
Apollon77
left a comment
Apollon77
left a comment
Collaborator
There was a problem hiding this comment.
Reviewed alongside #832. This side is clean — the open-string-set choice for kind/role/strength, the unknown-key forward-compat test, and the per-command require_schema=13 gate (baseline staying at 11) are all the right calls, and the schema-12 rejection test actually proves the gate rather than assuming it.
Two non-blocking notes:
- Merge order:
require_schema=13is hardcoded whilemainstill reportsSCHEMA_VERSION = 12, so this has to land after #832 (which bumps it and updatespython_client/tests/test_integration.py). No file overlap between the two, so no conflict either way. refresh=Trueis expensive server-side, and #832 currently has no in-flight coalescing (each caller fans out reads to every online node). Callers polling it would multiply that. Docstring note below.
Copilot's strength-in-docstring remark is already addressed in the current head.
…ollable The refresh path costs a per-node attribute read fan-out on the server, so it is a user-initiated action; the push event is the source for keeping a graph current. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Python client counterpart of #832, for the Matter network visualization work in OpenHomeFoundation roadmap #210. Targets the next
matter-python-clientrelease (0.8.0), which Home Assistant core will consume.What's here
NetworkTopology/NetworkTopologyNode/NetworkTopologyConnection/TopologyDirectionInfodataclasses matching the schema-13 wire contract.kind/role/strengthare open string sets (not enums) so a newer server introducing values can never breakdataclass_from_dictparsing.get_network_topology(refresh=False)— gated withrequire_schema=13(raisesServerVersionTooOldagainst older servers); issuing it also opts the connection in to topology pushes, per the server contract.network_topology_updatedreaches subscribers as a parsedNetworkTopology(EventType.NETWORK_TOPOLOGY_UPDATED).The client baseline
SCHEMA_VERSIONstays 11 — per-command gating is the feature gate, so the client keeps working against schema-11/12 servers.Testing
ruff/mypyclean; unit tests cover command translation +refreshpassthrough, the schema-12 rejection path, forward-compat parsing (unknown fields and enum-like values), and typed event dispatch. The full python integration suite stays green.Also verified live against a server build from #832: connect (schema 13) → empty typed graph →
import_test_nodefixtures →network_topology_updatedpush parsed intoNetworkTopology(18 nodes / 16 connections with per-direction LQI/RSSI) →refresh=Trueround-trip.