From 7b26abfdfdb0f3b9dd83a5d7d21c7df902db0b5b Mon Sep 17 00:00:00 2001 From: Baptiste Date: Wed, 25 Feb 2026 14:05:49 +0100 Subject: [PATCH 1/4] Draft overview page sdk --- docs/docs/python-sdk/introduction.mdx | 131 +++++++++++++++++++++----- 1 file changed, 108 insertions(+), 23 deletions(-) diff --git a/docs/docs/python-sdk/introduction.mdx b/docs/docs/python-sdk/introduction.mdx index 26f945ce..f7700031 100644 --- a/docs/docs/python-sdk/introduction.mdx +++ b/docs/docs/python-sdk/introduction.mdx @@ -1,36 +1,121 @@ --- -title: Python SDK +title: Python SDK overview --- -import VideoPlayer from '../../src/components/VideoPlayer'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -The Infrahub Python SDK greatly simplifies how you can interact with Infrahub programmatically. +# Infrahub Python SDK -## Videos +The Infrahub Python SDK is a client library for interacting with [Infrahub](https://docs.infrahub.app/) programmatically. It handles authentication, query construction, and data serialization so you can work with infrastructure data using native Python objects instead of raw API calls. -
- -
+## What you can do with it -## Blog posts +The SDK covers three main use cases: -- [Querying Data in Infrahub via the Python SDK](https://www.opsmill.com/querying-data-in-infrahub-via-the-python-sdk/) -- [Creating, Modifying, and Deleting Data in Infrahub Using the Python SDK](https://www.opsmill.com/infrahub-python-sdk-create-modify-delete/) +- **Automate inside Infrahub** — Write [transforms](https://docs.infrahub.app/guides/python-transform), generators, and checks that run as part of Infrahub's pipeline. +- **Integrate with external systems** — Query and sync data between Infrahub and your existing tools, scripts, or CI/CD pipelines. +- **Build custom applications** — Use Infrahub as a data backend for your own Python projects. -## Guides +Under the hood, tools like `infrahubctl` and the Infrahub Ansible collection both use this SDK. -- [Installing infrahub-sdk](./guides/installation.mdx) -- [Creating a client](./guides/client.mdx) -- [Querying data in Infrahub](./guides/query_data.mdx) -- [Managing nodes](./guides/create_update_delete.mdx) -- [Managing branches](./guides/branches.mdx) -- [Using the client store](./guides/store.mdx) -- [Using the client tracking mode](./guides/tracking.mdx) +## A quick look -## Topics + + -- [Understanding tracking in the Python SDK](./topics/tracking.mdx) +```python +import asyncio +from infrahub_sdk import InfrahubClient -## Reference +async def main(): + client = InfrahubClient() -- [Client configuration](./reference/config.mdx) -- [Python SDK Release Notes](https://github.com/opsmill/infrahub-sdk-python/releases) + # Query all devices + devices = await client.all(kind="InfraDevice") + for device in devices: + print(f"{device.name.value} — {device.site.peer.name.value}") + + # Create a new tag and save it + tag = await client.create(kind="BuiltinTag", name="staging") + await tag.save() + + # Work on a branch + branch = await client.branch.create("update-tags", description="Add staging tags") + +asyncio.run(main()) +``` + + + + +```python +from infrahub_sdk import InfrahubClientSync + +client = InfrahubClientSync() + +# Query all devices +devices = client.all(kind="InfraDevice") +for device in devices: + print(f"{device.name.value} — {device.site.peer.name.value}") + +# Create a new tag and save it +tag = client.create(kind="BuiltinTag", name="staging") +tag.save() + +# Work on a branch +branch = client.branch.create("update-tags", description="Add staging tags") +``` + + + + +Both async and sync clients expose the same API. Choose async for applications that benefit from concurrent I/O (transforms, large-scale sync scripts) and sync for straightforward scripting. + +## Why use the SDK over direct API calls + +| Concern | Raw API | SDK | +|---------|---------|-----| +| Authentication | Manual token management, JWT refresh | Handled automatically | +| Querying | Build GraphQL strings by hand | `client.get()`, `client.all()`, `client.filters()` | +| Mutations | Construct and POST GraphQL mutations | `node.save()`, `node.delete()` | +| Relationships | Navigate nested JSON responses | Access via `node.relationship.peer` | +| Branching | Manage branch headers/parameters | `client.branch.create()`, `client.branch.merge()` | +| Concurrency | Roll your own async batching | Built-in `batch` with concurrency control | +| Schema awareness | Parse schema separately | Schema-driven filters and validation | + +The SDK removes the boilerplate so you can focus on the logic that matters to your infrastructure. + +## Key capabilities + +- **CRUD operations** — Create, read, update, and delete any node type defined in your schema. +- **Filtering** — Query nodes using schema-aware attribute and relationship filters (`name__value`, `site__name__value`, etc.). +- **Branch management** — Create, merge, rebase, and diff branches programmatically. +- **Batch execution** — Group multiple queries into a batch with configurable concurrency limits. +- **Tracking** — Tag operations with identifiers for auditing and idempotent updates. +- **Store** — Cache retrieved nodes locally to reduce redundant queries. +- **GraphQL escape hatch** — Run arbitrary GraphQL queries when the high-level API doesn't cover your use case. + +## Installation + +```bash +pip install infrahub-sdk +``` + +Extras are available for additional functionality: + +```bash +pip install 'infrahub-sdk[ctl]' # Adds the infrahubctl CLI +pip install 'infrahub-sdk[tests]' # Adds the testing framework for transforms and checks +pip install 'infrahub-sdk[all]' # Everything +``` + +See the [installation guide](./guides/installation.mdx) for details. + +## Next steps + +- **[Create and configure a client](./guides/client.mdx)** — Set up authentication, proxy settings, and client options. +- **[Query data](./guides/query_data.mdx)** — Retrieve nodes with filters and GraphQL. +- **[Create, update, and delete nodes](./guides/create_update_delete.mdx)** — Manage infrastructure data programmatically. +- **[Work with branches](./guides/branches.mdx)** — Use Infrahub's branch workflow from Python. +- **[Batch operations](./guides/batch.mdx)** — Optimize performance for bulk operations. +- **[Client configuration reference](./reference/config.mdx)** — All available configuration options. From 58b5dc01c6f7e9ab50f971de8f5581c1a49d0386 Mon Sep 17 00:00:00 2001 From: Baptiste Date: Mon, 30 Mar 2026 16:55:46 +0200 Subject: [PATCH 2/4] refresh sdk overview --- docs/docs/python-sdk/introduction.mdx | 88 +++++++++++++++++++-------- 1 file changed, 61 insertions(+), 27 deletions(-) diff --git a/docs/docs/python-sdk/introduction.mdx b/docs/docs/python-sdk/introduction.mdx index f7700031..6eeb9f64 100644 --- a/docs/docs/python-sdk/introduction.mdx +++ b/docs/docs/python-sdk/introduction.mdx @@ -3,6 +3,8 @@ title: Python SDK overview --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import ReferenceLink from '@site/src/components/Card'; +import VideoPlayer from '@site/src/components/VideoPlayer'; # Infrahub Python SDK @@ -12,11 +14,11 @@ The Infrahub Python SDK is a client library for interacting with [Infrahub](http The SDK covers three main use cases: -- **Automate inside Infrahub** — Write [transforms](https://docs.infrahub.app/guides/python-transform), generators, and checks that run as part of Infrahub's pipeline. -- **Integrate with external systems** — Query and sync data between Infrahub and your existing tools, scripts, or CI/CD pipelines. +- **Automate inside Infrahub** — Write [transforms](https://docs.infrahub.app/topics/transformation), [generators](https://docs.infrahub.app/topics/generator), and [checks](https://docs.infrahub.app/topics/check) that run as part of Infrahub's pipeline. +- **Integrate with external systems** — Query and sync data between Infrahub and your existing tools. - **Build custom applications** — Use Infrahub as a data backend for your own Python projects. -Under the hood, tools like `infrahubctl` and the Infrahub Ansible collection both use this SDK. +Under the hood, tools like [`infrahubctl`](/infrahubctl/infrahubctl) and the [Infrahub Ansible collection](https://docs.infrahub.app/ansible) both use this SDK. ## A quick look @@ -27,22 +29,26 @@ Under the hood, tools like `infrahubctl` and the Infrahub Ansible collection bot import asyncio from infrahub_sdk import InfrahubClient + async def main(): client = InfrahubClient() - # Query all devices - devices = await client.all(kind="InfraDevice") - for device in devices: - print(f"{device.name.value} — {device.site.peer.name.value}") - # Create a new tag and save it - tag = await client.create(kind="BuiltinTag", name="staging") + tag = await client.create( + kind="BuiltinTag", + name="staging", + description="Resources in the staging environment", + ) await tag.save() - # Work on a branch - branch = await client.branch.create("update-tags", description="Add staging tags") + # Query all tags + tags = await client.all(kind="BuiltinTag") + for tag in tags: + print(f"{tag.name.value} — {tag.description.value}") + asyncio.run(main()) + ``` @@ -53,17 +59,19 @@ from infrahub_sdk import InfrahubClientSync client = InfrahubClientSync() -# Query all devices -devices = client.all(kind="InfraDevice") -for device in devices: - print(f"{device.name.value} — {device.site.peer.name.value}") - # Create a new tag and save it -tag = client.create(kind="BuiltinTag", name="staging") +tag = client.create( + kind="BuiltinTag", + name="staging", + description="Resources in the staging environment", +) tag.save() -# Work on a branch -branch = client.branch.create("update-tags", description="Add staging tags") +# Query all tags +tags = client.all(kind="BuiltinTag") +for tag in tags: + print(f"{tag.name.value} — {tag.description.value}") + ``` @@ -74,29 +82,51 @@ Both async and sync clients expose the same API. Choose async for applications t ## Why use the SDK over direct API calls | Concern | Raw API | SDK | -|---------|---------|-----| +| ------- | ------- | --- | | Authentication | Manual token management, JWT refresh | Handled automatically | -| Querying | Build GraphQL strings by hand | `client.get()`, `client.all()`, `client.filters()` | +| Querying | Build GraphQL queries by hand | `client.get()`, `client.all()`, `client.filters()` | | Mutations | Construct and POST GraphQL mutations | `node.save()`, `node.delete()` | -| Relationships | Navigate nested JSON responses | Access via `node.relationship.peer` | -| Branching | Manage branch headers/parameters | `client.branch.create()`, `client.branch.merge()` | | Concurrency | Roll your own async batching | Built-in `batch` with concurrency control | -| Schema awareness | Parse schema separately | Schema-driven filters and validation | +| Typing | Maintain type definitions manually | Schema-driven type export using protocols | +:::tip The SDK removes the boilerplate so you can focus on the logic that matters to your infrastructure. +::: ## Key capabilities - **CRUD operations** — Create, read, update, and delete any node type defined in your schema. -- **Filtering** — Query nodes using schema-aware attribute and relationship filters (`name__value`, `site__name__value`, etc.). -- **Branch management** — Create, merge, rebase, and diff branches programmatically. - **Batch execution** — Group multiple queries into a batch with configurable concurrency limits. - **Tracking** — Tag operations with identifiers for auditing and idempotent updates. - **Store** — Cache retrieved nodes locally to reduce redundant queries. - **GraphQL escape hatch** — Run arbitrary GraphQL queries when the high-level API doesn't cover your use case. +## Video walkthrough + +
+ +
+ ## Installation + + + +```bash +uv add infrahub-sdk +``` + +Extras are available for additional functionality: + +```bash +uv add 'infrahub-sdk[ctl]' # Adds the infrahubctl CLI +uv add 'infrahub-sdk[tests]' # Adds the testing framework for transforms and checks +uv add 'infrahub-sdk[all]' # Everything +``` + + + + ```bash pip install infrahub-sdk ``` @@ -109,10 +139,14 @@ pip install 'infrahub-sdk[tests]' # Adds the testing framework for transforms a pip install 'infrahub-sdk[all]' # Everything ``` -See the [installation guide](./guides/installation.mdx) for details. + + + + ## Next steps +- **[Hello world example](./guides/client.mdx#hello-world-example)** — Your first client connection and query. - **[Create and configure a client](./guides/client.mdx)** — Set up authentication, proxy settings, and client options. - **[Query data](./guides/query_data.mdx)** — Retrieve nodes with filters and GraphQL. - **[Create, update, and delete nodes](./guides/create_update_delete.mdx)** — Manage infrastructure data programmatically. From 3c0426ac1e71cc38010a1117759422b759175efb Mon Sep 17 00:00:00 2001 From: Baptiste Date: Mon, 30 Mar 2026 16:58:42 +0200 Subject: [PATCH 3/4] spelling --- .vale/styles/spelling-exceptions.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.vale/styles/spelling-exceptions.txt b/.vale/styles/spelling-exceptions.txt index 2da24e1f..d43441bb 100644 --- a/.vale/styles/spelling-exceptions.txt +++ b/.vale/styles/spelling-exceptions.txt @@ -136,3 +136,4 @@ yamllint YouTube vscode VSCode +walkthrough \ No newline at end of file From 7ac5e73ae7db101843c973dabd913bd8901d448f Mon Sep 17 00:00:00 2001 From: Baptiste Date: Mon, 30 Mar 2026 17:10:13 +0200 Subject: [PATCH 4/4] Add product context --- AGENTS.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 00de5ab1..59a33f1e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,20 @@ Infrahub Python SDK - async/sync client for Infrahub infrastructure management. +## Product context + +The SDK is the foundational library for programmatically interacting with Infrahub. It abstracts away the underlying API so developers can work with infrastructure data using native Python objects. + +**Primary audience:** Network automation engineers and software developers. + +**Three main use cases:** + +- **Automate inside Infrahub** — Write transforms, generators, and checks that run as part of Infrahub's pipeline. +- **Integrate with external systems** — Query and sync data between Infrahub and existing tools. `infrahubctl` and the Infrahub Ansible collection both use this SDK internally. +- **Build custom applications** — Use Infrahub as a data backend for Python projects entirely outside of Infrahub's own pipeline. + +**Why the SDK over direct API calls:** eliminates the need to learn Infrahub's API structure, provides Python-native interfaces with built-in auth, adds advanced capabilities (batching, caching, tracking), and reduces boilerplate. + ## Commands ```bash