Prefect Docs

# Prefect Tasks

Tasks for interacting with the Prefect API

# StartFlowRun

class

prefect.tasks.prefect.flow_run.StartFlowRun

(flow_name=None, project_name=None, parameters=None, run_config=None, wait=False, new_flow_context=None, run_name=None, scheduled_start_time=None, poll_interval=datetime.timedelta(seconds=10), create_link_artifact=True, **kwargs)[source]

Task used to kick off a flow run using Prefect Core's server or Prefect Cloud. If multiple versions of the flow are found, this task will kick off the most recent unarchived version.

Args:

  • flow_name (str, optional): the name of the flow to schedule; this value may also be provided at run time
  • project_name (str, optional): the name of the project in which the flow is located; this value may also be provided at runtime.
  • parameters (dict, optional): the parameters to pass to the flow run being scheduled; this value may also be provided at run time
  • run_config (RunConfig, optional): a run-config to use for this flow run, overriding any existing flow settings.
  • wait (bool, optional): whether to wait the triggered flow run's state; if True, this task will wait until the flow run is complete, and then reflect the corresponding state as the state of this task. Defaults to False.
  • new_flow_context (dict, optional): the optional run context for the new flow run
  • run_name (str, optional): name to be set for the flow run
  • scheduled_start_time (datetime, optional): the time to schedule the execution for; if not provided, defaults to now
  • poll_interval (timedelta): the time to wait between each check if the flow is finished. Has to be >= 3 seconds. Used only if wait=True. Defaults to 10 seconds.
  • create_link_artifact (bool, optional): whether to create a link artifact to the child flow run page. Defaults to True.
  • **kwargs (dict, optional): additional keyword arguments to pass to the Task constructor

methods:                                                                                                                                                       

prefect.tasks.prefect.flow_run.StartFlowRun.run

(flow_name=None, project_name=None, parameters=None, run_config=None, new_flow_context=None, run_name=None, idempotency_key=None, scheduled_start_time=None)[source]

Run method for the task; responsible for scheduling the specified flow run.

Args:

  • flow_name (str, optional): the name of the flow to schedule; if not provided, this method will use the flow name provided at initialization
  • project_name (str, optional): the project in which the flow is located; if not provided, this method will use the project provided at initialization.
  • parameters (dict, optional): the parameters to pass to the flow run being scheduled; if not provided, this method will use the parameters provided at initialization
  • run_config (RunConfig, optional): a run-config to use for this flow run, overriding any existing flow settings.
  • new_flow_context (dict, optional): the optional run context for the new flow run
  • run_name (str, optional): name to be set for the flow run
  • idempotency_key (str, optional): a unique idempotency key for scheduling the flow run. Duplicate flow runs with the same idempotency key will only create a single flow run. This is useful for ensuring that only one run is created if this task is retried. If not provided, defaults to the active task_run_id.
  • scheduled_start_time (datetime, optional): the time to schedule the execution for; if not provided, defaults to now
Returns:
  • str: the ID of the newly-scheduled flow run
Raises:
  • ValueError: if flow was not provided, cannot be found, or if a project name was not provided while using Cloud as a backend
Example: 
    from prefect.tasks.prefect.flow_run import StartFlowRun

    kickoff_task = StartFlowRun(project_name="Hello, World!", flow_name="My Cloud Flow")


# RenameFlowRun

class

prefect.tasks.prefect.flow_run_rename.RenameFlowRun

(flow_run_id=None, flow_run_name=None, **kwargs)[source]

Task used to rename a running flow.

Args:

  • flow_run_id (str, optional): The ID of the flow run to rename.
  • flow_run_name (str, optional): The new flow run name.
  • **kwargs (dict, optional): additional keyword arguments to pass to the Task constructor

methods:                                                                                                                                                       

prefect.tasks.prefect.flow_run_rename.RenameFlowRun.run

(flow_run_id, flow_run_name)[source]

Args:

  • flow_run_id (str, optional): The ID of the flow run to rename. If None, the flow_run_id from prefect.context will be used as default value
  • flow_run_name (str, optional): The new flow run name
Returns:
  • bool: Boolean representing whether the flow run was renamed successfully or not.
Raises:
  • ValueError: If flow_run_id is not provided and flow_run_id does not exist in prefect.context
  • ValueError: If flow_run_name is not provided
Example: 
    from prefect.tasks.prefect.flow_rename import FlowRenameTask

    rename_flow = FlowRenameTask(flow_name="A new flow run name")


# CancelFlowRun

class

prefect.tasks.prefect.flow_run_cancel.CancelFlowRun

(flow_run_id=None, **kwargs)[source]

Task to cancel a flow run. If flow_run_id is not provided, flow_run_id from prefect.context will be used by default

Args:

  • flow_run_id (str, optional): The ID of the flow run to cancel
  • **kwargs (dict, optional): additional keyword arguments to pass to the Task constructor

methods:                                                                                                                                                       

prefect.tasks.prefect.flow_run_cancel.CancelFlowRun.run

(flow_run_id=None)[source]

Args:

  • flow_run_id (str, optional): The ID of the flow run to cancel
Returns:
  • bool: Whether the flow run was canceled successfully or not


# create_flow_run

prefect.tasks.prefect.flow_run.create_flow_run

(flow_id=None, flow_name=None, project_name="", parameters=None, context=None, labels=None, run_name=None, run_config=None, scheduled_start_time=None, idempotency_key=None)[source]

Task to create a flow run in the Prefect backend.

