Prefect Docs

# State

State is the main currency in the Prefect platform. It is used to represent the current status of a flow or task.

This module contains all Prefect state classes, all ultimately inheriting from the base State class as follows:

diagram of state inheritances

Every run is initialized with the Pending state, meaning that it is waiting for execution. During execution a run will enter a Running state. Finally, runs become Finished.

# State

class

prefect.engine.state.State

(message=None, result=None, context=None, cached_inputs=None)[source]

Base state class implementing the basic helper methods for checking state.

Note: Each state-checking method (e.g., is_failed()) will also return True for all subclasses of the parent state. So, for example:

my_state = TriggerFailed()
my_state.is_failed() # returns True

another_state = Retrying()
another_state.is_pending() # returns True

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.

methods:                                                                                                                                                       

prefect.engine.state.State.children

(include_self=False, names_only=False)[source]

Helper method for retrieving all possible child states of this state.

Args:

  • include_self (bool, optional): whether to include the calling state in the return values; defaults to False
  • names_only (bool, optional): whether to only return the string names of the states; defaults to False, in which case the actual classes are returned
Returns:
  • list: a (possibly empty) list of states or state names

prefect.engine.state.State.deserialize

(json_blob)[source]

Deserializes the state from a dict.

Args:

  • json_blob (dict): the JSON representing the serialized state

prefect.engine.state.State.is_cached

()[source]

Checks if the state is currently in a Cached state

Returns:

  • bool: True if the state is Cached, False otherwise

prefect.engine.state.State.is_failed

()[source]

Checks if the state is currently in a failed state

Returns:

  • bool: True if the state is failed, False otherwise

prefect.engine.state.State.is_finished

()[source]

Checks if the state is currently in a finished state

Returns:

  • bool: True if the state is finished, False otherwise

prefect.engine.state.State.is_looped

()[source]

Checks if the state is currently in a looped state

Returns:

  • bool: True if the state is looped, False otherwise

prefect.engine.state.State.is_mapped

()[source]

Checks if the state is currently in a mapped state

Returns:

  • bool: True if the state is mapped, False otherwise

prefect.engine.state.State.is_meta_state

()[source]

Checks if the state is a meta state that wraps another state

Returns:

  • bool: True if the state is a meta state, False otherwise

prefect.engine.state.State.is_pending

()[source]

Checks if the state is currently in a pending state

Returns:

  • bool: True if the state is pending, False otherwise

prefect.engine.state.State.is_queued

()[source]

Checks if the state is currently in a queued state

Returns:

  • bool: True if the state is queued, False otherwise

prefect.engine.state.State.is_retrying

()[source]

Checks if the state is currently in a retrying state

Returns:

  • bool: True if the state is retrying, False otherwise

prefect.engine.state.State.is_running

()[source]

Checks if the state is currently in a running state

Returns:

  • bool: True if the state is running, False otherwise

prefect.engine.state.State.is_scheduled

()[source]

Checks if the state is currently in a scheduled state, which includes retrying.

Returns:

  • bool: True if the state is skipped, False otherwise

prefect.engine.state.State.is_skipped

()[source]

Checks if the state is currently in a skipped state

Returns:

  • bool: True if the state is skipped, False otherwise

prefect.engine.state.State.is_submitted

()[source]

Checks if the state is currently in a submitted state.

Returns:

  • bool: True if the state is submitted, False otherwise

prefect.engine.state.State.is_successful

()[source]

Checks if the state is currently in a successful state

Returns:

  • bool: True if the state is successful, False otherwise

prefect.engine.state.State.load_cached_results

(results=None)[source]

Given another Result instance, uses the current Result's location to create a fully hydrated Result using the logic of the provided result. This method is mainly intended to be used by TaskRunner methods to hydrate deserialized Cloud results into fully functional Result instances.

Args:

  • results (Dict[str, Result]): a dictionary of result instances to hydrate self.cached_inputs with
Returns:
  • State: the current state with a fully hydrated Result attached

prefect.engine.state.State.load_result

