Skip to main content

Installation

API reference for the iii-helpers package (Python).

http

HTTP request/response types, auth config, and the http helper. Import

Functions

http

Wrap a streaming handler so it receives typed StreamRequest and StreamResponse. Takes a callback (req, res) -> HttpResponse | None and returns a function the iii engine can invoke directly. The wrapper converts the raw dict (or InternalHttpRequest) delivered by the engine into the typed StreamRequest / StreamResponse pair that the callback expects. Signature

Parameters

Callable[[StreamRequest, StreamResponse], Awaitable[HttpResponse[Any] | None]]
required
Async handler (req, res) -> HttpResponse | None invoked with the typed StreamRequest and StreamResponse.

Types

HttpAuthApiKey · HttpAuthBearer · HttpAuthHmac · HttpInvocationConfig · HttpRequest · HttpResponse

HttpAuthApiKey

API key sent via a custom header.

HttpAuthBearer

Bearer token authentication.

HttpAuthHmac

HMAC signature verification using a shared secret.

HttpInvocationConfig

Configuration for an HTTP-invoked function (Lambda, Cloudflare Workers, etc.).

HttpRequest

Incoming buffered HTTP request received by a function handler.

HttpResponse

Structured buffered HTTP response returned from function handlers.

observability

Logger, OpenTelemetry config, and span helpers. Import

Functions

current_span_id

Return current active span_id as 16-char hex, or None when unavailable. Signature

current_span_is_recording

Returns False when there is no active span or the sampler dropped it. Signature

current_trace_id

Return current active trace_id as 32-char hex, or None when unavailable. Signature

execute_traced_request

Execute an httpx Request inside an OTel CLIENT span.
  • Injects W3C traceparent into outgoing request headers.
  • Records HTTP semantic-convention attributes on the span.
  • Sets ERROR span status for responses with status >= 400.
  • Records exceptions for network-level errors.
Signature

Parameters

Any
required
httpx async client used to send the request.
Any
required
The httpx request to execute.

extract_baggage

Extract baggage from a W3C baggage header string. Signature

Parameters

str
required
W3C baggage header value.

extract_traceparent

Extract a trace context from a W3C traceparent header string. Signature

Parameters

str
required
W3C traceparent header value.

flush_otel

Force-flush all OTel providers without tearing them down. Counterpart to shutdown_otel. Use before short-lived process exits where you want pending spans/metrics/logs delivered but plan to keep using OTel afterwards. Signature

init_otel

Initialize OpenTelemetry. Subsequent calls are no-ops. Signature

Parameters

OtelConfig | None
OTel configuration.
None
Running asyncio event loop. When provided, SharedEngineConnection starts immediately. When None, the connection is started lazily on first use (pre-start buffer absorbs early frames).

inject_baggage

Inject the current baggage into a W3C baggage header string. Signature

inject_traceparent

Inject the current trace context into a W3C traceparent header string. Signature

record_span_event

No-op when the current span is not recording. Signature

Parameters

str
required
Name of the event to record on the current span.
dict[str, Any] | None
Optional attributes attached to the event.

redact

Recursively redact values of sensitive keys. Returns a new value. Signature

Parameters

Any
required
Value to redact; dicts, lists, and tuples are traversed recursively.

redact_and_truncate

Redact then serialize to JSON, optionally capped at max_bytes. Signature

Parameters

Any
required
Value to redact and serialize.
Optional[int]
Optional cap on the serialized byte length; unset, zero, or negative means no cap.

resolve_max_bytes_from_env

Signature

set_current_span_attribute

No-op when the current span is not recording. Signature

Parameters

str
required
Attribute name to set on the current span.
Any
required
Attribute value.

set_current_span_error

No-op when there is no active span. Signature

Parameters

str
required
Error message recorded on the current span’s status.

shutdown_otel

Shut down OTel synchronously (best-effort; does not await WS flush). Signature

with_span

Start a new span and run fn(span) within it. If the tracer is not initialized, fn is called with a no-op span that silently ignores attribute/event calls. Signature

Parameters

