prefect.futures

Functions

as_completed ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L590" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

as_completed(futures: list[PrefectFuture[R]], timeout: float | None = None) -> Generator[PrefectFuture[R], None]

wait ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L641" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

wait(futures: list[PrefectFuture[R]], timeout: float | None = None) -> DoneAndNotDoneFutures[R]

Wait for the futures in the given sequence to complete.

Args:

• futures: The sequence of Futures to wait upon.
• timeout: The maximum number of seconds to wait. If None, then there is no limit on the wait time.

Returns:

• A named 2-tuple of sets. The first set, named 'done', contains the
• futures that completed (is finished or cancelled) before the wait
• completed. The second set, named 'not_done', contains uncompleted
• futures. Duplicate futures given to futures are removed and will be
• returned only once.

Examples:

@task
def sleep_task(seconds):
    sleep(seconds)
    return 42

@flow
def flow():
    futures = random_task.map(range(10))
    done, not_done = wait(futures, timeout=5)
    print(f"Done: {len(done)}")
    print(f"Not Done: {len(not_done)}")

resolve_futures_to_states ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L734" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

resolve_futures_to_states(expr: PrefectFuture[R] | Any) -> PrefectFuture[R] | Any

Given a Python built-in collection, recursively find PrefectFutures and build a new collection with the same structure with futures resolved to their final states. Resolving futures to their final states may wait for execution to complete.

Unsupported object types will be returned without modification.

resolve_futures_to_results ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L755" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

resolve_futures_to_results(expr: PrefectFuture[R] | Any) -> Any

Given a Python built-in collection, recursively find PrefectFutures and build a new collection with the same structure with futures resolved to their final results. Resolving futures to their final result may wait for execution to complete.

Unsupported object types will be returned without modification.

Classes

PrefectFuture ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L36" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Abstract base class for Prefect futures. A Prefect future is a handle to the asynchronous execution of a run. It provides methods to wait for the to complete and to retrieve the result of the run.

Methods:

add_done_callback ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L121" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

add_done_callback(self, fn: Callable[['PrefectFuture[R]'], None]) -> None

Add a callback to be run when the future completes or is cancelled.

Args:

• fn: A callable that will be called with this future as its only argument when the future completes or is cancelled.

result ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L100" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

result(self, timeout: float | None = None, raise_on_failure: bool = True) -> R

state ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L66" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

state(self) -> State

The current state of the task run associated with this future

task_run_id ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L54" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

task_run_id(self) -> uuid.UUID

The ID of the task run associated with this future

wait ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L87" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

wait(self, timeout: float | None = None) -> None

PrefectTaskRunFuture ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L131" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

A Prefect future that represents the eventual execution of a task run.

Methods:

state ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L146" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

state(self) -> State

The current state of the task run associated with this future

task_run_id ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L141" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

task_run_id(self) -> uuid.UUID

The ID of the task run associated with this future

PrefectWrappedFuture ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L160" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

A Prefect future that wraps another future object.

Methods:

add_done_callback ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L178" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

add_done_callback(self, fn: Callable[[PrefectFuture[R]], None]) -> None

Add a callback to be executed when the future completes.

wrapped_future ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L174" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

wrapped_future(self) -> F

The underlying future object wrapped by this Prefect future

PrefectConcurrentFuture ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L191" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

A Prefect future that wraps a concurrent.futures.Future. This future is used when the task run is submitted to a ThreadPoolExecutor.

Methods:

result ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L243" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

result(self, timeout: float | None = None, raise_on_failure: bool = True) -> R

wait ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L235" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

wait(self, timeout: float | None = None) -> None

PrefectDistributedFuture ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L268" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

Represents the result of a computation happening anywhere.

This class is typically used to interact with the result of a task run scheduled to run in a Prefect task worker but can be used to interact with any task run scheduled in Prefect's API.

Methods:

add_done_callback ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L358" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

add_done_callback(self, fn: Callable[[PrefectFuture[R]], None]) -> None

result ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L328" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

result(self, timeout: float | None = None, raise_on_failure: bool = True) -> R

result_async ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L337" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

result_async(self, timeout: float | None = None, raise_on_failure: bool = True) -> R

wait ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L280" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

wait(self, timeout: float | None = None) -> None

wait_async ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L283" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

wait_async(self, timeout: float | None = None) -> None

PrefectFlowRunFuture ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L380" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

A Prefect future that represents the eventual execution of a flow run.

Methods:

add_done_callback ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L485" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

add_done_callback(self, fn: Callable[[PrefectFuture[R]], None]) -> None

aresult ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L471" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

aresult(self, timeout: float | None = None, raise_on_failure: bool = True) -> R

flow_run_id ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L390" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

flow_run_id(self) -> uuid.UUID

The ID of the flow run associated with this future

result ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L462" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

result(self, timeout: float | None = None, raise_on_failure: bool = True) -> R

state ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L395" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

state(self) -> State

The current state of the flow run associated with this future

wait ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L410" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

wait(self, timeout: float | None = None) -> None

wait_async ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L413" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

wait_async(self, timeout: float | None = None) -> None

PrefectFutureList ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L507" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

A list of Prefect futures.

This class provides methods to wait for all futures in the list to complete and to retrieve the results of all task runs.

Methods:

result ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L525" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

result(self: Self, timeout: float | None = None, raise_on_failure: bool = True) -> list[R]

Get the results of all task runs associated with the futures in the list.

Uses as_completed internally so that failures are raised as soon as they occur rather than waiting for earlier, still-running futures to finish first.

Args:

• timeout: The maximum number of seconds to wait for all futures to complete.
• raise_on_failure: If True, an exception will be raised if any task run fails.

Returns:

• A list of results of the task runs, in the same order as the
• futures in the list.

Raises:

• TimeoutError: If the timeout is reached before all futures complete.

wait ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L515" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

wait(self, timeout: float | None = None) -> None

Wait for all futures in the list to complete.

Args:

• timeout: The maximum number of seconds to wait for all futures to complete. This method will not raise if the timeout is reached.

DoneAndNotDoneFutures ^{<a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/futures.py#L631" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a>}

A named 2-tuple of sets.

multiple inheritance supported in 3.11+, use typing_extensions.NamedTuple