tungsten-runtime (Python)

Runtime support for SDKs generated by Tungsten.

Install from source

From the repository root, with an interpreter satisfying requires-python in runtimes/python/pyproject.toml:

python -m pip install ./runtimes/python

For generated clients, set targets.python.runtime_path to this runtime checkout when using uv, or install the runtime and generated SDK explicitly. The package includes py.typed; generated models support Pydantic and models: dataclasses. See the root README for interpreter compatibility options. ClientCore is synchronous; AsyncClientCore uses asyncio.

Shared contract

Generated clients use the runtime for request validation, authentication, idempotency keys, confirmation previews, bounded retries, verification, pagination, macros and server-sent events where the input API declares them. Calls return a typed result or a diagnostic envelope describing recovery; unknown outcomes never justify blindly repeating a mutation. The API remains responsible for authorization and server-side idempotency.

Limits

Stream collect(max_bytes=..., max_ms=...) accepts optional byte and time budgets. Setting either defaults the other to 4 MiB or 60 seconds. The byte count uses UTF-8 JSON for the event values, excluding SSE framing. A limit closes the stream and returns a nonretryable error with only the admitted events as partial. Calling collect() with no arguments preserves unbounded collection.

Set ClientOptions.max_response_bytes to opt into an ordinary-response byte cap; a call option with the same name overrides it. The value must be a positive safe integer (at most 9007199254740991); unset keeps the existing unbounded behavior. Content-Length is checked before reading, and actual bytes are counted even without that header. Overflow closes the body and returns UNEXPECTED_RESPONSE with code RESPONSE_TOO_LARGE and retryable: never. A mutation may have taken effect: inspect API state before retrying. The cap does not limit a successful SSE stream; use its event and collection limits.

Default idempotency and OAuth token state are in memory. A FileIdempotencyStore is available for durable idempotency keys; it does not store OAuth tokens. Applications own persistence, permissions and lifecycle.

No runtime ships a file-backed OAuth token store. Provide an application-owned token-store implementation when tokens must survive process restarts; protect stored credentials and avoid logging them. Registry publication and package availability are separate from building this source checkout.

License

Apache-2.0; see the packaged LICENSE. The compiler is licensed separately under AGPL-3.0-only.