Skip to content

prefect.server.schemas.states

State schemas.

State

Bases: StateBaseModel, Generic[R]

Represents the state of a run.

Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/schemas/states.py 
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
class State(StateBaseModel, Generic[R]):
    """Represents the state of a run."""

    class Config:
        orm_mode = True

    type: StateType
    name: Optional[str] = Field(default=None)
    timestamp: DateTimeTZ = Field(default_factory=lambda: pendulum.now("UTC"))
    message: Optional[str] = Field(default=None, example="Run started")
    data: Optional[Any] = Field(
        default=None,
        description=(
            "Data associated with the state, e.g. a result. "
            "Content must be storable as JSON."
        ),
    )
    state_details: StateDetails = Field(default_factory=StateDetails)

    @classmethod
    def from_orm_without_result(
        cls,
        orm_state: Union[
            "prefect.server.database.orm_models.ORMFlowRunState",
            "prefect.server.database.orm_models.ORMTaskRunState",
        ],
        with_data: Optional[Any] = None,
    ):
        """
        During orchestration, ORM states can be instantiated prior to inserting results
        into the artifact table and the `data` field will not be eagerly loaded. In
        these cases, sqlalchemy will attempt to lazily load the the relationship, which
        will fail when called within a synchronous pydantic method.

        This method will construct a `State` object from an ORM model without a loaded
        artifact and attach data passed using the `with_data` argument to the `data`
        field.
        """

        field_keys = cls.schema()["properties"].keys()
        state_data = {
            field: getattr(orm_state, field, None)
            for field in field_keys
            if field != "data"
        }
        state_data["data"] = with_data
        return cls(**state_data)

    @validator("name", always=True)
    def default_name_from_type(cls, v, *, values, **kwargs):
        """If a name is not provided, use the type"""

        # if `type` is not in `values` it means the `type` didn't pass its own
        # validation check and an error will be raised after this function is called
        if v is None and values.get("type"):
            v = " ".join([v.capitalize() for v in values.get("type").value.split("_")])
        return v

    @root_validator
    def default_scheduled_start_time(cls, values):
        """
        TODO: This should throw an error instead of setting a default but is out of
              scope for https://github.com/PrefectHQ/orion/pull/174/ and can be rolled
              into work refactoring state initialization
        """
        if values.get("type") == StateType.SCHEDULED:
            state_details = values.setdefault(
                "state_details", cls.__fields__["state_details"].get_default()
            )
            if not state_details.scheduled_time:
                state_details.scheduled_time = pendulum.now("utc")
        return values

    def is_scheduled(self) -> bool:
        return self.type == StateType.SCHEDULED

    def is_pending(self) -> bool:
        return self.type == StateType.PENDING

    def is_running(self) -> bool:
        return self.type == StateType.RUNNING

    def is_completed(self) -> bool:
        return self.type == StateType.COMPLETED

    def is_failed(self) -> bool:
        return self.type == StateType.FAILED

    def is_crashed(self) -> bool:
        return self.type == StateType.CRASHED

    def is_cancelled(self) -> bool:
        return self.type == StateType.CANCELLED

    def is_cancelling(self) -> bool:
        return self.type == StateType.CANCELLING

    def is_final(self) -> bool:
        return self.type in TERMINAL_STATES

    def is_paused(self) -> bool:
        return self.type == StateType.PAUSED

    def copy(self, *, update: dict = None, reset_fields: bool = False, **kwargs):
        """
        Copying API models should return an object that could be inserted into the
        database again. The 'timestamp' is reset using the default factory.
        """
        update = update or {}
        update.setdefault("timestamp", self.__fields__["timestamp"].get_default())
        return super().copy(reset_fields=reset_fields, update=update, **kwargs)

    def result(self, raise_on_failure: bool = True, fetch: Optional[bool] = None):
        # Backwards compatible `result` handling on the server-side schema
        from prefect.states import State

        warnings.warn(
            (
                "`result` is no longer supported by"
                " `prefect.server.schemas.states.State` and will be removed in a future"
                " release. When result retrieval is needed, use `prefect.states.State`."
            ),
            DeprecationWarning,
            stacklevel=2,
        )

        state = State.parse_obj(self)
        return state.result(raise_on_failure=raise_on_failure, fetch=fetch)

    def to_state_create(self):
        # Backwards compatibility for `to_state_create`
        from prefect.client.schemas import State

        warnings.warn(
            (
                "Use of `prefect.server.schemas.states.State` from the client is"
                " deprecated and support will be removed in a future release. Use"
                " `prefect.states.State` instead."
            ),
            DeprecationWarning,
            stacklevel=2,
        )

        state = State.parse_obj(self)
        return state.to_state_create()

    def __repr__(self) -> str:
        """
        Generates a complete state representation appropriate for introspection
        and debugging, including the result:

        `MyCompletedState(message="my message", type=COMPLETED, result=...)`
        """
        from prefect.deprecated.data_documents import DataDocument

        if isinstance(self.data, DataDocument):
            result = self.data.decode()
        else:
            result = self.data

        display = dict(
            message=repr(self.message),
            type=str(self.type.value),
            result=repr(result),
        )

        return f"{self.name}({', '.join(f'{k}={v}' for k, v in display.items())})"

    def __str__(self) -> str:
        """
        Generates a simple state representation appropriate for logging:

        `MyCompletedState("my message", type=COMPLETED)`
        """

        display = []

        if self.message:
            display.append(repr(self.message))

        if self.type.value.lower() != self.name.lower():
            display.append(f"type={self.type.value}")

        return f"{self.name}({', '.join(display)})"

    def __hash__(self) -> int:
        return hash(
            (
                getattr(self.state_details, "flow_run_id", None),
                getattr(self.state_details, "task_run_id", None),
                self.timestamp,
                self.type,
            )
        )

