Python SDK¶

sympheny-toolbox is the official Python client for the Sympheny API. It exposes every documented REST endpoint as a typed method, validates requests and responses with Pydantic models, and handles authentication (login, token caching, refresh) for you.

Install¶

pip install sympheny-toolbox

Requires Python 3.11 or newer.

One API, sync and async¶

Every method exists on both Sympheny and AsyncSympheny with identical signatures — the sync client is generated from the async source, so the two can never diverge. These docs describe the async client once; every code example has a Sync / Async tab, and your choice persists across all pages.

Quickstart¶

Authenticate with your Sympheny account credentials, then reach the endpoints through resource groups on the client (client.projects, client.scenarios, …):

AsyncSync

import asyncio

from sympheny_toolbox import AsyncSympheny


async def main() -> None:
    async with AsyncSympheny("you@example.com", "password") as client:
        projects = await client.projects.list()
        for project in projects:
            print(project.project_name, project.project_guid)


asyncio.run(main())

from sympheny_toolbox import Sympheny

with Sympheny("you@example.com", "password") as client:
    projects = client.projects.list()
    for project in projects:
        print(project.project_name, project.project_guid)

The client is a context manager; it closes its HTTP connection pool on exit. Outside a with block, call aclose() (async) or close() (sync) yourself.

Client options¶

Argument	Default	Description
`username`	—	Sympheny account email address.
`password`	—	Sympheny account password.
`is_dev`	`False`	Use the development environment instead of production.
`base_url`	production URL	Override the API base URL entirely (takes precedence over `is_dev`).
`timeout`	`30.0`	Request timeout in seconds.

Errors¶

Failed requests raise typed exceptions from sympheny_toolbox.errors, all subclasses of SymphenyError: AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), APIError (any other unsuccessful status, with status_code and body attributes), and UnexpectedResponseError (the response lacked the expected payload).

Where to go next¶

Workflows — end-to-end guides: create a scenario from Excel, run a solver job, and download the results.
SDK reference — one page per resource group, one section per method, each cross-linked to the REST operation it wraps.
Model reference — the Pydantic request/response models, grouped by resource.
REST API reference — the underlying HTTP API, if you need to call it directly.