(result=None)[source]

Given another Result instance, uses the current Result's location to create a fully hydrated Result using the logic of the provided result. This method is mainly intended to be used by TaskRunner methods to hydrate deserialized Cloud results into fully functional Result instances.

Args:

  • result (Result): the result instance to hydrate with self.location
Returns:
  • State: the current state with a fully hydrated Result attached

prefect.engine.state.State.parents

(include_self=False, names_only=False)[source]

Helper method for retrieving all possible parent states of this state.

Args:

  • include_self (bool, optional): whether to include the calling state in the return values; defaults to False
  • names_only (bool, optional): whether to only return the string names of the states; defaults to False, in which case the actual classes are returned
Returns:
  • list: a (possibly empty) list of states or state names

prefect.engine.state.State.serialize

()[source]

Serializes the state to a dict.

Returns:

  • dict: a JSON representation of the state


# Pending

class

prefect.engine.state.Pending

(message=None, result=None, cached_inputs=None, context=None)[source]

Base Pending state; default state for new tasks.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# Paused

class

prefect.engine.state.Paused

(message=None, result=None, start_time=None, cached_inputs=None, context=None)[source]

Paused state for tasks. This allows manual intervention or pausing for a set amount of time.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • start_time (datetime): time at which the task is scheduled to resume; defaults to 10 years from now if not provided.
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# Scheduled

class

prefect.engine.state.Scheduled

(message=None, result=None, start_time=None, cached_inputs=None, context=None)[source]

Pending state indicating the object has been scheduled to run.

Scheduled states have a start_time that indicates when they are scheduled to run. Only scheduled states have this property; this is important because non-Python systems identify scheduled states by the presence of this property.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • start_time (datetime): time at which the task is scheduled to run
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# Resume

class

prefect.engine.state.Resume

(message=None, result=None, start_time=None, cached_inputs=None, context=None)[source]

Resume state indicating the object can resume execution (presumably from a Paused state).

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • start_time (datetime): time at which the task is scheduled to run
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# Retrying

class

prefect.engine.state.Retrying

(message=None, result=None, start_time=None, cached_inputs=None, context=None, run_count=None)[source]

Pending state indicating the object has been scheduled to be retried.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • start_time (datetime): time at which the task is scheduled to be retried
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible
  • run_count (int): The number of runs that had been attempted at the time of this Retry. Defaults to the value stored in context under "task_run_count" or 1, if that value isn't found.


# Submitted

class

prefect.engine.state.Submitted

(message=None, result=None, state=None, context=None, cached_inputs=None)[source]

The Submitted state is used to indicate that another state, usually a Scheduled state, has been handled. For example, if a task is in a Retrying state, then at the appropriate time it may be put into a Submitted state referencing the Retrying state. This communicates to the system that the retry has been handled, without losing the information contained in the Retry state.

The Submitted state should be initialized with another state, which it wraps. The wrapped state is extracted at the beginning of a task run.

Args:

  • message (string): a message for the state.
  • result (Any, optional): Defaults to None.
  • state (State): the State state that has been marked as "submitted".
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# Queued

class

prefect.engine.state.Queued

(message=None, result=None, state=None, start_time=None, context=None, cached_inputs=None)[source]

The Queued state is used to indicate that another state could not transition to a Running state for some reason, often a lack of available resources.

The Queued state should be initialized with another state, which it wraps. The wrapped state is extracted at the beginning of a task run.

Args:

  • message (string): a message for the state.
  • result (Any, optional): Defaults to None.
  • state (State): the State state that has been marked as "queued".
  • start_time (datetime): a time the state is queued until. Defaults to now.
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# ClientFailed

class

prefect.engine.state.ClientFailed

(message=None, result=None, state=None, context=None, cached_inputs=None)[source]

The ClientFailed state is used to indicate that the Prefect Client failed to set a task run state, and thus this task run should exit, without triggering any downstream task runs.

The ClientFailed state should be initialized with another state, which it wraps. The wrapped state is the state which the client attempted to set in the database, but failed to for some reason.

