SDK Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Infrahub Python SDK provides a foundational library for programmatic interaction with Infrahub infrastructure management. It abstracts the underlying GraphQL and REST APIs, allowing developers to manipulate infrastructure data as native Python objects. The SDK supports built-in authentication, batching, caching, and tracking to simplify complex infrastructure automation tasks.
Sources: AGENTS.md:3-7, dev/constitution.md:15-18
Core Architectural Principles
Async/Sync Dual API Parity
The SDK enforces a signature contract where every public feature must ship on both InfrahubClient (async) and InfrahubClientSync (sync). These clients must maintain matching method names, signatures, and behaviors. This parity prevents regressions for sync consumers, such as the Infrahub Ansible collection.
Sources: dev/constitution.md:22-31, AGENTS.md:31-36
Layered Architecture
Logic is partitioned to ensure reusability. Reusable logic including API interaction, data transformation, and domain rules resides within infrahub_sdk/. Consumer layers, such as the Command Line Interface (CLI) located in infrahub_sdk/ctl/, act as thin wrappers that handle presentation and input parsing without duplicating SDK logic.
Sources: dev/constitution.md:46-56, AGENTS.md:43-48
System Components
The following diagram illustrates the relationship between the SDK core, its internal modules, and the external consumer layers.
The SDK core manages client implementations and the node system, while consumers interact via the public Client API.
Sources: AGENTS.md:41-48, dev/specs/001-end-user-cli/plan.md:39-65
Key Modules and Packages
| Module | Description |
|---|---|
infrahub_sdk.client | Main implementations for InfrahubClient and InfrahubClientSync. |
infrahub_sdk.node | The core data model and node management system. |
infrahub_sdk.ctl | CLI implementation logic for infrahubctl. |
infrahub_sdk.schema | Repository and node schema configurations. |
infrahub_sdk.graphql | GraphQL query rendering and fragment inlining logic. |
infrahub_sdk.pytest_plugin | Custom plugin for testing Infrahub integrations. |
Sources: AGENTS.md:41-48, tasks.py:127-142, dev/specs/001-end-user-cli/plan.md:39-65
Data Interaction Flow
The SDK utilizes a structured flow to process infrastructure data, moving from user input or code requests through the client to the Infrahub server.
The sequence demonstrates how a simple get request triggers GraphQL rendering and node transformation.
Sources: dev/specs/001-end-user-cli/research.md:32-38, dev/specs/001-end-user-cli/plan.md:92-105
Relationship Handling
The SDK implements a "Human Friendly ID" (HFID) pass-through pattern. When updating or creating relationships, the SDK accepts HFID references directly rather than requiring the client to resolve them to UUIDs via additional round-trips. The server handles the final resolution, which is particularly useful for generic peer types.
Sources: dev/specs/001-end-user-cli/plan.md:92-105, dev/specs/001-end-user-cli/research.md:73-86
Development and Quality Gates
The SDK maintains strict quality standards enforced through a comprehensive linting and testing pipeline.
- Type Safety: All function signatures must carry type hints, passing both
tyandmypychecks. - Documentation: CLI commands and SDK configurations are automatically generated using
invoke docs-generateto ensure the documentation matches the actual code behavior. - Testing: New features must include tests for both async and sync paths. Integration tests utilize
testcontainersfor real server validation.
Sources: dev/constitution.md:59-62, dev/constitution.md:72-81, AGENTS.md:55-65, pyproject.toml:79-88
Build and Tooling
The project uses uv for dependency management and hatchling as the build backend. It targets Python versions 3.10 through 3.14.
Sources: pyproject.toml:1-15, pyproject.toml:440-441
Conclusion
The Infrahub Python SDK architecture prioritizes stability, consistency, and ease of use. By enforcing async/sync parity and a layered design, it serves as a reliable foundation for the infrahubctl CLI, Ansible collections, and custom automation scripts.