str
required
Span name.
Any
required
Async callable (span) -> T.
Any
Optional SpanKind. Defaults to INTERNAL.
str | None
Optional W3C traceparent to use as parent context.

Types

BaggageSpanProcessor · Logger · OtelConfig · ReconnectionConfig

BaggageSpanProcessor

OpenTelemetry span processor that copies OTel baggage entries onto each started span as attributes.

Logger

Structured logger that emits logs as OpenTelemetry LogRecords. Every log call automatically captures the active trace and span context, correlating your logs with distributed traces without any manual wiring. When OTel is not initialized, Logger gracefully falls back to Python logging. Pass structured data as the second argument to any log method. Using a dict of key-value pairs (instead of string interpolation) lets you filter, aggregate, and build dashboards in your observability backend.

OtelConfig

Configuration for OpenTelemetry initialization.

ReconnectionConfig

Configuration for WebSocket reconnection behavior.

queue

Queue enqueue result types. Import

Types

EnqueueResult

EnqueueResult

Result returned when a function is called with CallAction.Enqueue.

stream

Stream change events, IO inputs, and update operations. Import

Types

StreamAuthInput · StreamAuthResult · StreamChangeEvent · StreamChangeEventDetail · StreamDeleteInput · StreamDeleteResult · StreamGetInput · StreamJoinLeaveEvent · StreamJoinResult · StreamListGroupsInput · StreamListInput · StreamSetInput · StreamSetResult · StreamUpdateInput · StreamUpdateResult · UpdateAppend · UpdateDecrement · UpdateIncrement · UpdateMerge · UpdateOpError · UpdateRemove · UpdateSet

StreamAuthInput

Input for stream authentication. .. deprecated:: StreamAuthInput is deprecated (iii-stream) and will be removed in an upcoming release. Behavior is unchanged for now. Migration guide: https://iii.dev/docs/upgrading/migrate-from-streams

StreamAuthResult

Result of stream authentication. .. deprecated:: StreamAuthResult is deprecated (iii-stream) and will be removed in an upcoming release. Behavior is unchanged for now. Migration guide: https://iii.dev/docs/upgrading/migrate-from-streams

StreamChangeEvent

A stream change, from an item changed via stream::set, stream::update, or stream::delete. .. deprecated:: StreamChangeEvent is deprecated (iii-stream) and will be removed in an upcoming release. Behavior is unchanged for now. Migration guide: https://iii.dev/docs/upgrading/migrate-from-streams

StreamChangeEventDetail

Detail of a stream change event containing the mutation type and data. .. deprecated:: StreamChangeEventDetail is deprecated (iii-stream) and will be removed in an upcoming release. Behavior is unchanged for now. Migration guide: https://iii.dev/docs/upgrading/migrate-from-streams

StreamDeleteInput

Input for stream delete operation. .. deprecated:: StreamDeleteInput is deprecated (iii-stream) and will be removed in an upcoming release. Behavior is unchanged for now. Migration guide: https://iii.dev/docs/upgrading/migrate-from-streams

StreamDeleteResult

Result of stream delete operation.

StreamGetInput

Input for stream get operation. .. deprecated:: StreamGetInput is deprecated (iii-stream) and will be removed in an upcoming release. Behavior is unchanged for now. Migration guide: https://iii.dev/docs/upgrading/migrate-from-streams

StreamJoinLeaveEvent

Event for stream join/leave. .. deprecated:: StreamJoinLeaveEvent is deprecated (iii-stream) and will be removed in an upcoming release. Behavior is unchanged for now. Migration guide: https://iii.dev/docs/upgrading/migrate-from-streams

StreamJoinResult

Result of stream join. .. deprecated:: StreamJoinResult is deprecated (iii-stream) and will be removed in an upcoming release. Behavior is unchanged for now. Migration guide: https://iii.dev/docs/upgrading/migrate-from-streams

StreamListGroupsInput

Input for stream list groups operation. .. deprecated:: StreamListGroupsInput is deprecated (iii-stream) and will be removed in an upcoming release. Behavior is unchanged for now. Migration guide: https://iii.dev/docs/upgrading/migrate-from-streams

StreamListInput

