feat(sdk): add graph traversal support for Infrahub 1.10+#1090
Open
minitriga wants to merge 3 commits into
Open
feat(sdk): add graph traversal support for Infrahub 1.10+#1090minitriga wants to merge 3 commits into
minitriga wants to merge 3 commits into
Conversation
Add traverse_paths(), path_exists(), and reachable_nodes() client methods (with sync equivalents) for discovering how nodes are connected without knowing the relationship path in advance. - traverse_paths: shortest path(s) between a source and destination node - path_exists: boolean convenience wrapper for checks - reachable_nodes: nodes of given kinds reachable from a source Source/destination accept node ids or InfrahubNode instances; kind filters accept kind strings or protocol classes; each result PathNode exposes .fetch() to resolve the full node (store-backed). Calling against a pre-1.10 server raises a clear VersionNotSupportedError. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
the
type/documentation
Deploying infrahub-sdk-python with
|
| Latest commit: |
0415f11
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://2d0b25d1.infrahub-sdk-python.pages.dev |
| Branch Preview URL: | https://infp-531-graph-traversal.infrahub-sdk-python.pages.dev |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
3 issues found across 38 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="infrahub_sdk/schema/__init__.py">
<violation number="1">
P3: `_get_schema_name` accepts `CoreNodeBase` but then unconditionally reads `schema.save`, which can crash with `AttributeError`. Guard for `save` presence (or narrower subclass) so invalid inputs consistently raise `ValueError`.</violation>
</file>
<file name="infrahub_sdk/node/related_node.py">
<violation number="1">
P2: `hasattr(data, "_schema")` is too broad for node detection. It can accept non-node objects and defer failure to later peer access paths.</violation>
</file>
<file name="docs/docs/python-sdk/sdk_ref/infrahub_sdk/client.mdx">
<violation number="1" location="docs/docs/python-sdk/sdk_ref/infrahub_sdk/client.mdx:125">
P3: Public docs omit the new keyword-only traversal arguments, so the reference page misstates the API surface for graph traversal.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| @@ -119,6 +119,64 @@ count(self, kind: str | type[SchemaType], at: Timestamp | None = None, branch: s | |||
|
|
|||
There was a problem hiding this comment.
P3: Public docs omit the new keyword-only traversal arguments, so the reference page misstates the API surface for graph traversal.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/docs/python-sdk/sdk_ref/infrahub_sdk/client.mdx, line 125:
<comment>Public docs omit the new keyword-only traversal arguments, so the reference page misstates the API surface for graph traversal.</comment>
<file context>
@@ -119,6 +119,64 @@ count(self, kind: str | type[SchemaType], at: Timestamp | None = None, branch: s
+#### `traverse_paths`
+
+```python
+traverse_paths(self, source: str | InfrahubNode, destination: str | InfrahubNode) -> PathTraversalResult
+```
+
</file context>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The async/sync signature parity test matches annotation strings against a known-equivalence map. Add the new traversal parameter annotations (str | InfrahubNode, list[str | type[SchemaType]] and its optional variant) so traverse_paths/path_exists/reachable_nodes pass the parity check. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Codecov Report❌ Patch coverage is
@@ Coverage Diff @@
## develop #1090 +/- ##
===========================================
- Coverage 82.32% 82.05% -0.27%
===========================================
Files 135 138 +3
Lines 11992 11859 -133
Branches 1793 1783 -10
===========================================
- Hits 9872 9731 -141
- Misses 1571 1581 +10
+ Partials 549 547 -2
Flags with carried forward coverage won't be shown. Click here to find out more.
... and 2 files with indirect coverage changes 🚀 New features to boost your workflow:
|
ajtmccarty
approved these changes
Jun 18, 2026
ajtmccarty
left a comment
ajtmccarty
left a comment
Contributor
There was a problem hiding this comment.
looks good. few small comments
|
|
||
| ### Constraining the traversal | ||
|
|
||
| All limits and filters are optional; when omitted, the server applies its own defaults. Unknown kinds (for example IP namespaces) are excluded by default and reported back in `result.excluded_kinds`. |
Contributor
There was a problem hiding this comment.
I don't know exactly what "Unknown kinds" means here. Any IP namespaces are excluded by default b/c they act as hubs and are generally not valuable in this kind of path tracing (although they can be re-included using included_kinds). other internal namespaces are also excluded by default: Builtin, Internal, Core, etc.
|
|
||
| ### Detecting truncated results | ||
|
|
||
| The server caps the number of paths/results. Compare `count` to your requested limit to know whether more may exist: |
Contributor
There was a problem hiding this comment.
the count is actually always the number of paths returned for either of the path traversal queries. it won't be a reliable method for determining if the max_targets was reached. that would require checking the UUIDs of the start objects for each path
| ``source`` accepts either a node UUID string or an ``InfrahubNode`` instance. | ||
| ``target_kinds`` accepts kind-name strings and/or generated protocol classes. | ||
|
|
||
| Requires Infrahub 1.10 or later. See https://docs.infrahub.app for details. |
Contributor
There was a problem hiding this comment.
is this docs link actually helpful?
| if isinstance(node, str): | ||
| return node | ||
| if node.id is None: | ||
| raise Error("Cannot use a node without an id as a traversal source or destination.") |
Contributor
There was a problem hiding this comment.
the function name is pretty generic but the error message is specific to path traversal. I think this method should raise some sort of NodeNotSaved error and then the path traversal caller can catch it and raise an error that mentions path traversal if necessary
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
2 participants
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.
Overview
Adds graph-traversal support to the SDK (requires Infrahub 1.10+), letting users discover how nodes are connected without knowing the relationship path in advance. Purely additive — no existing signatures change.
What's new
Three client methods, each with a sync equivalent:
traverse_paths(source, destination, ...)— find the shortest path(s) between two nodes.path_exists(source, destination, ...)— boolean convenience wrapper for checks (requests a single path).reachable_nodes(source, target_kinds, ...)— find every node of given kinds reachable from a source, with the path to each.Ergonomics:
source/destinationaccept a node UUID string or anInfrahubNodeinstance.PathNodeis a lightweight identity exposing.fetch()to resolve the full node (store-backed).VersionNotSupportedErrorinstead of an opaque GraphQL failure.Implementation notes
infrahub_sdk/graph_traversal/package: typed pydantic result models (models.py) and GraphQL query strings + input builders (query.py). Pure logic is isolated so it's unit-tested without HTTP.VersionNotSupportedErrorexception.tasks.py), a how-to guide, generated SDK reference, and a changelog fragment.Testing
pytest tests/unit/sdk/test_graph_traversal.py— 23 passed (pure-logic builders/parsing + client methods mocked at the transport boundary, async + sync).ruff checkclean;lint-docs0 errors.🤖 Generated with Claude Code
Summary by cubic
Adds graph traversal to the Python SDK for Infrahub 1.10+, enabling shortest-path and dependency discovery across any relationships. Supports INFP-531 (Phase 1) by exposing traversal APIs the UI and GraphQL layer can use.
New Features
InfrahubClient.traverse_paths(),reachable_nodes(), andpath_exists()(with sync equivalents) to find shortest paths, discover reachable nodes by kind, and check connectivity.InfrahubNode; kind filters accept strings or protocol classes; results includePathNode.fetch()to resolve full nodes from the client store.VersionNotSupportedErrorwith a clear message.Bug Fixes
operationNamein requests for better tracing.Written for commit 0415f11. Summary will update on new commits.