Skip to content

dispatch ¤

The Dispatch SDK for Python.

DispatchID module-attribute ¤

DispatchID: TypeAlias = str

Unique identifier in Dispatch.

It should be treated as an opaque value.

Client ¤

Client(
    api_key: None | str = None, api_url: None | str = None
)

Client for the Dispatch API.

Parameters:

Name Type Description Default
api_key None | str

Dispatch API key to use for authentication. Uses the value of the DISPATCH_API_KEY environment variable by default.

 None
api_url None | str

The URL of the Dispatch API to use. Uses the value of the DISPATCH_API_URL environment variable if set, otherwise defaults to the public Dispatch API (DEFAULT_API_URL).

 None

Raises:

Type Description
ValueError

if the API key is missing.

dispatch ¤

dispatch(calls: Iterable[Call]) -> list[DispatchID]

Dispatch function calls.

Parameters:

Name Type Description Default
calls Iterable[Call]

Calls to dispatch.

 required

Returns:

Type Description
list[DispatchID]

Identifiers for the function calls, in the same order as the inputs.

Call dataclass ¤

Instruction to call a function.

Though this class can be built manually, it is recommended to use the with_call method of a Function instead.

Error dataclass ¤

Error(
    status: Status,
    type: str,
    message: str,
    value: Exception | None = None,
    traceback: bytes | None = None,
)

Error when running a function.

This is not a Python exception, but potentially part of a CallResult or Output.

Parameters:

Name Type Description Default
status Status

categorization of the error.

 required
type str

arbitrary string, used for humans.

 required
message str

arbitrary message.

 required
value Exception | None

arbitrary exception from which the error is derived. Optional.

 None

Raises:

Type Description
ValueError

Neither type or message was provided or status is invalid.

from_exception classmethod ¤

from_exception(
    ex: Exception, status: Status | None = None
) -> Error

Create an Error from a Python exception, using its class qualified named as type.

The status tries to be inferred, but can be overridden. If it is not provided or cannot be inferred, it defaults to TEMPORARY_ERROR.

to_exception ¤

to_exception() -> Exception

Returns an equivalent exception.

Input ¤

Input(req: RunRequest)

The input to a primitive function.

Functions always take a single argument of type Input. When the function is run for the first time, it receives the input. When the function is a coroutine that's resuming after a yield point, it receives the results of the yield directive. Use the is_first_call and is_resume properties to differentiate between the two cases.

This class is intended to be used as read-only.

input_arguments ¤

input_arguments() -> tuple[tuple[Any, ...], dict[str, Any]]

Returns positional and keyword arguments carried by the input.

Output dataclass ¤

Output(proto: RunResponse)

The output of a primitive function.

This class is meant to be instantiated and returned by authors of functions to indicate the follow up action they need to take. Use the various class methods create an instance of this class. For example Output.value() or Output.poll().

value classmethod ¤

value(value: Any, status: Status | None = None) -> Output

Terminally exit the function with the provided return value.

error classmethod ¤

error(error: Error) -> Output

Terminally exit the function with the provided error.

tail_call classmethod ¤

tail_call(tail_call: Call) -> Output

Terminally exit the function, and instruct the orchestrator to tail call the specified function.

exit classmethod ¤

exit(
    result: CallResult | None = None,
    tail_call: Call | None = None,
    status: Status = Status.OK,
) -> Output

Terminally exit the function.

poll classmethod ¤

poll(
    state: Any,
    calls: None | list[Call] = None,
    min_results: int = 1,
    max_results: int = 10,
    max_wait_seconds: int | None = None,
) -> Output

Suspend the function with a set of Calls, instructing the orchestrator to resume the function with the provided state when call results are ready.

Status ¤

Bases: int, Enum

Enumeration of the possible values that can be used in the return status of functions.

call ¤

call(call: Call) -> Any

Make an asynchronous function call and return its result. If the function call fails with an error, the error is raised.

gather ¤

gather(*awaitables: Awaitable[Any]) -> list[Any]

Concurrently run a set of coroutines and block until all results are available. If any coroutine fails with an uncaught exception, it will be re-raised when awaiting a result here.