Introduction & Installation
Relevant source files
The following files were used as context for generating this wiki page:
The Infrahub Python SDK provides a foundational library for programmatically interacting with Infrahub infrastructure management. It abstracts the underlying GraphQL API, allowing you to work with infrastructure data as native Python objects with built-in authentication, batching, caching, and tracking. The SDK supports both asynchronous and synchronous execution modes to accommodate different automation requirements.
Sources: AGENTS.md:3-6, dev/constitution.md:46-52
This SDK serves three primary use cases:
- Internal Automation: Writing transforms, generators, and checks that run within the Infrahub pipeline.
- External Integration: Querying and syncing data between Infrahub and external tools.
- Custom Applications: Using Infrahub as a data backend for standalone Python projects.
Sources: AGENTS.md:12-15
Core Architecture and Design
The SDK follows a layered architecture where reusable logic, including API interaction and domain rules, resides in the core library. The infrahubctl CLI and other first-party consumers act as thin layers over these SDK methods.
Sources: dev/constitution.md:65-72
Async/Sync Parity
The SDK implements a dual-API approach to ensure parity between asynchronous and synchronous consumers. Every public feature is shipped on both InfrahubClient and InfrahubClientSync with matching method names and signatures.
Sources: dev/constitution.md:46-51, AGENTS.md:33-35
Sources: tasks.py:33-38, AGENTS.md:37-41
System Requirements
The SDK supports modern Python environments and requires specific versions for stability and performance.
| Requirement | Supported Versions |
|---|---|
| Python | 3.10 to 3.13 |
| Package Manager | uv (recommended) |
| Pydantic | >= 2.0.0, < 3.0.0 |
| GraphQL Core | >= 3.1, < 3.3 |
| HTTP Client | httpx >= 0.20 |
Sources: pyproject.toml:11-20, AGENTS.md:28, dev/constitution.md:95
Installation and Environment Setup
The project uses uv for dependency management. Follow these steps to set up the development environment:
- Install Dependencies: Install all core, test, and development dependencies.
uv sync --all-groups --all-extras - Verify Tooling: Ensure required documentation and linting tools are available on your PATH.
mdxify: Required for API documentation generation.vale: Required for documentation style checks.rumdl: Required for markdown linting.
Sources: AGENTS.md:20, tasks.py:53-54, tasks.py:171-172, tasks.py:221-222
Optional Components
Additional functionality can be installed via optional dependency groups defined in pyproject.toml.
| Group | Included Functionality |
|---|---|
ctl | Typer, Rich, Jinja2, and other CLI-related tools. |
tests | Pytest, testcontainers, and coverage plugins. |
lint | Ruff, mypy, yamllint, and ty type checker. |
dev | Includes tests, lint, types, and invoke. |
Sources: pyproject.toml:40-90
Project Structure
The SDK is organized into logical modules that separate the client logic from the CLI and testing tools.
infrahub_sdk/
├── client.py # Core InfrahubClient and InfrahubClientSync implementations
├── config.py # Pydantic configuration models
├── node/ # Core data model and node system logic
├── ctl/ # infrahubctl CLI logic and commands
└── pytest_plugin/ # Custom plugin for SDK testing
Sources: AGENTS.md:46-51
Development Workflow
The project uses invoke to manage common development tasks. You must run these commands to ensure compliance with the project's quality gates.
Formatting and Linting
The SDK enforces strict type safety and formatting. signatures must carry type hints, and all linters must pass.
- Format code:
uv run invoke format - Lint all code:
uv run invoke lint-code - Lint documentation:
uv run invoke lint-docs
Sources: AGENTS.md:21-23, dev/constitution.md:78-82, dev/constitution.md:88-91
Documentation Management
Documentation accuracy is non-negotiable. Generated documentation for the CLI and SDK must be updated whenever docstrings or configurations change.
- Generate all docs:
uv run invoke docs-generate - Validate docs:
uv run invoke docs-validate
Sources: AGENTS.md:24-25, dev/constitution.md:107-112, tasks.py:61-63
Sources: AGENTS.md:20-27, dev/constitution.md:120-125
Summary
The Infrahub Python SDK provides a robust, type-safe interface for infrastructure automation. By maintaining async/sync parity and a strictly layered architecture, it ensures that automation logic remains consistent whether executed inside Infrahub's pipelines or within external applications. Proper installation using uv and adherence to the invoke-based development workflow are required to maintain the stability and accuracy of the library.
Sources: dev/constitution.md:14-25, AGENTS.md:3-6