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 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 diff --git a/docs/docs/python-sdk/introduction.mdx b/docs/docs/python-sdk/introduction.mdx index 26f945ce..6eeb9f64 100644 --- a/docs/docs/python-sdk/introduction.mdx +++ b/docs/docs/python-sdk/introduction.mdx @@ -1,36 +1,155 @@ --- -title: Python SDK +title: Python SDK overview --- -import VideoPlayer from '../../src/components/VideoPlayer'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import ReferenceLink from '@site/src/components/Card'; +import VideoPlayer from '@site/src/components/VideoPlayer'; -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 + +The SDK covers three main use cases: + +- **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`](/infrahubctl/infrahubctl) and the [Infrahub Ansible collection](https://docs.infrahub.app/ansible) both use this SDK. + +## A quick look + + + + +```python +import asyncio +from infrahub_sdk import InfrahubClient + + +async def main(): + client = InfrahubClient() + + # Create a new tag and save it + tag = await client.create( + kind="BuiltinTag", + name="staging", + description="Resources in the staging environment", + ) + await tag.save() + + # Query all tags + tags = await client.all(kind="BuiltinTag") + for tag in tags: + print(f"{tag.name.value} — {tag.description.value}") + + +asyncio.run(main()) + +``` + + + + +```python +from infrahub_sdk import InfrahubClientSync + +client = InfrahubClientSync() + +# Create a new tag and save it +tag = client.create( + kind="BuiltinTag", + name="staging", + description="Resources in the staging environment", +) +tag.save() + +# Query all tags +tags = client.all(kind="BuiltinTag") +for tag in tags: + print(f"{tag.name.value} — {tag.description.value}") + +``` + + + + +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 queries by hand | `client.get()`, `client.all()`, `client.filters()` | +| Mutations | Construct and POST GraphQL mutations | `node.save()`, `node.delete()` | +| Concurrency | Roll your own async batching | Built-in `batch` with concurrency control | +| 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. +- **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
-## Blog posts +## 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 +``` + + + -- [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/) +```bash +pip install infrahub-sdk +``` -## Guides +Extras are available for additional functionality: -- [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) +```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 +``` -## Topics + + -- [Understanding tracking in the Python SDK](./topics/tracking.mdx) + -## Reference +## Next steps -- [Client configuration](./reference/config.mdx) -- [Python SDK Release Notes](https://github.com/opsmill/infrahub-sdk-python/releases) +- **[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. +- **[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.