Input for stream list operation. .. deprecated:: StreamListInput is deprecated (iii-stream) and will be removed in an upcoming release. Behavior is unchanged for now. Migration guide: https://iii.dev/docs/upgrading/migrate-from-streams

StreamSetInput

Input for stream set operation. .. deprecated:: StreamSetInput is deprecated (iii-stream) and will be removed in an upcoming release. Behavior is unchanged for now. Migration guide: https://iii.dev/docs/upgrading/migrate-from-streams

StreamSetResult

Result of stream set operation.

StreamUpdateInput

Input for stream update operation. .. deprecated:: StreamUpdateInput is deprecated (iii-stream) and will be removed in an upcoming release. Behavior is unchanged for now. Migration guide: https://iii.dev/docs/upgrading/migrate-from-streams

StreamUpdateResult

Result of stream update operation.

UpdateAppend

Append an element to an array, concatenate a string, or push at a nested path. The target is the root (when path is omitted, an empty string, or an empty list), a single first-level key (when path is a non-empty string), or an arbitrary nested location (when path is a list of literal segments). Path forms accepted (mirrors UpdateMerge after #1547):
  • None / "" / []: append at the root.
  • "foo": append at the first-level key foo. A dotted string like "a.b" is the literal key "a.b", not traversed as a -> b.
  • ["a", "b", "c"]: nested path; each element is a literal segment.
Engine semantics:
  • Missing/non-object intermediates along a nested path are auto-created/replaced with {}.
  • At the leaf:
    • missing/null + nested path -> [value] (always an array)
    • missing/null + single-string path -> string-as-string for the string-concat tier, otherwise [value]
    • existing array -> push
    • existing string + string value -> concatenate
    • existing object/scalar at the leaf -> append.type_mismatch
Validation: invalid paths (depth > 32 segments, segment > 256 bytes, or any __proto__ / constructor / prototype segment) are rejected with a structured error in the errors field of the state::update / stream::update response. The append does not apply when an error is returned for that op.

UpdateDecrement

Decrement a numeric field by a given amount.

UpdateIncrement

Increment a numeric field by a given amount.

UpdateMerge

Shallow merge an object into the target. The target is the root (when path is omitted, an empty string, or an empty list) or an arbitrary nested location specified by an array of literal segments. Path forms accepted:
  • None / "" / []: merge at the root.
  • "foo": equivalent to ["foo"]; single first-level key.
  • ["a", "b", "c"]: nested path. Each element is a literal key. ["a.b"] writes a single key named "a.b", not a -> b.
Engine semantics:
  • Missing or non-object intermediates along the path are auto-replaced with {}.
  • The merge is shallow at the target node (top-level keys of value overwrite same-named keys; siblings preserved).
Validation: invalid paths/values (depth > 32 segments, segment > 256 bytes, value depth > 16, > 1024 top-level keys, or any __proto__ / constructor / prototype segment or top-level key) are rejected with a structured error in the errors array of the state::update / stream::update response. The merge does not apply when an error is returned.

UpdateOpError

Per-op error returned by state::update / stream::update. Emitted by the merge and append ops when input violates the validation bounds, and by append for its type-mismatch and target-not-object cases. Successfully applied ops are still reflected in the response’s new_value.

UpdateRemove

Remove a field at the given path.

UpdateSet

Set a field at the given path to a value.

worker_connection_manager

RBAC auth and registration callback types. Import

Types

AuthInput · AuthResult · OnFunctionRegistrationInput · OnFunctionRegistrationResult

AuthInput

Input passed to the RBAC auth function during WebSocket upgrade. Contains the HTTP headers, query parameters, and client IP from the connecting worker’s upgrade request.

AuthResult

Return value from the RBAC auth function. Controls which functions the authenticated worker can invoke and what context is forwarded to the middleware.

OnFunctionRegistrationInput

Input passed to the on_function_registration_function_id hook when a worker attempts to register a function through the RBAC port. Return an OnFunctionRegistrationResult with the (possibly mapped) fields, or raise an exception to deny the registration.

OnFunctionRegistrationResult

Result returned from the on_function_registration_function_id hook. Omitted fields keep the original value from the registration request: return model_dump(exclude_none=True).