Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The Infrahub Python SDK contributing guidelines define the non-negotiable standards and operational workflows required to maintain the library's stability, type safety, and architectural integrity. As a foundational library for infrahubctl and the Infrahub Ansible collection, this SDK requires strict adherence to core principles including async/sync parity, test-first development, and non-negotiable documentation accuracy.
Sources: dev/constitution.md:14-19, AGENTS.md:7-13
Core Development Principles
Contributors must follow seven core articles that govern the SDK's architecture and behavior.
I. Async/Sync Dual API Parity
Every public feature must ship simultaneously on InfrahubClient (async) and InfrahubClientSync (sync). Both versions must maintain matching method names, signatures, and behaviors. Divergence is only permitted if a feature is physically meaningless in one mode and must be documented and justified in the pull request.
Sources: dev/constitution.md:23-31, AGENTS.md:31-35
II. Backward Compatibility and Stability
Stability is tiered based on the export location. Names exported from infrahub_sdk/__init__.py and public methods of those classes are guaranteed. Breaking changes to guaranteed surfaces require a deprecation path:
- Ship a release with
DeprecationWarning. - Keep the path working for at least one MINOR release.
- Remove only in a MAJOR release.
Sources: dev/constitution.md:37-45
III. Layered Architecture
Reusable logic for API interaction, data transformation, and domain rules must reside in the SDK (infrahub_sdk/). Consumer layers like the CLI (infrahub_sdk/ctl/) are restricted to argument parsing, presentation via Rich, and error-to-exit-code handling.
Sources: dev/constitution.md:50-57
IV. Type Safety and Errors
All function signatures must include type hints. Precision is required for exceptions; failure modes must use specific subclasses of infrahub_sdk.exceptions.Error rather than generic exceptions.
Sources: dev/constitution.md:63-71
Development Workflow and Tools
The project uses uv for dependency management and invoke for task automation.
Quality Gates
The following flowchart illustrates the mandatory quality gate process before code can be committed or merged.
The diagram shows the sequential quality gates: Python linting, unit testing, documentation generation, and documentation linting.
Sources: dev/constitution.md:120-125, AGENTS.md:17-26, tasks.py:239-270
Automation Commands
| Command | Purpose |
|---|---|
uv sync --all-groups | Install all dependencies including dev, lint, and test groups. |
uv run invoke format | Automatically formats Python code using Ruff. |
uv run invoke lint | Runs the full pipeline: ruff, yamllint, ty, mypy, rumdl, and vale. |
uv run invoke docs-generate | Regenerates all CLI and SDK reference documentation. |
uv run invoke docs-validate | Verifies committed docs match generated output in CI. |
Sources: AGENTS.md:17-26, tasks.py:220-226, tasks.py:284-304
Testing Requirements
Every feature or bug fix must include tests. Bug fixes require a reproduction test that fails before the fix. Unit tests must be fast and use mocks; integration tests requiring a server utilize testcontainers.
The diagram represents the relationship between testing requirements and the SDK's core principles.
Sources: dev/constitution.md:76-83, AGENTS.md:52-53
Documentation Standards
Documentation accuracy is non-negotiable. Artifacts like protocols.py and generated .mdx files must never be edited by hand.
- Generated Docs: Run
uv run invoke docs-generatewhenever CLI commands, SDK config, or docstrings change. - Hand-written Docs: Must be updated in the same pull request as the behavior change.
- Markdown Style: Use fenced code blocks with language identifiers, add blank lines around lists, and use
textlanguage for directory structures.
Sources: dev/constitution.md:95-103, dev/knowledge/doc-generation.md:1-6, AGENTS.md:41-45
Architectural Constraints
| Category | Requirement |
|---|---|
| Tech Stack | Python 3.10–3.13, Pydantic >= 2.0, HTTPX, GraphQL-core. |
| Type Checking | Mandatory mypy and ty compliance for all signatures. |
| Public API | Changes to signatures require maintainer approval ("Ask first"). |
| Prohibited | Modifying protocols.py or bypassing type checking without justification. |
Sources: dev/constitution.md:108-115, AGENTS.md:58-64, pyproject.toml:13-25
The Infrahub Python SDK maintains high standards to support critical network automation workflows. By following these guidelines, contributors ensure the SDK remains a reliable foundation for all downstream applications.
Sources: dev/constitution.md:129-132