Skip to content

prefect.utilities.annotations

BaseAnnotation

Bases: namedtuple('BaseAnnotation', field_names='value'), ABC, Generic[T]

Base class for Prefect annotation types.

Inherits from namedtuple for unpacking support in another tools.

Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/utilities/annotations.py
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
class BaseAnnotation(
    namedtuple("BaseAnnotation", field_names="value"), ABC, Generic[T]
):
    """
    Base class for Prefect annotation types.

    Inherits from `namedtuple` for unpacking support in another tools.
    """

    def unwrap(self) -> T:
        if sys.version_info < (3, 8):
            # cannot simply return self.value due to recursion error in Python 3.7
            # also _asdict does not follow convention; it's not an internal method
            # https://stackoverflow.com/a/26180604
            return self._asdict()["value"]
        else:
            return self.value

    def rewrap(self, value: T) -> "BaseAnnotation[T]":
        return type(self)(value)

    def __eq__(self, other: object) -> bool:
        if not type(self) == type(other):
            return False
        return self.unwrap() == other.unwrap()

    def __repr__(self) -> str:
        return f"{type(self).__name__}({self.value!r})"

NotSet

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

Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/utilities/annotations.py
89
90
91
92
class NotSet:
    """
    Singleton to distinguish `None` from a value that is not provided by the user.
    """

allow_failure

Bases: BaseAnnotation[T]

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.

Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/utilities/annotations.py
53
54
55
56
57
58
59
60
61
62
63
64
65
class allow_failure(BaseAnnotation[T]):
    """
    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

Bases: BaseAnnotation[T]

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.

Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/utilities/annotations.py
68
69
70
71
72
73
74
75
76
class quote(BaseAnnotation[T]):
    """
    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.
    """

    def unquote(self) -> T:
        return self.unwrap()

unmapped

Bases: BaseAnnotation[T]

Wrapper for iterables.

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

Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/utilities/annotations.py
40
41
42
43
44
45
46
47
48
49
50
class unmapped(BaseAnnotation[T]):
    """
    Wrapper for iterables.

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

    def __getitem__(self, _) -> T:
        # Internally, this acts as an infinite array where all items are the same value
        return self.unwrap()