Skip to main content

Python SDK

The Python SDK provides a Pythonic interface for interacting with Terragnos Core. It's generated from the OpenAPI specification and supports Python 3.9+.

Installation​

pip install terragnos-admin-client

Or with poetry:

poetry add terragnos-admin-client

Requirements​

  • Python 3.9+
  • requests library (included as dependency)

Basic Usage​

Creating a Client​

from terragnos_admin_client import TerragnosAdminClient

client = TerragnosAdminClient(
    base_url="https://core.example.com/v1",
    token="Bearer your-jwt-token"
)

Listing Objects​

response = client.list_objects(type_id="traffic-signal", limit=25)
print(f"Found {len(response['items'])} objects")

for obj in response['items']:
    print(f"{obj['publicId']}: {obj['typeId']}")

Creating Objects​

object_data = client.create_object(
    type_id="traffic-signal",
    attributes={
        "signalType": "standard",
        "intersectionId": "INT-001"
    },
    geometry={
        "type": "Point",
        "coordinates": [19.04, 47.49]
    }
)

print(f"Created object: {object_data['id']}")

Updating Objects​

updated = client.update_object(
    object_id="object-id",
    version=1,  # Optimistic locking
    attributes={
        "signalType": "pedestrian"
    }
)

Workflow Transitions​

client.transition_workflow(
    object_id="object-id",
    target_state="approved",
    metadata={
        "reason": "Meets all requirements"
    }
)

Query Service​

results = client.run_query(
    filters=[
        {
            "field": "typeId",
            "operator": "equals",
            "value": "traffic-signal"
        },
        {
            "field": "attributes.status",
            "operator": "equals",
            "value": "active"
        }
    ],
    sorts=[
        {
            "field": "createdAt",
            "order": "desc"
        }
    ],
    limit=50
)

Error Handling​

from terragnos_admin_client.exceptions import TerragnosError

try:
    obj = client.get_object(object_id="object-id")
except TerragnosError as e:
    if e.status_code == 401:
        print("Authentication failed")
    elif e.status_code == 403:
        print("Permission denied")
    elif e.status_code == 404:
        print("Object not found")
    elif e.status_code == 409:
        print("Optimistic locking conflict")
    else:
        print(f"API error: {e.message}")

Custom HTTP Configuration​

import requests
from terragnos_admin_client import TerragnosAdminClient

session = requests.Session()
session.mount('https://', requests.adapters.HTTPAdapter(
    max_retries=3
))

client = TerragnosAdminClient(
    base_url="https://core.example.com/v1",
    token="Bearer your-token",
    session=session
)

Available Operations​

The SDK exposes all API operations. View available operations:

print(client.AVAILABLE_OPERATIONS)

Best Practices​

  1. Use virtual environments – Isolate dependencies
  2. Handle exceptions – Always catch TerragnosError
  3. Reuse client instances – Create one client per application
  4. Environment variables – Store tokens securely
  5. Type hints – Use type hints for better IDE support
  6. Async support – Use async/await for concurrent operations (if supported)