Python SDK

Overview

The StrataGateway Python SDK is intended to provide a Python-native interface over the StrataGateway REST API, giving developers a direct way to automate infrastructure workflows from Python applications and operational tooling.

Planned installation

The SDK is not yet published. The commands below are illustrative and only show the intended future installation shape.

pip install stratagateway
python -m pip install stratagateway

Status: Planned. The final package name and distribution method will be confirmed before public release.

Do not assume a public PyPI package currently exists.

Client setup

Initialize the planned SDK client with your API token. The syntax below is illustrative only.

import os
from stratagateway import StrataGateway

client = StrataGateway(
    token=os.environ["STRATA_API_TOKEN"]
)

This interface is a preview of the planned client shape and should not be treated as a published module contract yet.

Authentication

The Python SDK is expected to use the same API token authentication model as the REST API.

Set the STRATA_API_TOKENenvironment variable and pass it to the client.

import os
from stratagateway import StrataGateway

client = StrataGateway(
    token=os.environ["STRATA_API_TOKEN"]
)

Creating an instance

Provision a new compute instance using the planned instances resource. The example below uses illustrative SDK API syntax.

instance = client.instances.create(
    name="web-prod-01",
    region="fra-1",
    plan="compute-standard",
    image="ubuntu-24.04-lts",
    ssh_keys=["key_8f3a9b1c"],
)

print(instance.id)

Illustrative result

{
    "id": "inst_7a91c2",
    "name": "web-prod-01",
    "status": "provisioning",
    "region": "fra-1"
}

Listing instances

List all instances or retrieve a single instance by identifier.

instances = client.instances.list()

for instance in instances.data:
    print(instance.name, instance.status)

instance = client.instances.get("inst_7a91c2")

Exact response object shapes are not finalized.

Working with networks

Create and manage private networks using the planned networks resource.

network = client.networks.create(
    name="production-private",
    region="fra-1",
    cidr="10.10.0.0/24",
)

Working with firewalls

Create and manage firewall policies using the planned firewalls resource.

firewall = client.firewalls.create(
    name="web-production",
    rules=[
        {
            "direction": "inbound",
            "protocol": "tcp",
            "port": "443",
            "source": "0.0.0.0/0",
            "action": "allow",
        }
    ],
)

SSH keys

Manage SSH keys for instance access using the planned SSH keys resource.

key = client.ssh_keys.create(
    name="Personal Laptop",
    public_key="ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...",
)

Error handling

Illustrative Python error handling pattern:

try:
    instance = client.instances.get("inst_example")
except StrataGatewayError as error:
    print(error.code)
    print(error.message)

A planned SDK error concept is StrataGatewayError.

The final Python SDK error hierarchy is still being designed.

Type hints

The Python SDK is intended to include type hints to improve editor autocomplete, static analysis, API discoverability, request validation, and resource modeling.

Illustrative type model

from typing import Literal

InstanceStatus = Literal[
    "provisioning",
    "running",
    "stopped",
    "rebuilding",
    "deleting",
    "error",
]

The exact type definitions are not finalized.

Async support

Async Python support is being considered for workloads that need concurrent infrastructure operations.

from stratagateway import AsyncStrataGateway

client = AsyncStrataGateway(
    token=os.environ["STRATA_API_TOKEN"]
)

instance = await client.instances.create(
    name="worker-01",
    region="fra-1",
    plan="compute-standard",
    image="ubuntu-24.04-lts",
)

The final asynchronous SDK design has not yet been finalized.

Environment variables

Environment variables are preferable to hardcoding credentials in source code.

STRATA_API_TOKEN=your_token_here

export STRATA_API_TOKEN="your_token_here"

$env:STRATA_API_TOKEN="your_token_here"

import os

token = os.environ["STRATA_API_TOKEN"]

REST API relationship

The Python SDK is intended to provide Python-native abstractions over the same API used by the CLI, TypeScript SDK, and Terraform integration.

Python Application
→ StrataGateway Python SDK
→ REST API
→ StrataGateway Control Plane

Automation example

The SDK is intended for repeatable infrastructure automation and operational scripts. The example below shows one restrained workflow for creating several compute resources.

names = ["worker-01", "worker-02", "worker-03"]

for name in names:
    client.instances.create(
        name=name,
        region="fra-1",
        plan="compute-standard",
        image="ubuntu-24.04-lts",
    )

This example does not imply concurrency behavior, rate limit handling, or provisioning guarantees.

Next steps