Skip to content

API reference

map_unordered async

map_unordered(
    function_name: str,
    inputs: list[Any],
    /,
    *,
    input_key: str,
    constant_args: dict[str, Any] | None = None,
    memory: int | None = None,
    endpoint_url: str | None = None,
    project: str | None = None,
    dispatchers: int | Literal["auto"] = "auto",
    concurrency: int = DEFAULT_CONCURRENCY,
    retries: int = 2,
    on_progress: Callable[[int], None] | None = None,
    dispatcher_stats: list[dict[str, Any]] | None = None,
    invocation_stats: list[dict[str, Any]] | None = None,
) -> AsyncGenerator[tuple[int, Any], None]

Invoke function_name once per value of inputs, yielding (index, output) as each output comes back. If outputs are not needed, use for_each.

Refer to Session.map_unordered for argument definitions.

endpoint_url onwards are the dispatch settings documented on Session, applied to a session opened for this call alone - which closes when the iterator does, so stopping early still shuts the client down.

Yields:

Type Description
AsyncGenerator[tuple[int, Any], None]

(index, output), in the order the invocations finished.

for_each async

for_each(
    function_name: str,
    inputs: list[Any],
    /,
    *,
    input_key: str,
    constant_args: dict[str, Any] | None = None,
    memory: int | None = None,
    endpoint_url: str | None = None,
    project: str | None = None,
    dispatchers: int | Literal["auto"] = "auto",
    concurrency: int = DEFAULT_CONCURRENCY,
    retries: int = 2,
    on_progress: Callable[[int], None] | None = None,
    dispatcher_stats: list[dict[str, Any]] | None = None,
    invocation_stats: list[dict[str, Any]] | None = None,
) -> None

Invoke function_name once for each value of inputs. This is the same as map_unordered except nothing is returned.

Refer to Session.map_unordered for argument definitions.

Session dataclass

Session(
    endpoint_url: str | None = None,
    project: str | None = None,
    dispatchers: int | Literal["auto"] = "auto",
    concurrency: int = DEFAULT_CONCURRENCY,
    retries: int = 2,
    on_progress: Callable[[int], None] | None = None,
    dispatcher_stats: list[dict[str, Any]] | None = None,
    invocation_stats: list[dict[str, Any]] | None = None,
)

The deployed lambdas, holding settings and stats for a session. Use as async with.

endpoint_url class-attribute instance-attribute

endpoint_url: str | None = None

None uses AWS with credentials and region picked up from the local environment; LOCAL_ENDPOINT_URL uses a local cargo lambda watch instead.

project class-attribute instance-attribute

project: str | None = None

The project the lambdas were deployed as, which prefixes every name on AWS: the dispatcher is <project>-dispatcher, and a worker "copy" is <project>-copy. None uses the names as given. Against a local cargo lambda watch, names are never prefixed, as it serves each function under its binary's name.

dispatchers class-attribute instance-attribute

dispatchers: int | Literal['auto'] = 'auto'

The number of dispatchers the inputs are partitioned across.

"auto" uses the fewest number of dispatchers that respects AWS Lambda limits.

concurrency class-attribute instance-attribute

concurrency: int = DEFAULT_CONCURRENCY

The total number of worker lambdas in flight for the whole call, split across dispatchers.

retries class-attribute instance-attribute

retries: int = 2

How many times to retry a failed request to Lambda (per invocation). The default is 2, which is 3 attempts in total. A worker that ran and raised is never retried: the same payload gets the same output.

on_progress class-attribute instance-attribute

on_progress: Callable[[int], None] | None = None

Called as invocations complete, with how many more have since the last call.

dispatcher_stats class-attribute instance-attribute

dispatcher_stats: list[dict[str, Any]] | None = None

Pass a list to collect stats for the dispatchers - one record per dispatcher invocation. A call stops at its first failed invocation without waiting for these, so it collects none. Each record holds:

  • req_id - AWS's id for the dispatcher's own invocation, for finding its run in CloudWatch
  • dispatched - invocations it sent, which is its partition's size
  • retried - attempts beyond the first, across the partition
  • retry_wait_ms - summed wait before those attempts
  • cold - whether the execution environment was cold, or None for a local run, which has no shared client set to build
  • connections - HTTP/2 connections the invocations were spread over
  • elapsed_ms - how long the partition took
  • call - which map_unordered or for_each of the session this was
  • call_start - when that call began, as epoch seconds

