Skip to main content

Python SDK

The official Python SDK for GGNomad is published as ggnomad-sdk. It is a thin shell over burdenoff-sdk-libs that mounts the GGNomad domain module plus all shared platform modules.

Installation​

pip install ggnomad-sdk

# Development install
pip install -e ".[dev]"

Environment selection​

The SDK defaults to production endpoints. Set BURDENOFF_ENV before initializing the SDK to target alpha or local:

BURDENOFF_ENVWorkspace endpointGlobal endpoint
prod (default)https://graphqlworkspaces.burdenoff.com/workspaces/graphqlhttps://graphql.burdenoff.com/global/graphql
alphahttps://alphagraphqlworkspaces.burdenoff.com/workspaces/graphqlhttps://alphagraphql.burdenoff.com/global/graphql
localhttp://localhost:4003/workspaces/graphqlhttp://localhost:4000/global/graphql
export BURDENOFF_ENV=alpha

Quick start​

import asyncio
from ggnomad_sdk import GgnomadSDK


async def main():
    # Defaults to the shared prod gateways and the burdenoff_cli_ggnomad
    # OIDC client. Override the endpoints for local dev.
    sdk = GgnomadSDK()

    # Sign in with email/password
    await sdk.auth.sign_in(email="[email protected]", password="secret")

    # Ggnomad-domain operations are nested under sdk.ggnomad
    properties = await sdk.ggnomad.properties.list()
    bookings = await sdk.ggnomad.bookings.list()

    # Shared cross-product modules are mounted at the top level
    tags = await sdk.tags.list()

    await sdk.close()


asyncio.run(main())

Modules​

All methods are async. The following modules are mounted on the GgnomadSDK instance:

auth, billing, channels, conversations, devportal, export, files, groups, health, integrations, ggnomad, notifications, organizations, products, rbac, sandbox, scheduler, security, store, support, tags, tours, workspaces.

GGNomad domain methods​

await sdk.ggnomad.properties.list()
await sdk.ggnomad.activities.list()
await sdk.ggnomad.events.list()
await sdk.ggnomad.tours.list()
await sdk.ggnomad.trips.list()
await sdk.ggnomad.providers.list()
await sdk.ggnomad.bookings.list()
await sdk.ggnomad.favorites.list()
await sdk.ggnomad.analytics.health()

Configuration​

from ggnomad_sdk import GgnomadSDK

sdk = GgnomadSDK(
    workspace_endpoint="https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
    global_endpoint="https://graphql.burdenoff.com/global/graphql",
    client_id="burdenoff_cli_ggnomad",   # default
    oidc_issuer=None,                       # derived from global_endpoint
    api_key=None,
    access_token=None,
    refresh_token=None,
    workspace_token=None,
    timeout=30.0,
    auto_refresh=True,
)

Error handling​

from ggnomad_sdk import (
    GgnomadError,
    AuthenticationError,
    AuthorizationError,
    NetworkError,
    ValidationError,
    RateLimitError,
    DeviceCodeExpiredError,
    DeviceCodeDeniedError,
)

try:
    await sdk.auth.sign_in(email="[email protected]", password="wrong")
except AuthenticationError:
    print("Invalid credentials")
except NetworkError:
    print("Could not reach the API")
except GgnomadError as e:
    print(f"SDK error: {e}")

Development​

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

make format        # black + isort
make lint          # flake8
make type-check    # mypy (strict)
make test          # pytest
make sanity        # format-check + lint + type-check + test (cov>=80) + build