from_orm_without_result classmethod

During orchestration, ORM states can be instantiated prior to inserting results into the artifact table and the data field will not be eagerly loaded. In these cases, sqlalchemy will attempt to lazily load the the relationship, which will fail when called within a synchronous pydantic method.

This method will construct a State object from an ORM model without a loaded artifact and attach data passed using the with_data argument to the data field.

Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/schemas/states.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
@classmethod
def from_orm_without_result(
    cls,
    orm_state: Union[
        "prefect.server.database.orm_models.ORMFlowRunState",
        "prefect.server.database.orm_models.ORMTaskRunState",
    ],
    with_data: Optional[Any] = None,
):
    """
    During orchestration, ORM states can be instantiated prior to inserting results
    into the artifact table and the `data` field will not be eagerly loaded. In
    these cases, sqlalchemy will attempt to lazily load the the relationship, which
    will fail when called within a synchronous pydantic method.

    This method will construct a `State` object from an ORM model without a loaded
    artifact and attach data passed using the `with_data` argument to the `data`
    field.
    """

    field_keys = cls.schema()["properties"].keys()
    state_data = {
        field: getattr(orm_state, field, None)
        for field in field_keys
        if field != "data"
    }
    state_data["data"] = with_data
    return cls(**state_data)

json

Returns a representation of the model as JSON.

If include_secrets=True, then SecretStr and SecretBytes objects are fully revealed. Otherwise they are obfuscated.

Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/_internal/schemas/bases.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def json(self, *args, include_secrets: bool = False, **kwargs) -> str:
    """
    Returns a representation of the model as JSON.

    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are
    fully revealed. Otherwise they are obfuscated.

    """
    if include_secrets:
        if "encoder" in kwargs:
            raise ValueError(
                "Alternative encoder provided; can not set encoder for"
                " SecretFields."
            )
        kwargs["encoder"] = partial(
            custom_pydantic_encoder,
            {SecretField: lambda v: v.get_secret_value() if v else None},
        )
    return super().json(*args, **kwargs)

subclass classmethod

Creates a subclass of this model containing only the specified fields.

See pydantic_subclass().

Parameters:

Name Type Description Default
name str

a name for the subclass

 None
include_fields List[str]

fields to include

 None
exclude_fields List[str]

fields to exclude

 None

Returns:

Name Type Description
BaseModel Type[B]

a subclass of this class
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/utilities/schemas.py 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
@classmethod
def subclass(
    cls: Type[B],
    name: str = None,
    include_fields: List[str] = None,
    exclude_fields: List[str] = None,
) -> Type[B]:
    """Creates a subclass of this model containing only the specified fields.

    See `pydantic_subclass()`.

    Args:
        name (str, optional): a name for the subclass
        include_fields (List[str], optional): fields to include
        exclude_fields (List[str], optional): fields to exclude

    Returns:
        BaseModel: a subclass of this class
    """
    return pydantic_subclass(
        base=cls,
        name=name,
        include_fields=include_fields,
        exclude_fields=exclude_fields,
    )

StateBaseModel

Bases: IDBaseModel

Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/schemas/states.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
class StateBaseModel(IDBaseModel):
    def orm_dict(
        self, *args, shallow: bool = False, json_compatible: bool = False, **kwargs
    ) -> dict:
        """
        This method is used as a convenience method for constructing fixtues by first
        building a `State` schema object and converting it into an ORM-compatible
        format. Because the `data` field is not writable on ORM states, this method
        omits the `data` field entirely for the purposes of constructing an ORM model.
        If state data is required, an artifact must be created separately.
        """

        schema_dict = self.dict(
            *args, shallow=shallow, json_compatible=json_compatible, **kwargs
        )
        # remove the data field in order to construct a state ORM model
        schema_dict.pop("data", None)
        return schema_dict

