OrbitsDocs
esc
    Open Orbits
    SDKsPython

    Python SDK

    Install useorbits, create a client, deploy and follow a build, manage variables and domains, and handle errors, pages and retries, sync or async.

    Python
    import useorbits
    
    with useorbits.Orbits() as orbits:
        for project in orbits.projects.list_all("my-team"):
            print(project["slug"], project["status"], project["free_address"])

    useorbits is the official Python library. It has sync (Orbits) and asyncio (AsyncOrbits) clients with the same methods, typed keyword arguments, and results typed with the TypedDicts in useorbits.types, keyed exactly as the API names its fields. Its one dependency is httpx. It needs Python 3.10 or later.

    Every route under a team takes the team's slug (or team_ id) first, then the project's slug (or prj_ id) where there is one. Other arguments are keyword-only. Arguments you leave out are not sent; passing None sends JSON null.

    Install

    Terminal
    $ pip install useorbits

    Authenticate

    Make an API token under Team › Settings › API tokens and put it in ORBITS_TOKEN. The client reads it.

    Terminal
    $ export ORBITS_TOKEN=orb_live_…

    Without a token, useorbits.Orbits() raises. Or pass options:

    Python
    import os
    import useorbits
    
    orbits = useorbits.Orbits(
        token=os.environ["MY_ORBITS_TOKEN"],
        base_url="https://stagingapi.theorbits.app/v1",  # or ORBITS_API_URL; default https://api.theorbits.app/v1
        timeout=60.0,  # per attempt, in seconds (the default; 10 s to connect); or an httpx.Timeout
        max_retries=3,  # the default
    )

    The other options are default_headers, user_agent and http_client. Every method also takes timeout=, extra_headers=, extra_query= and, with a body, extra_body=. POSTs take idempotency_key=. Use the client as a context manager, as above, or call close() when you are done.

    Deploy and follow the build

    For a Git project, deployments.create builds a branch's newest commit, by default the production branch:

    deploy.py
    import useorbits
    
    with useorbits.Orbits() as orbits:
        deployment = orbits.deployments.create("my-team", "my-app")
        # or a preview: orbits.deployments.create("my-team", "my-app", branch="feature/checkout")
    
        for event in orbits.deployments.stream_logs("my-team", "my-app", deployment["id"]):
            if event["event"] == "line":
                print(event["data"]["text"])
            elif event["event"] == "done":
                break
    
        ready = orbits.wait_for_deployment("my-team", "my-app", deployment)  # raises DeploymentFailedError if it fails
        print(ready["url"])

    stream_logs yields the build's events (line, steps, done, then screenshot) and reconnects if the connection drops, without missing or repeating a line. get_logs(..., after=n) reads the log without streaming. deployments.get(team, project, deployment) reads one deployment.

    Deploy a folder

    A project created with source_kind="upload" deploys from files instead of a repository:

    Python
    project = orbits.projects.create("my-team", name="my-site", source_kind="upload")
    
    deployment = orbits.deployments.upload_dir("my-team", project["slug"], "./dist")
    orbits.wait_for_deployment("my-team", project["slug"], deployment)
    print("Live at https://" + project["free_address"])

    upload_dir zips the folder, leaving out node_modules, .git, .next and __MACOSX at any depth, links, and whatever an .orbitsignore at the folder's root lists (.gitignore syntax). It sends the archive straight to storage, without your API token, then deploys it to production. upload_archive takes a zip you made yourself.

    Promote, roll back, redeploy

    Python
    orbits.deployments.promote("my-team", "my-app", "dpl_…")  # a preview to production, as a new build
    orbits.deployments.rollback("my-team", "my-app", "dpl_…")  # production back to an earlier build, at once
    orbits.deployments.redeploy("my-team", "my-app", "dpl_…", use_cache=False)
    orbits.deployments.cancel("my-team", "my-app", "dpl_…")

    A rollback pauses automatic production deploys. See Deployments.

    Environment variables

    Python
    import os
    
    orbits.env.create(
        "my-team",
        "my-app",
        variables=[
            {"key": "STRIPE_SECRET_KEY", "value": os.environ["STRIPE_SECRET_KEY"]},  # sensitive by default
            {"key": "API_URL", "value": "https://api.example.com", "sensitive": False, "environments": ["production"]},
        ],
    )
    
    for var in orbits.env.list_all("my-team", "my-app"):
        print(var["key"], var["environments"], var["sensitive"])

    Variables are sensitive (write-only) unless "sensitive": False, and apply to production and preview unless you set environments. A key that exists already raises ConflictError; pass on_conflict="replace" to replace it. New values apply to deployments built afterwards, so redeploy to use them. Values are never listed; env.reveal reads one non-sensitive value and env.pull(team, project, environment="development") an environment's readable values, both with a full-access token. See Environment variables.

    Domains

    Python
    domain = orbits.domains.add("my-team", domain="shop.example.com", project="my-app")
    print(domain["state"], domain["required_record"])
    
    orbits.domains.check("my-team", "shop.example.com")  # look the DNS up again now

    branch= serves a branch's newest preview instead of production, and to= redirects to another hostname. Records on Orbits DNS are under domains.records. See Custom domains.

    Resources

    Areas are attributes of the client and nest where the API does:

    AttributeWhat it covers
    meThe person the token acts as
    teams, teams.notificationsTeams, their overview and notifications
    projectsCreate, configure, pause/resume, delete
    deployments, deployments.uploadsList, deploy, upload_dir, logs and stream_logs, promote, rollback, redeploy, cancel, set_production, wait
    envEnvironment variables: list, create, update, delete, restore, reveal, pull
    domains, domains.records, domains.emailDomains, checks, zone imports, DNS records, email provider records
    flags, flags.rulesFeature flags and their targeting rules
    workflowsWorkflows and their runs
    alerts, alerts.channelsAlerts and where they are sent
    observabilityRuntime logs, request metrics, Analytics, Speed Insights
    usage, activity, billing, billing.invoicesUsage, the activity log, the plan and invoices (read only)
    templates, integrations, operationsStarter templates, the integrations list, operations

    There is a sandboxes attribute too, but sandboxes are not available yet.

    Async

    AsyncOrbits has the same methods; lists are async iterators:

    Python
    import asyncio
    import useorbits
    
    
    async def main() -> None:
        async with useorbits.AsyncOrbits() as orbits:
            async for deployment in orbits.deployments.list_all("my-team", "my-app", environment="production"):
                print(deployment["id"], deployment["state"])
    
    
    asyncio.run(main())

    Errors

    Python
    try:
        orbits.projects.get("my-team", "my-app")
    except useorbits.NotFoundError as err:
        print(err.detail, err.request_id)  # also "not in your team": the API doesn't tell the two apart
    except useorbits.ValidationError as err:
        for field in err.errors:
            print(field["field"], field["message"])
    except useorbits.ForbiddenError as err:
        print(err.detail)  # e.g. "This API token is read-only"
    except useorbits.APIError as err:
        print(err.status, err.title, err.detail)

    APIError carries status, title, detail (safe to show), type, instance, code (a stable reason where there is one, such as plan_required), request_id (quote it to support) and errors.

    ClassWhen
    BadRequestError400
    AuthenticationError401: the token is wrong, revoked or expired
    PaymentRequiredError402: the team's plan doesn't include this (required_plan, feature)
    ForbiddenError403
    NotFoundError404: not there, or not in the token's team
    ConflictError409
    ValidationError422, with errors
    RateLimitError429 after the retries, with retry_after and scope
    ServerError5xx after the retries
    APIConnectionError, APITimeoutErrorNo answer
    UploadErrorStorage refused an upload
    OperationFailedError, DeploymentFailedError, WaitTimeoutErrorWaiting ended badly

    All of them are OrbitsError. Errors.

    Pages

    list() returns one page, with items and next_cursor. list_all() follows the cursor for you:

    Python
    for d in orbits.deployments.list_all("my-team", "my-app", environment="production"):
        print(d["id"], d["state"])

    Waiting

    Slow changes answer 202 with an operation or the new deployment:

    Python
    accepted = orbits.projects.delete("my-team", "old-site")
    orbits.wait_for_operation(accepted, timeout=300)  # raises OperationFailedError if it failed
    
    orbits.wait_for_deployment("my-team", "my-app", "dpl_…", timeout=900)

    wait_for_deployment polls every 3 seconds for up to 30 minutes, and wait_for_operation every 2 seconds for up to 10 minutes. Both take timeout= and poll_interval= in seconds, and raise_on_failure=False to get the result back instead of an error. A wait that runs out raises WaitTimeoutError; the change may still finish. They are also deployments.wait and operations.wait.

    Idempotency and retries

    Every POST gets a fresh UUID Idempotency-Key, and retries resend the same key, so the API returns the first result instead of repeating the change. Connection errors, timeouts, 429, 502, 503 and 504 are retried up to max_retries times with a growing, random wait, or after the Retry-After the API sends (at most 60 seconds). GET, PUT and DELETE are safe to repeat; a PATCH is retried only when the API certainly did nothing (a 429, or a connection that was never made).

    Requests carry User-Agent: orbits-python/<version>. The token is never logged.

    Calling any endpoint

    request calls a path directly, with the same auth, retries and errors:

    Python
    page = orbits.request("GET", "/teams/my-team/projects", query={"q": "shop"})

    Was this page helpful?

    Updated