invocation_stats class-attribute instance-attribute

invocation_stats: list[dict[str, Any]] | None = None

Pass a list to collect stats for the function invocations - one record per worker function invocation, holding:

  • index - the position in inputs of the input it ran
  • req_id - AWS's id for the worker invocation, for joining to CloudWatch. Empty against cargo lambda watch, which assigns none
  • invoke_start, invoke_end - epoch seconds, spanning every attempt
  • call, call_start - as in dispatcher_stats

function_name

function_name(
    name: str, /, *, memory: int | None = None
) -> str

The name a call to name invokes, such as <project>-copy-3538 on AWS, for finding the function's logs or metrics. Works whether or not the session is open.

map_unordered

map_unordered(
    function_name: str,
    inputs: list[Any],
    /,
    *,
    input_key: str,
    constant_args: dict[str, Any] | None = None,
    memory: int | None = None,
) -> AsyncGenerator[tuple[int, Any], None]

Invoke function_name once per value of inputs, yielding (index, output) as each output comes back. If outputs are not needed, use for_each.

Each worker's payload is a dict with the input value under input_key, plus a copy of constant_args (if supplied).

Parameters:

Name Type Description Default
function_name str

The worker's name in its project, such as "copy".

required
inputs list[Any]

The values to pass to the function, one entry per invocation.

required
input_key str

The name of the key for the input in each worker's payload. Must match the field the worker deserialises it into: for a Rust worker, a field of its Request struct.

required
constant_args dict[str, Any] | None

Optional extra arguments to pass to each function invocation.

None
memory int | None

Which of the worker's deployed memory sizes to use, in MB, or None for its default. On AWS this calls <name>-<memory>.

None

Yields:

Type Description
AsyncGenerator[tuple[int, Any], None]

(index, output), in the order the invocations finished.

for_each async

for_each(
    function_name: str,
    inputs: list[Any],
    /,
    *,
    input_key: str,
    constant_args: dict[str, Any] | None = None,
    memory: int | None = None,
) -> None

Invoke function_name once for each value of inputs. This is the same as map_unordered except nothing is returned, and it waits for the whole call.

Refer to map_unordered for argument definitions.

invoke_detached async

invoke_detached(
    function_name: str, /, **payload: Any
) -> None

Invoke function_name once with the given payload and do not wait for it.

Useful for "fire and forget" semantics, where failing after submission and not learning about the failure is acceptable - failing to submit raises. For a synchronous one-off, use for_each with a single input.

LOCAL_ENDPOINT_URL module-attribute

LOCAL_ENDPOINT_URL = _native.LOCAL_ENDPOINT_URL

DEFAULT_CONCURRENCY module-attribute

DEFAULT_CONCURRENCY: int = _native.DEFAULT_CONCURRENCY

Stats

stats

What calls recorded about themselves, and how to render it.

Two kinds of record, one per level, each collected only when a caller passes Session a list:

Every record carries call, the 0-based index of the map_unordered or for_each call it came from, and call_start, time.time() when that call began. Records group by call because it is an index: two calls that read the same clock value would merge on a timestamp.

An invocation's duration is time queued for a connection, plus the round trip, plus execution.

summarize_dispatchers

summarize_dispatchers(dispatcher_stats: list[Stats]) -> str

A short human-readable summary of dispatchers.

summarize_invocations

summarize_invocations(
    invocation_stats: list[Stats],
    elapsed: float | None = None,
    max_pool_connections: int | None = None,
) -> str

A short human-readable summary of invocation timings.

elapsed is the caller's wall clock. Without it the wall time and rate are left out rather than derived from the records, whose span starts at the first invocation rather than at the call.

write_jsonl

write_jsonl(stats: list[Stats], path: str | Path) -> None

Write one JSON object per record.

read_jsonl

read_jsonl(path: str | Path) -> list[Stats]

Read back what write_jsonl wrote.

Timeline

timeline

A timeline of invocations: one row per invocation, showing when its call began, when it went on the wire, when the function actually ran, and when it came back.

Adapted from cubed's cubed/diagnostics/timeline.py.

generate_timeline

generate_timeline(
    records: Sequence[Stats],
    title: str | None = None,
    max_points: int = DEFAULT_MAX_POINTS,
) -> Any

Build the figure. Returns a matplotlib Figure for the caller to save.

matplotlib is imported lazily: it is an optional extra (map-lambda[diagnostics]).