Skip to content

Commit f148553

Browse files
BaptisteGiBaptisteGi
authored
Overview page sdk (#853)
* Draft overview page sdk * refresh sdk overview * spelling * Add product context * Apply suggestion from @BaptisteGi
1 parent ba0a3bd commit f148553

3 files changed

Lines changed: 156 additions & 21 deletions

File tree

‎.vale/styles/spelling-exceptions.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,3 +138,4 @@ yamllint
138138
YouTube
139139
vscode
140140
VSCode
141+
walkthrough

‎AGENTS.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,20 @@
22

33
Infrahub Python SDK - async/sync client for Infrahub infrastructure management.
44

5+
## Product context
6+
7+
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.
8+
9+
**Primary audience:** Network automation engineers and software developers.
10+
11+
**Three main use cases:**
12+
13+
- **Automate inside Infrahub** — Write transforms, generators, and checks that run as part of Infrahub's pipeline.
14+
- **Integrate with external systems** — Query and sync data between Infrahub and existing tools. `infrahubctl` and the Infrahub Ansible collection both use this SDK internally.
15+
- **Build custom applications** — Use Infrahub as a data backend for Python projects entirely outside of Infrahub's own pipeline.
16+
17+
**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.
18+
519
## Commands
620

721
```bash

‎docs/docs/python-sdk/introduction.mdx‎

Lines changed: 141 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,157 @@
11
---
2-
title: Python SDK
2+
title: Python SDK overview
33
---
4-
import VideoPlayer from '../../src/components/VideoPlayer';
4+
import Tabs from '@theme/Tabs';
5+
import TabItem from '@theme/TabItem';
6+
import ReferenceLink from '@site/src/components/Card';
7+
import VideoPlayer from '@site/src/components/VideoPlayer';
58

6-
The Infrahub Python SDK greatly simplifies how you can interact with Infrahub programmatically.
9+
# Infrahub Python SDK
710

8-
## Videos
11+
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.
12+
13+
## What you can do with it
14+
15+
The SDK covers three main use cases:
16+
17+
- **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.
18+
- **Integrate with external systems** — Query and sync data between Infrahub and your existing tools.
19+
- **Build custom applications** — Use Infrahub as a data backend for your own Python projects.
20+
21+
Under the hood, tools like [`infrahubctl`](/infrahubctl/infrahubctl) and the [Infrahub Ansible collection](https://docs.infrahub.app/ansible) both use this SDK.
22+
23+
## A quick look
24+
25+
<Tabs groupId="async-sync">
26+
<TabItem value="Async" default>
27+
28+
```python
29+
import asyncio
30+
from infrahub_sdk import InfrahubClient
31+
32+
33+
async def main():
34+
client = InfrahubClient()
35+
36+
# Create a new tag and save it
37+
tag = await client.create(
38+
kind="BuiltinTag",
39+
name="staging",
40+
description="Resources in the staging environment",
41+
)
42+
await tag.save()
43+
44+
# Query all tags
45+
tags = await client.all(kind="BuiltinTag")
46+
for tag in tags:
47+
print(f"{tag.name.value} — {tag.description.value}")
48+
49+
50+
asyncio.run(main())
51+
52+
```
53+
54+
</TabItem>
55+
<TabItem value="Sync">
56+
57+
```python
58+
from infrahub_sdk import InfrahubClientSync
59+
60+
client = InfrahubClientSync()
61+
62+
# Create a new tag and save it
63+
tag = client.create(
64+
kind="BuiltinTag",
65+
name="staging",
66+
description="Resources in the staging environment",
67+
)
68+
tag.save()
69+
70+
# Query all tags
71+
tags = client.all(kind="BuiltinTag")
72+
for tag in tags:
73+
print(f"{tag.name.value} — {tag.description.value}")
74+
75+
```
76+
77+
</TabItem>
78+
</Tabs>
79+
80+
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.
81+
82+
## When to use the SDK instead of direct API calls
83+
84+
| Concern | Raw API | SDK |
85+
| ------- | ------- | --- |
86+
| Authentication | Manual token management, JWT refresh | Handled automatically |
87+
| Querying | Build GraphQL queries by hand | `client.get()`, `client.all()`, `client.filters()` |
88+
| Mutations | Construct and POST GraphQL mutations | `node.save()`, `node.delete()` |
89+
| Concurrency | Roll your own async batching | Built-in `batch` with concurrency control |
90+
| Typing | Maintain type definitions manually | Schema-driven type export using protocols |
91+
92+
:::tip
93+
The SDK removes the boilerplate so you can focus on the logic that matters to your infrastructure.
94+
:::
95+
96+
## Key capabilities
97+
98+
- **CRUD operations** — Create, read, update, and delete any node type defined in your schema.
99+
- **Batch execution** — Group multiple queries into a batch with configurable concurrency limits.
100+
- **Tracking** — Tag operations with identifiers for auditing and idempotent updates.
101+
- **Store** — Cache retrieved nodes locally to reduce redundant queries.
102+
- **GraphQL escape hatch** — Run arbitrary GraphQL queries when the high-level API doesn't cover your use case.
103+
104+
## Video walkthrough
9105

10106
<center>
11107
<VideoPlayer url='https://www.youtube.com/live/RbRz8_t0FBs?feature=shared' light />
12108
</center>
13109

14-
## Blog posts
110+
## Installation
111+
112+
<Tabs groupId="installation">
113+
<TabItem value="uv" default>
114+
115+
```bash
116+
uv add infrahub-sdk
117+
```
118+
119+
Extras are available for additional functionality:
120+
121+
```bash
122+
uv add 'infrahub-sdk[ctl]' # Adds the infrahubctl CLI
123+
uv add 'infrahub-sdk[tests]' # Adds the testing framework for transforms and checks
124+
uv add 'infrahub-sdk[all]' # Everything
125+
```
126+
127+
</TabItem>
128+
<TabItem value="pip">
15129

16-
- [Querying Data in Infrahub via the Python SDK](https://www.opsmill.com/querying-data-in-infrahub-via-the-python-sdk/)
17-
- [Creating, Modifying, and Deleting Data in Infrahub Using the Python SDK](https://www.opsmill.com/infrahub-python-sdk-create-modify-delete/)
130+
```bash
131+
pip install infrahub-sdk
132+
```
18133

19-
## Guides
134+
Extras are available for additional functionality:
20135

21-
- [Installing infrahub-sdk](./guides/installation.mdx)
22-
- [Creating a client](./guides/client.mdx)
23-
- [Querying data in Infrahub](./guides/query_data.mdx)
24-
- [Managing nodes](./guides/create_update_delete.mdx)
25-
- [Managing branches](./guides/branches.mdx)
26-
- [Using the client store](./guides/store.mdx)
27-
- [Using the client tracking mode](./guides/tracking.mdx)
136+
```bash
137+
pip install 'infrahub-sdk[ctl]' # Adds the infrahubctl CLI
138+
pip install 'infrahub-sdk[tests]' # Adds the testing framework for transforms and checks
139+
pip install 'infrahub-sdk[all]' # Everything
140+
```
28141

29-
## Topics
142+
</TabItem>
143+
</Tabs>
30144

31-
- [Understanding tracking in the Python SDK](./topics/tracking.mdx)
145+
<ReferenceLink title="Installation guide" url="/python-sdk/guides/installation" />
32146

33-
## Reference
147+
## Next steps
34148

35-
- [Client configuration](./reference/config.mdx)
36-
- [Compatibility matrix](./reference/compatibility.mdx)
37-
- [Python SDK Release Notes](https://github.com/opsmill/infrahub-sdk-python/releases)
149+
- **[Hello world example](./guides/client.mdx#hello-world-example)** — Your first client connection and query.
150+
- **[Create and configure a client](./guides/client.mdx)** — Set up authentication, proxy settings, and client options.
151+
- **[Query data](./guides/query_data.mdx)** — Retrieve nodes with filters and GraphQL.
152+
- **[Create, update, and delete nodes](./guides/create_update_delete.mdx)** — Manage infrastructure data programmatically.
153+
- **[Work with branches](./guides/branches.mdx)** — Use Infrahub's branch workflow from Python.
154+
- **[Batch operations](./guides/batch.mdx)** — Optimize performance for bulk operations.
155+
- **[Client configuration reference](./reference/config.mdx)** — All available configuration options.
156+
- **[Compatibility matrix](./reference/compatibility.mdx)**
157+
- **[Python SDK Release Notes](https://github.com/opsmill/infrahub-sdk-python/releases)**

0 commit comments

Comments
 (0)
⚡