The flow to run must be registered and an agent must be available to deploy the flow run.

Args:

  • flow_id: The flow or flow group uuid to lookup the flow to run
  • flow_name: The flow name to lookup the flow to run
  • project_name: The project name to lookup the flow to run. For use with flow_name if you have flows with the same name in multiple projects
  • parameters: An optional dictionary of parameters to pass to the flow run
  • context: An optional dictionary of context variables to pass to the flow run
  • labels: An optional iterable of labels to set on the flow run; if not provided, the default set of labels for the flow will be used
  • run_name: An optional name for the flow run; if not provided, the name will be generated as "{current_run_name}-{flow_name}"
  • run_config: An optional run config to use for the flow run; will override any existing run config settings
  • scheduled_start_time: An optional time in the future to schedule flow run execution for. If not provided, the flow run will be scheduled to start now
  • idempotency_key: a unique idempotency key for scheduling the flow run. Duplicate flow runs with the same idempotency key will only create a single flow run. This is useful for ensuring that only one run is created if this task is retried. If not provided, defaults to the active task run id and its map index.
Returns: str: The UUID of the created flow run

methods:                                                                                                                                                       

prefect.tasks.prefect.flow_run.create_flow_run

(flow_id=None, flow_name=None, project_name="", parameters=None, context=None, labels=None, run_name=None, run_config=None, scheduled_start_time=None, idempotency_key=None)[source]

Task to create a flow run in the Prefect backend.

The flow to run must be registered and an agent must be available to deploy the flow run.

Args:

  • flow_id: The flow or flow group uuid to lookup the flow to run
  • flow_name: The flow name to lookup the flow to run
  • project_name: The project name to lookup the flow to run. For use with flow_name if you have flows with the same name in multiple projects
  • parameters: An optional dictionary of parameters to pass to the flow run
  • context: An optional dictionary of context variables to pass to the flow run
  • labels: An optional iterable of labels to set on the flow run; if not provided, the default set of labels for the flow will be used
  • run_name: An optional name for the flow run; if not provided, the name will be generated as "{current_run_name}-{flow_name}"
  • run_config: An optional run config to use for the flow run; will override any existing run config settings
  • scheduled_start_time: An optional time in the future to schedule flow run execution for. If not provided, the flow run will be scheduled to start now
  • idempotency_key: a unique idempotency key for scheduling the flow run. Duplicate flow runs with the same idempotency key will only create a single flow run. This is useful for ensuring that only one run is created if this task is retried. If not provided, defaults to the active task run id and its map index.
Returns: str: The UUID of the created flow run


# get_task_run_result

prefect.tasks.prefect.flow_run.get_task_run_result

(flow_run_id, task_slug, map_index=-1, poll_time=5)[source]

Task to get the result of a task from a flow run.

Will wait for the flow run to finish entirely or dynamic task run results will not be properly populated.

Results are loaded from the Result location of the task which may not be accessible from where this task is executed. You will need to ensure results can be accessed.

Args:

  • flow_run_id: The flow run the task run belongs to
  • task_slug: The 'slug' of the task run you want to get the result of
  • map_index: If the task is mapped, the index you would like to access. By default, if given a mapped task, all of the child results will be loaded.
  • poll_time: The amount of time to wait while polling to check if the sub-flow has finished
Returns: Any: The return value of the task

methods:                                                                                                                                                       

prefect.tasks.prefect.flow_run.get_task_run_result

(flow_run_id, task_slug, map_index=-1, poll_time=5)[source]

Task to get the result of a task from a flow run.

Will wait for the flow run to finish entirely or dynamic task run results will not be properly populated.

Results are loaded from the Result location of the task which may not be accessible from where this task is executed. You will need to ensure results can be accessed.

Args:

  • flow_run_id: The flow run the task run belongs to
  • task_slug: The 'slug' of the task run you want to get the result of
  • map_index: If the task is mapped, the index you would like to access. By default, if given a mapped task, all of the child results will be loaded.
  • poll_time: The amount of time to wait while polling to check if the sub-flow has finished
Returns: Any: The return value of the task


# wait_for_flow_run

prefect.tasks.prefect.flow_run.wait_for_flow_run

(flow_run_id, stream_states=True, stream_logs=False, raise_final_state=False, max_duration=datetime.timedelta(seconds=43200))[source]

Task to wait for a flow run to finish executing, streaming state and log information

Args:

  • flow_run_id: The flow run id to wait for
  • stream_states: Stream information about the flow run state changes
  • stream_logs: Stream flow run logs; if stream_state is False this will be ignored
  • raise_final_state: If set, the state of this task will be set to the final state of the child flow run on completion.
  • max_duration: Duration to wait for flow run to complete. Defaults to 12 hours.
Returns: FlowRunView: A view of the flow run after completion

methods:                                                                                                                                                       

prefect.tasks.prefect.flow_run.wait_for_flow_run

(flow_run_id, stream_states=True, stream_logs=False, raise_final_state=False, max_duration=datetime.timedelta(seconds=43200))[source]

Task to wait for a flow run to finish executing, streaming state and log information

Args:

  • flow_run_id: The flow run id to wait for
  • stream_states: Stream information about the flow run state changes
  • stream_logs: Stream flow run logs; if stream_state is False this will be ignored
  • raise_final_state: If set, the state of this task will be set to the final state of the child flow run on completion.
  • max_duration: Duration to wait for flow run to complete. Defaults to 12 hours.
Returns: FlowRunView: A view of the flow run after completion


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

← prometheus Tasks →