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: Optional[str] = None,
    api_url: Optional[str] = None,
)

Client for the Dispatch API.

Parameters:

Name Type Description Default
api_key Optional[str]

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

 None
api_url Optional[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 async ¤

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.

Registry ¤

Registry(
    name: str,
    client: Optional[Client] = None,
    endpoint: Optional[str] = None,
)

Registry of functions.

Parameters:

Name Type Description Default
name str

A unique name for the registry.

 required
endpoint Optional[str]

URL of the endpoint that the function is accessible from.

 None
client Optional[Client]

Client instance to use for dispatching calls to registered functions. Defaults to creating a new client instance.

 None

Raises:

Type Description
ValueError

If any of the required arguments are missing.

close ¤

close()

Closes the registry, removing it and all its functions from the dispatch application.

function ¤

function(func)

Decorator that registers functions.

primitive_function ¤

primitive_function(
    primitive_func: PrimitiveFunctionType,
) -> PrimitiveFunction

Decorator that registers primitive functions.

batch ¤

batch() -> Batch

Returns a Batch instance that can be used to build a set of calls to dispatch.

Reset ¤

Reset(
    func: Union[
        AsyncFunction[P, T], BlockingFunction[P, T]
    ],
    *args: args,
    **kwargs: kwargs
)

Bases: TailCall

The current coroutine is aborted and scheduling reset to be replaced with the call embedded in this exception.

Call dataclass ¤

Call(
    function: str,
    input: Optional[Any] = None,
    endpoint: Optional[str] = None,
    correlation_id: Optional[int] = None,
)

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: Optional[Exception] = None,
    traceback: Optional[bytes] = 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 Optional[Exception]

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: Optional[Status] = 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: Optional[Status] = 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, status: Status = Status.OK
) -> Output

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

exit classmethod ¤

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

Terminally exit the function.

poll classmethod ¤

poll(
    coroutine_state: Any = None,
    calls: Optional[List[Call]] = None,
    min_results: int = 1,
    max_results: int = 10,
    max_wait_seconds: Optional[int] = 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.

all ¤

all(*awaitables: Awaitable[Any]) -> List[Any]

Concurrently run a set of coroutines, blocking until all coroutines return or any coroutine raises an error. If any coroutine fails with an uncaught exception, the exception will be re-raised here.

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]

Alias for all.

race ¤

race(*awaitables: Awaitable[Any]) -> List[Any]

Concurrently run a set of coroutines, blocking until any coroutine returns or raises an error. If any coroutine fails with an uncaught exception, the exception will be re-raised here.

run ¤

run(
    coro: Coroutine[Any, Any, T],
    addr: Optional[str] = None,
) -> T

Run the default Dispatch server. The default server uses a function registry where functions tagged by the @dispatch.function decorator are registered.

This function is intended to be used with the dispatch CLI tool, which automatically configures environment variables to connect the local server to the Dispatch bridge API.

Parameters:

Name Type Description Default
coro Coroutine[Any, Any, T]

The coroutine to run as the entrypoint, the function returns when the coroutine returns.

 required
addr Optional[str]

The address to bind the server to. If not provided, the server will bind to the address specified by the DISPATCH_ENDPOINT_ADDR environment variable. If the environment variable is not set, the server will bind to localhost:8000.

 None

Returns:

Type Description
T

The value returned by the coroutine.