> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# task_engine

# `prefect.task_engine`

## Functions

### `run_task_sync` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1729](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1729)</sup>

```python theme={null}
run_task_sync(task: 'Task[P, R]', task_run_id: Optional[UUID] = None, task_run: Optional[TaskRun] = None, parameters: Optional[dict[str, Any]] = None, wait_for: Optional['OneOrManyFutureOrResult[Any]'] = None, return_type: Literal['state', 'result'] = 'result', dependencies: Optional[dict[str, set[RunInput]]] = None, context: Optional[dict[str, Any]] = None) -> Union[R, State, None]
```

### `run_task_async` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1761](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1761)</sup>

```python theme={null}
run_task_async(task: 'Task[P, R]', task_run_id: Optional[UUID] = None, task_run: Optional[TaskRun] = None, parameters: Optional[dict[str, Any]] = None, wait_for: Optional['OneOrManyFutureOrResult[Any]'] = None, return_type: Literal['state', 'result'] = 'result', dependencies: Optional[dict[str, set[RunInput]]] = None, context: Optional[dict[str, Any]] = None) -> Union[R, State, None]
```

### `run_generator_task_sync` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1793](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1793)</sup>

```python theme={null}
run_generator_task_sync(task: 'Task[P, R]', task_run_id: Optional[UUID] = None, task_run: Optional[TaskRun] = None, parameters: Optional[dict[str, Any]] = None, wait_for: Optional['OneOrManyFutureOrResult[Any]'] = None, return_type: Literal['state', 'result'] = 'result', dependencies: Optional[dict[str, set[RunInput]]] = None, context: Optional[dict[str, Any]] = None) -> Generator[R, None, None]
```

### `run_generator_task_async` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1854](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1854)</sup>

```python theme={null}
run_generator_task_async(task: 'Task[P, R]', task_run_id: Optional[UUID] = None, task_run: Optional[TaskRun] = None, parameters: Optional[dict[str, Any]] = None, wait_for: Optional['OneOrManyFutureOrResult[Any]'] = None, return_type: Literal['state', 'result'] = 'result', dependencies: Optional[dict[str, set[RunInput]]] = None, context: Optional[dict[str, Any]] = None) -> AsyncGenerator[R, None]
```

### `run_task` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1942](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1942)</sup>

```python theme={null}
run_task(task: 'Task[P, Union[R, Coroutine[Any, Any, R]]]', task_run_id: Optional[UUID] = None, task_run: Optional[TaskRun] = None, parameters: Optional[dict[str, Any]] = None, wait_for: Optional['OneOrManyFutureOrResult[Any]'] = None, return_type: Literal['state', 'result'] = 'result', dependencies: Optional[dict[str, set[RunInput]]] = None, context: Optional[dict[str, Any]] = None) -> Union[R, State, None, Coroutine[Any, Any, Union[R, State, None]]]
```

Runs the provided task.

**Args:**

* `task`: The task to run
* `task_run_id`: The ID of the task run; if not provided, a new task run
  will be created
* `task_run`: The task run object; if not provided, a new task run
  will be created
* `parameters`: The parameters to pass to the task
* `wait_for`: A list of futures to wait for before running the task
* `return_type`: The return type to return; either "state" or "result"
* `dependencies`: A dictionary of task run inputs to use for dependency tracking
* `context`: A dictionary containing the context to use for the task run; only
  required if the task is running on in a remote environment

**Returns:**

* The result of the task run

## Classes

### `TaskRunTimeoutError` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L230](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L230)</sup>

Raised when a task run exceeds its timeout.

### `BaseTaskRunEngine` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L235](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L235)</sup>

**Methods:**

#### `compute_transaction_key` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L272](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L272)</sup>

```python theme={null}
compute_transaction_key(self) -> Optional[str]
```

#### `handle_rollback` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L416](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L416)</sup>

```python theme={null}
handle_rollback(self, txn: Transaction) -> None
```

#### `is_cancelled` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L263](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L263)</sup>

```python theme={null}
is_cancelled(self) -> bool
```

#### `is_running` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L372](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L372)</sup>

```python theme={null}
is_running(self) -> bool
```

Whether or not the engine is currently running a task.

#### `log_finished_message` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L378](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L378)</sup>

```python theme={null}
log_finished_message(self) -> None
```

#### `record_terminal_state_timing` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L365](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L365)</sup>

```python theme={null}
record_terminal_state_timing(self, state: State) -> None
```

#### `state` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L258](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L258)</sup>

```python theme={null}
state(self) -> State
```

### `SyncTaskRunEngine` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L433](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L433)</sup>

**Methods:**

#### `asset_context` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L835](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L835)</sup>

```python theme={null}
asset_context(self)
```

#### `begin_run` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L521](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L521)</sup>

```python theme={null}
begin_run(self) -> None
```

#### `call_hooks` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L484](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L484)</sup>

```python theme={null}
call_hooks(self, state: Optional[State] = None) -> None
```

#### `call_task_fn` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1064](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1064)</sup>

```python theme={null}
call_task_fn(self, transaction: Transaction) -> Union[ResultRecord[Any], None, Coroutine[Any, Any, R], R]
```

Convenience method to call the task function. Returns a coroutine if the
task is async.

#### `can_retry` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L443](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L443)</sup>

```python theme={null}
can_retry(self, exc_or_state: Exception | State[R]) -> bool
```

#### `client` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L438](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L438)</sup>

```python theme={null}
client(self) -> SyncPrefectClient
```

#### `handle_crash` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L782](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L782)</sup>

```python theme={null}
handle_crash(self, exc: BaseException) -> None
```

#### `handle_exception` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L752](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L752)</sup>

