prefect.utilities.annotations

Classes

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

Base class for Prefect annotation types.

Inherits from tuple for unpacking support in other tools.

Methods:

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

rewrap(self, value: T) -> Self

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

unwrap(self) -> T

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

Wrapper for iterables.

Indicates that this input should be sent as-is to all runs created during a mapping operation instead of being split.

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

Wrapper for states or futures.

Indicates that the upstream run for this input can be failed.

Generally, Prefect will not allow a downstream run to start if any of its inputs are failed. This annotation allows you to opt into receiving a failed input downstream.

If the input is from a failed run, the attached exception will be passed to your function.

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

Simple wrapper to mark an expression as a different type so it will not be coerced by Prefect. For example, if you want to return a state from a flow without having the flow assume that state.

quote will also instruct prefect to ignore introspection of the wrapped object when passed as flow or task parameter. Parameter introspection can be a significant performance hit when the object is a large collection, e.g. a large dictionary or DataFrame, and each element needs to be visited. This will disable task dependency tracking for the wrapped object, but likely will increase performance.

@task
def my_task(df):
    ...

@flow
def my_flow():
    my_task(quote(df))

Methods:

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

unquote(self) -> T

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

Wrapper for task inputs that resolves the top-level value but prevents recursive traversal into its contents.

When a PrefectFuture (or State) is wrapped with opaque, Prefect will wait for the future and return its result, but will not walk into the resolved object looking for nested futures, states, or task-run inputs. This avoids the expensive CPU-bound traversal that visit_collection performs on large results (big dicts, DataFrames, etc.) while still preserving the ergonomic .submit() chaining pattern.

Semantics compared with other annotations:

• No annotation — resolve and recursively traverse (default).
• quote — do not resolve, do not traverse.
• opaque — resolve the top-level value, but do not traverse into its contents.

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

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

Singleton to distinguish None from a value that is not provided by the user.

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

Wrapper for parameters in deployments.

Indicates that this parameter should be frozen in the UI and not editable when creating flow runs from this deployment.

Example:

@flow
def my_flow(customer_id: str):
    # flow logic

deployment = my_flow.deploy(parameters={"customer_id": freeze("customer123")})

Methods:

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

unfreeze(self) -> T

Return the unwrapped value.