json

Returns a representation of the model as JSON.

If include_secrets=True, then SecretStr and SecretBytes objects are fully revealed. Otherwise they are obfuscated.

Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/_internal/schemas/bases.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def json(self, *args, include_secrets: bool = False, **kwargs) -> str:
    """
    Returns a representation of the model as JSON.

    If `include_secrets=True`, then `SecretStr` and `SecretBytes` objects are
    fully revealed. Otherwise they are obfuscated.

    """
    if include_secrets:
        if "encoder" in kwargs:
            raise ValueError(
                "Alternative encoder provided; can not set encoder for"
                " SecretFields."
            )
        kwargs["encoder"] = partial(
            custom_pydantic_encoder,
            {SecretField: lambda v: v.get_secret_value() if v else None},
        )
    return super().json(*args, **kwargs)

subclass classmethod

Creates a subclass of this model containing only the specified fields.

See pydantic_subclass().

Parameters:

Name Type Description Default
name str

a name for the subclass

 None
include_fields List[str]

fields to include

 None
exclude_fields List[str]

fields to exclude

 None

Returns:

Name Type Description
BaseModel Type[B]

a subclass of this class
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/utilities/schemas.py 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
@classmethod
def subclass(
    cls: Type[B],
    name: str = None,
    include_fields: List[str] = None,
    exclude_fields: List[str] = None,
) -> Type[B]:
    """Creates a subclass of this model containing only the specified fields.

    See `pydantic_subclass()`.

    Args:
        name (str, optional): a name for the subclass
        include_fields (List[str], optional): fields to include
        exclude_fields (List[str], optional): fields to exclude

    Returns:
        BaseModel: a subclass of this class
    """
    return pydantic_subclass(
        base=cls,
        name=name,
        include_fields=include_fields,
        exclude_fields=exclude_fields,
    )

StateType

Bases: AutoEnum

Enumeration of state types.

Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/schemas/states.py 
22
23
24
25
26
27
28
29
30
31
32
33
class StateType(AutoEnum):
    """Enumeration of state types."""

    SCHEDULED = AutoEnum.auto()
    PENDING = AutoEnum.auto()
    RUNNING = AutoEnum.auto()
    COMPLETED = AutoEnum.auto()
    FAILED = AutoEnum.auto()
    CANCELLED = AutoEnum.auto()
    CRASHED = AutoEnum.auto()
    PAUSED = AutoEnum.auto()
    CANCELLING = AutoEnum.auto()

auto staticmethod

Exposes enum.auto() to avoid requiring a second import to use AutoEnum

Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/utilities/collections.py 
59
60
61
62
63
64
@staticmethod
def auto():
    """
    Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum`
    """
    return auto()

AwaitingRetry

Convenience function for creating AwaitingRetry states.

Returns:

Name Type Description
State State

a AwaitingRetry state
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/schemas/states.py 
394
395
396
397
398
399
400
401
402
403
404
def AwaitingRetry(
    scheduled_time: datetime.datetime = None, cls: Type[State] = State, **kwargs
) -> State:
    """Convenience function for creating `AwaitingRetry` states.

    Returns:
        State: a AwaitingRetry state
    """
    return Scheduled(
        cls=cls, scheduled_time=scheduled_time, name="AwaitingRetry", **kwargs
    )

Cancelled

Convenience function for creating Cancelled states.

Returns:

Name Type Description
State State

a Cancelled state
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/schemas/states.py 
340
341
342
343
344
345
346
def Cancelled(cls: Type[State] = State, **kwargs) -> State:
    """Convenience function for creating `Cancelled` states.

    Returns:
        State: a Cancelled state
    """
    return cls(type=StateType.CANCELLED, **kwargs)

Cancelling

Convenience function for creating Cancelling states.

Returns:

Name Type Description
State State

a Cancelling state
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/schemas/states.py 
331
332
333
334
335
336
337
def Cancelling(cls: Type[State] = State, **kwargs) -> State:
    """Convenience function for creating `Cancelling` states.

    Returns:
        State: a Cancelling state
    """
    return cls(type=StateType.CANCELLING, **kwargs)

Completed

Convenience function for creating Completed states.

Returns:

Name Type Description
State State

a Completed state
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/schemas/states.py 
295
296
297
298
299
300
301
def Completed(cls: Type[State] = State, **kwargs) -> State:
    """Convenience function for creating `Completed` states.

    Returns:
        State: a Completed state
    """
    return cls(type=StateType.COMPLETED, **kwargs)