```python theme={null}
handle_exception(self, exc: Exception) -> None
```

#### `handle_retry` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L693](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L693)</sup>

```python theme={null}
handle_retry(self, exc_or_state: Exception | State[R]) -> bool
```

Handle any task run retries.

* If the task has retries left, and the retry condition is met, set the task to retrying and return True.
* If the task has a retry delay, place in AwaitingRetry state with a delayed scheduled time.
* If the task has no retries left, or the retry condition is not met, return False.

#### `handle_success` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L627](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L627)</sup>

```python theme={null}
handle_success(self, result: R, transaction: Transaction) -> Union[ResultRecord[R], None, Coroutine[Any, Any, R], R]
```

#### `handle_timeout` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L767](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L767)</sup>

```python theme={null}
handle_timeout(self, exc: TimeoutError) -> None
```

#### `initialize_run` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L853](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L853)</sup>

```python theme={null}
initialize_run(self, task_run_id: Optional[UUID] = None, dependencies: Optional[dict[str, set[RunInput]]] = None) -> Generator[Self, Any, Any]
```

Enters a client context and creates a task run if needed.

#### `result` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L612](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L612)</sup>

```python theme={null}
result(self, raise_on_failure: bool = True) -> 'Union[R, State, None]'
```

#### `run_context` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1028](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1028)</sup>

```python theme={null}
run_context(self)
```

#### `set_state` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L561](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L561)</sup>

```python theme={null}
set_state(self, state: State[R], force: bool = False) -> State[R]
```

#### `setup_run_context` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L792](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L792)</sup>

```python theme={null}
setup_run_context(self, client: Optional[SyncPrefectClient] = None)
```

#### `start` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L957](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L957)</sup>

```python theme={null}
start(self, task_run_id: Optional[UUID] = None, dependencies: Optional[dict[str, set[RunInput]]] = None) -> Generator[None, None, None]
```

#### `transaction_context` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1001](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1001)</sup>

```python theme={null}
transaction_context(self) -> Generator[Transaction, None, None]
```

#### `wait_until_ready` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L934](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L934)</sup>

```python theme={null}
wait_until_ready(self) -> None
```

Sync version: Waits until the scheduled time (if its the future), then enters Running.

### `AsyncTaskRunEngine` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1081](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1081)</sup>

**Methods:**

#### `asset_context` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1500](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1500)</sup>

```python theme={null}
asset_context(self)
```

#### `begin_run` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1166](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1166)</sup>

```python theme={null}
begin_run(self) -> None
```

#### `call_hooks` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1129](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1129)</sup>

```python theme={null}
call_hooks(self, state: Optional[State] = None) -> None
```

#### `call_task_fn` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1713](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1713)</sup>

```python theme={null}
call_task_fn(self, transaction: AsyncTransaction) -> Union[ResultRecord[Any], None, Coroutine[Any, Any, R], R]
```

Convenience method to call the task function. Returns a coroutine if the
task is async.

#### `can_retry` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1091](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1091)</sup>

```python theme={null}
can_retry(self, exc_or_state: Exception | State[R]) -> bool
```

#### `client` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1086](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1086)</sup>

```python theme={null}
client(self) -> PrefectClient
```

#### `handle_crash` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1446](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1446)</sup>

```python theme={null}
handle_crash(self, exc: BaseException) -> None
```

#### `handle_exception` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1413](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1413)</sup>

```python theme={null}
handle_exception(self, exc: Exception) -> None
```

#### `handle_retry` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1353](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1353)</sup>

```python theme={null}
handle_retry(self, exc_or_state: Exception | State[R]) -> bool
```

Handle any task run retries.

* If the task has retries left, and the retry condition is met, set the task to retrying and return True.
* If the task has a retry delay, place in AwaitingRetry state with a delayed scheduled time.
* If the task has no retries left, or the retry condition is not met, return False.

#### `handle_success` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1288](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1288)</sup>

```python theme={null}
handle_success(self, result: R, transaction: AsyncTransaction) -> Union[ResultRecord[R], None, Coroutine[Any, Any, R], R]
```

#### `handle_timeout` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1429](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1429)</sup>

```python theme={null}
handle_timeout(self, exc: TimeoutError) -> None
```

#### `initialize_run` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1518](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1518)</sup>

```python theme={null}
initialize_run(self, task_run_id: Optional[UUID] = None, dependencies: Optional[dict[str, set[RunInput]]] = None) -> AsyncGenerator[Self, Any]
```

Enters a client context and creates a task run if needed.

#### `result` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1273](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1273)</sup>

```python theme={null}
result(self, raise_on_failure: bool = True) -> 'Union[R, State, None]'
```

#### `run_context` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1693](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1693)</sup>

```python theme={null}
run_context(self)
```

#### `set_state` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1220](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1220)</sup>

```python theme={null}
set_state(self, state: State, force: bool = False) -> State
```

#### `setup_run_context` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1457](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1457)</sup>

```python theme={null}
setup_run_context(self, client: Optional[PrefectClient] = None)
```

#### `start` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1621](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1621)</sup>

```python theme={null}
start(self, task_run_id: Optional[UUID] = None, dependencies: Optional[dict[str, set[RunInput]]] = None) -> AsyncGenerator[None, None]
```

#### `transaction_context` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1667](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1667)</sup>

```python theme={null}
transaction_context(self) -> AsyncGenerator[AsyncTransaction, None]
```

#### `wait_until_ready` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task\_engine.py#L1598](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/task_engine.py#L1598)</sup>

```python theme={null}
wait_until_ready(self) -> None
```

Waits until the scheduled time (if its the future), then enters Running.