Args:

  • message (string): a message for the state.
  • result (Any, optional): Defaults to None.
  • state (State): the State state that the task run ended in
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# Running

class

prefect.engine.state.Running

(message=None, result=None, context=None, cached_inputs=None)[source]

Base running state. Indicates that a task is currently running.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# Cancelling

class

prefect.engine.state.Cancelling

(message=None, result=None, context=None, cached_inputs=None)[source]

State indicating that a previously running flow run is in the process of cancelling, but still may have tasks running.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# Finished

class

prefect.engine.state.Finished

(message=None, result=None, context=None, cached_inputs=None)[source]

Base finished state. Indicates when a class has reached some form of completion.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# Success

class

prefect.engine.state.Success

(message=None, result=None, context=None, cached_inputs=None)[source]

Finished state indicating success.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# Cached

class

prefect.engine.state.Cached

(message=None, result=None, cached_inputs=None, cached_parameters=None, cached_result_expiration=None, context=None, hashed_inputs=None)[source]

Cached, which represents a Task whose outputs have been cached.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state, which will be cached.
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • cached_parameters (dict): Defaults to None
  • cached_result_expiration (datetime): The time at which this cache expires and can no longer be used. Defaults to None
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible
  • hashed_inputs (Dict[str, str], optional): a string hash of a dictionary of inputs


# Looped

class

prefect.engine.state.Looped

(message=None, result=None, loop_count=None, context=None, cached_inputs=None)[source]

Finished state indicating one successful run of a looped task - if a Task is in this state, it will run the next iteration of the loop immediately after.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • loop_count (int): The iteration number of the looping task. Defaults to the value stored in context under "task_loop_count" or 1, if that value isn't found.
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# Mapped

class

prefect.engine.state.Mapped

(message=None, result=None, map_states=None, context=None, cached_inputs=None, n_map_states=None)[source]

State indicated this task was mapped over, and all mapped tasks were submitted successfully. Note that this does not imply the individual mapped tasks were successful, just that they have been submitted.

You can not set the result of a Mapped state; it is determined by the results of its children states.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to []. A data payload for the state.
  • map_states (List): A list containing the states of any "children" of this task. When a task enters a Mapped state, it indicates that it has dynamically created copies of itself to map its operation over its inputs. Those copies are the children.
  • n_map_states (int, optional): the number of tasks that were mapped; if not provided, the value of len(map_states) is used
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# Skipped

class

prefect.engine.state.Skipped

(message=None, result=None, context=None, cached_inputs=None)[source]

Finished state indicating success on account of being skipped.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# Failed

class

prefect.engine.state.Failed

(message=None, result=None, cached_inputs=None, context=None)[source]

Finished state indicating failure.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# Cancelled

class

prefect.engine.state.Cancelled

(message=None, result=None, context=None, cached_inputs=None)[source]

Finished state indicating that a user cancelled the flow run manually, mid-run.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# TriggerFailed

class

prefect.engine.state.TriggerFailed

(message=None, result=None, cached_inputs=None, context=None)[source]

Finished state indicating failure due to trigger.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# ValidationFailed

class

prefect.engine.state.ValidationFailed

(message=None, result=None, cached_inputs=None, context=None)[source]

Finished stated indicating failure due to failed result validation.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


# TimedOut

class

prefect.engine.state.TimedOut

(message=None, result=None, cached_inputs=None, context=None)[source]

Finished state indicating failure due to execution timeout.

Args:

  • message (str or Exception, optional): Defaults to None. A message about the state, which could be an Exception (or Signal) that caused it.
  • result (Any, optional): Defaults to None. A data payload for the state.
  • cached_inputs (dict, optional, DEPRECATED): A dictionary of input keys to fully hydrated Results. Used / set if the Task requires retries.
  • context (dict, optional): A dictionary of execution context information; values should be JSON compatible


This documentation was auto-generated from commit bd9182e
on July 31, 2024 at 18:02 UTC

← TaskRunner →