Crashed

Convenience function for creating Crashed states.

Returns:

Name Type Description
State State

a Crashed state
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/schemas/states.py 
322
323
324
325
326
327
328
def Crashed(cls: Type[State] = State, **kwargs) -> State:
    """Convenience function for creating `Crashed` states.

    Returns:
        State: a Crashed state
    """
    return cls(type=StateType.CRASHED, **kwargs)

Failed

Convenience function for creating Failed states.

Returns:

Name Type Description
State State

a Failed state
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/schemas/states.py 
313
314
315
316
317
318
319
def Failed(cls: Type[State] = State, **kwargs) -> State:
    """Convenience function for creating `Failed` states.

    Returns:
        State: a Failed state
    """
    return cls(type=StateType.FAILED, **kwargs)

Late

Convenience function for creating Late states.

Returns:

Name Type Description
State State

a Late state
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/schemas/states.py 
416
417
418
419
420
421
422
423
424
def Late(
    scheduled_time: datetime.datetime = None, cls: Type[State] = State, **kwargs
) -> State:
    """Convenience function for creating `Late` states.

    Returns:
        State: a Late state
    """
    return Scheduled(cls=cls, scheduled_time=scheduled_time, name="Late", **kwargs)

Paused

Convenience function for creating Paused states.

Returns:

Name Type Description
State State

a Paused state
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/schemas/states.py 
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
def Paused(
    cls: Type[State] = State,
    timeout_seconds: int = None,
    pause_expiration_time: datetime.datetime = None,
    reschedule: bool = False,
    pause_key: str = None,
    **kwargs,
) -> State:
    """Convenience function for creating `Paused` states.

    Returns:
        State: a Paused state
    """
    state_details = StateDetails.parse_obj(kwargs.pop("state_details", {}))

    if state_details.pause_timeout:
        raise ValueError("An extra pause timeout was provided in state_details")

    if pause_expiration_time is not None and timeout_seconds is not None:
        raise ValueError(
            "Cannot supply both a pause_expiration_time and timeout_seconds"
        )

    if pause_expiration_time is None and timeout_seconds is None:
        pass
    else:
        state_details.pause_timeout = pause_expiration_time or (
            pendulum.now("UTC") + pendulum.Duration(seconds=timeout_seconds)
        )

    state_details.pause_reschedule = reschedule
    state_details.pause_key = pause_key

    return cls(type=StateType.PAUSED, state_details=state_details, **kwargs)

Pending

Convenience function for creating Pending states.

Returns:

Name Type Description
State State

a Pending state
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/schemas/states.py 
349
350
351
352
353
354
355
def Pending(cls: Type[State] = State, **kwargs) -> State:
    """Convenience function for creating `Pending` states.

    Returns:
        State: a Pending state
    """
    return cls(type=StateType.PENDING, **kwargs)

Retrying

Convenience function for creating Retrying states.

Returns:

Name Type Description
State State

a Retrying state
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/schemas/states.py 
407
408
409
410
411
412
413
def Retrying(cls: Type[State] = State, **kwargs) -> State:
    """Convenience function for creating `Retrying` states.

    Returns:
        State: a Retrying state
    """
    return cls(type=StateType.RUNNING, name="Retrying", **kwargs)

Running

Convenience function for creating Running states.

Returns:

Name Type Description
State State

a Running state
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/schemas/states.py 
304
305
306
307
308
309
310
def Running(cls: Type[State] = State, **kwargs) -> State:
    """Convenience function for creating `Running` states.

    Returns:
        State: a Running state
    """
    return cls(type=StateType.RUNNING, **kwargs)

Scheduled

Convenience function for creating Scheduled states.

Returns:

Name Type Description
State State

a Scheduled state
Source code in /home/runner/work/docs/docs/prefect_source/src/prefect/server/schemas/states.py 
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
def Scheduled(
    scheduled_time: datetime.datetime = None, cls: Type[State] = State, **kwargs
) -> State:
    """Convenience function for creating `Scheduled` states.

    Returns:
        State: a Scheduled state
    """
    # NOTE: `scheduled_time` must come first for backwards compatibility

    state_details = StateDetails.parse_obj(kwargs.pop("state_details", {}))
    if scheduled_time is None:
        scheduled_time = pendulum.now("UTC")
    elif state_details.scheduled_time:
        raise ValueError("An extra scheduled_time was provided in state_details")
    state_details.scheduled_time = scheduled_time

    return cls(type=StateType.SCHEDULED, state_details=state_details, **kwargs)