# Runnables `Runnables` in the Hatchet SDK are things that can be run, namely tasks and workflows. The two main types of runnables you'll encounter are: - `Workflow`, which lets you define tasks and call all of the run, schedule, etc. methods - `Standalone`, which is a single task that's returned by `hatchet.task` and can be run, scheduled, etc. ## Workflow Bases: `BaseWorkflow[TWorkflowInput]` A Hatchet workflow, which allows you to define tasks to be run and perform actions on the workflow. Workflows in Hatchet represent coordinated units of work that can be triggered, scheduled, or run on a cron schedule. Each workflow can contain multiple tasks that can be arranged in dependencies (DAGs), have customized retry behavior, timeouts, concurrency controls, and more. Example: ```python from pydantic import BaseModel from hatchet_sdk import Hatchet class MyInput(BaseModel): name: str hatchet = Hatchet() workflow = hatchet.workflow("my-workflow", input_type=MyInput) @workflow.task() def greet(input, ctx): return f"Hello, {input.name}!" # Run the workflow result = workflow.run(MyInput(name="World")) ``` Workflows support various execution patterns including: - One-time execution with `run()` or `aio_run()` - Scheduled execution with `schedule()` - Cron-based recurring execution with `create_cron()` - Bulk operations with `run_many()` Tasks within workflows can be defined with `@workflow.task()` or `@workflow.durable_task()` decorators and can be arranged into complex dependency patterns. Methods: Name, Description `task`, A decorator to transform a function into a Hatchet task that runs as part of a workflow. `durable_task`, A decorator to transform a function into a durable Hatchet task that runs as part of a workflow. `on_failure_task`, A decorator to transform a function into a Hatchet on-failure task that runs as the last step in a workflow that had at least one task fail. `on_success_task`, A decorator to transform a function into a Hatchet on-success task that runs as the last step in a workflow that had all upstream tasks succeed. `run`, Run the workflow synchronously and wait for it to complete. `aio_run`, Run the workflow asynchronously and wait for it to complete. `run_no_wait`, Synchronously trigger a workflow run without waiting for it to complete. `aio_run_no_wait`, Asynchronously trigger a workflow run without waiting for it to complete. `run_many`, Run a workflow in bulk and wait for all runs to complete. `aio_run_many`, Run a workflow in bulk and wait for all runs to complete. `run_many_no_wait`, Run a workflow in bulk without waiting for all runs to complete. `aio_run_many_no_wait`, Run a workflow in bulk without waiting for all runs to complete. `schedule`, Schedule a workflow to run at a specific time. `aio_schedule`, Schedule a workflow to run at a specific time. `create_cron`, Create a cron job for the workflow. `aio_create_cron`, Create a cron job for the workflow. `create_bulk_run_item`, Create a bulk run item for the workflow. This is intended to be used in conjunction with the various `run_many` methods. `list_runs`, List runs of the workflow. `aio_list_runs`, List runs of the workflow. `create_filter`, Create a new filter. `aio_create_filter`, Create a new filter. ### Attributes #### `name` The (namespaced) name of the workflow. #### `tasks` #### `id` `cached` Get the ID of the workflow. Returns: Type, Description `str`, The ID of the workflow. Raises: Type, Description `ValueError`, If no workflow ID is found for the workflow name. ### Functions #### `task` A decorator to transform a function into a Hatchet task that runs as part of a workflow. Parameters: Name, Type, Description, Default `name`, `str \, None`, The name of the task. If not specified, defaults to the name of the function being wrapped by the `task` decorator., `None` `schedule_timeout`, `Duration`, The maximum time to wait for the task to be scheduled. The run will be canceled if the task does not begin within this time., `timedelta(minutes=5)` `execution_timeout`, `Duration`, The maximum time to wait for the task to complete. The run will be canceled if the task does not complete within this time., `timedelta(seconds=60)` `parents`, `list[Task[TWorkflowInput, Any]] \, None`, A list of tasks that are parents of the task. Note: Parents must be defined before their children., `None` `retries`, `int`, The number of times to retry the task before failing., `0` `rate_limits`, `list[RateLimit] \, None`, A list of rate limit configurations for the task., `None` `desired_worker_labels`, `dict[str, DesiredWorkerLabel] \, None`, A dictionary of desired worker labels that determine to which worker the task should be assigned. See documentation and examples on affinity and worker labels for more details., `None` `backoff_factor`, `float \, None`, The backoff factor for controlling exponential backoff in retries., `None` `backoff_max_seconds`, `int \, None`, The maximum number of seconds to allow retries with exponential backoff to continue., `None` `concurrency`, `int \, list[ConcurrencyExpression] \, None`, A list of concurrency expressions for the task. If an integer is provided, it is treated as a constant concurrency limit with a `GROUP_ROUND_ROBIN` strategy, which means that only `N` runs of the task may execute at any given time., `None` `wait_for`, `list[Condition \, OrGroup] \, None`, A list of conditions that must be met before the task can run., `None` `skip_if`, `list[Condition \, OrGroup] \, None`, A list of conditions that, if met, will cause the task to be skipped., `None` `cancel_if`, `list[Condition \, OrGroup] \, None`, A list of conditions that, if met, will cause the task to be canceled., `None` Returns: Type, Description `Callable[[Callable[Concatenate[TWorkflowInput, Context, P], R \, CoroutineLike[R]]], Task[TWorkflowInput, R]]`, A decorator which creates a `Task` object. #### `durable_task` A decorator to transform a function into a durable Hatchet task that runs as part of a workflow. **IMPORTANT:** This decorator creates a _durable_ task, which works using Hatchet's durable execution capabilities. This is an advanced feature of Hatchet. See the Hatchet docs for more information on durable execution to decide if this is right for you. Parameters: Name, Type, Description, Default `name`, `str \, None`, The name of the task. If not specified, defaults to the name of the function being wrapped by the `task` decorator., `None` `schedule_timeout`, `Duration`, The maximum time to wait for the task to be scheduled. The run will be canceled if the task does not begin within this time., `timedelta(minutes=5)` `execution_timeout`, `Duration`, The maximum time to wait for the task to complete. The run will be canceled if the task does not complete within this time., `timedelta(seconds=60)` `parents`, `list[Task[TWorkflowInput, Any]] \, None`, A list of tasks that are parents of the task. Note: Parents must be defined before their children., `None` `retries`, `int`, The number of times to retry the task before failing., `0` `rate_limits`, `list[RateLimit] \, None`, A list of rate limit configurations for the task., `None` `desired_worker_labels`, `dict[str, DesiredWorkerLabel] \, None`, A dictionary of desired worker labels that determine to which worker the task should be assigned. See documentation and examples on affinity and worker labels for more details., `None` `backoff_factor`, `float \, None`, The backoff factor for controlling exponential backoff in retries., `None` `backoff_max_seconds`, `int \, None`, The maximum number of seconds to allow retries with exponential backoff to continue., `None` `concurrency`, `int \, list[ConcurrencyExpression] \, None`, A list of concurrency expressions for the task. If an integer is provided, it is treated as a constant concurrency limit with a `GROUP_ROUND_ROBIN` strategy, which means that only `N` runs of the task may execute at any given time., `None` `wait_for`, `list[Condition \, OrGroup] \, None`, A list of conditions that must be met before the task can run., `None` `skip_if`, `list[Condition \, OrGroup] \, None`, A list of conditions that, if met, will cause the task to be skipped., `None` `cancel_if`, `list[Condition \, OrGroup] \, None`, A list of conditions that, if met, will cause the task to be canceled., `None` Returns: Type, Description `Callable[[Callable[Concatenate[TWorkflowInput, DurableContext, P], R \, CoroutineLike[R]]], Task[TWorkflowInput, R]]`, A decorator which creates a `Task` object. #### `on_failure_task` A decorator to transform a function into a Hatchet on-failure task that runs as the last step in a workflow that had at least one task fail. Parameters: Name, Type, Description, Default `name`, `str \, None`, The name of the on-failure task. If not specified, defaults to the name of the function being wrapped by the `on_failure_task` decorator., `None` `schedule_timeout`, `Duration`, The maximum time to wait for the task to be scheduled. The run will be canceled if the task does not begin within this time., `timedelta(minutes=5)` `execution_timeout`, `Duration`, The maximum time to wait for the task to complete. The run will be canceled if the task does not complete within this time., `timedelta(seconds=60)` `retries`, `int`, The number of times to retry the on-failure task before failing., `0` `rate_limits`, `list[RateLimit] \, None`, A list of rate limit configurations for the on-failure task., `None` `backoff_factor`, `float \, None`, The backoff factor for controlling exponential backoff in retries., `None` `backoff_max_seconds`, `int \, None`, The maximum number of seconds to allow retries with exponential backoff to continue., `None` `concurrency`, `int \, list[ConcurrencyExpression] \, None`, A list of concurrency expressions for the on-failure task. If an integer is provided, it is treated as a constant concurrency limit with a `GROUP_ROUND_ROBIN` strategy, which means that only `N` runs of the task may execute at any given time., `None` Returns: Type, Description `Callable[[Callable[Concatenate[TWorkflowInput, Context, P], R \, CoroutineLike[R]]], Task[TWorkflowInput, R]]`, A decorator which creates a `Task` object. #### `on_success_task` A decorator to transform a function into a Hatchet on-success task that runs as the last step in a workflow that had all upstream tasks succeed. Parameters: Name, Type, Description, Default `name`, `str \, None`, The name of the on-success task. If not specified, defaults to the name of the function being wrapped by the `on_success_task` decorator., `None` `schedule_timeout`, `Duration`, The maximum time to wait for the task to be scheduled. The run will be canceled if the task does not begin within this time., `timedelta(minutes=5)` `execution_timeout`, `Duration`, The maximum time to wait for the task to complete. The run will be canceled if the task does not complete within this time., `timedelta(seconds=60)` `retries`, `int`, The number of times to retry the on-success task before failing, `0` `rate_limits`, `list[RateLimit] \, None`, A list of rate limit configurations for the on-success task., `None` `backoff_factor`, `float \, None`, The backoff factor for controlling exponential backoff in retries., `None` `backoff_max_seconds`, `int \, None`, The maximum number of seconds to allow retries with exponential backoff to continue., `None` `concurrency`, `int \, list[ConcurrencyExpression] \, None`, A list of concurrency expressions for the on-success task. If an integer is provided, it is treated as a constant concurrency limit with a `GROUP_ROUND_ROBIN` strategy, which means that only `N` runs of the task may execute at any given time., `None` Returns: Type, Description `Callable[[Callable[Concatenate[TWorkflowInput, Context, P], R \, CoroutineLike[R]]], Task[TWorkflowInput, R]]`, A decorator which creates a Task object. #### `run` Run the workflow synchronously and wait for it to complete. This method triggers a workflow run, blocks until completion, and returns the final result. Parameters: Name, Type, Description, Default `input`, `TWorkflowInput`, The input data for the workflow, must match the workflow's input type., `cast(TWorkflowInput, EmptyModel())` `options`, `TriggerWorkflowOptions`, Additional options for workflow execution like metadata and parent workflow ID., `TriggerWorkflowOptions()` Returns: Type, Description `dict[str, Any]`, The result of the workflow execution as a dictionary. #### `aio_run` Run the workflow asynchronously and wait for it to complete. This method triggers a workflow run, awaits until completion, and returns the final result. Parameters: Name, Type, Description, Default `input`, `TWorkflowInput`, The input data for the workflow, must match the workflow's input type., `cast(TWorkflowInput, EmptyModel())` `options`, `TriggerWorkflowOptions`, Additional options for workflow execution like metadata and parent workflow ID., `TriggerWorkflowOptions()` Returns: Type, Description `dict[str, Any]`, The result of the workflow execution as a dictionary. #### `run_no_wait` Synchronously trigger a workflow run without waiting for it to complete. This method is useful for starting a workflow run and immediately returning a reference to the run without blocking while the workflow runs. Parameters: Name, Type, Description, Default `input`, `TWorkflowInput`, The input data for the workflow., `cast(TWorkflowInput, EmptyModel())` `options`, `TriggerWorkflowOptions`, Additional options for workflow execution., `TriggerWorkflowOptions()` Returns: Type, Description `WorkflowRunRef`, A `WorkflowRunRef` object representing the reference to the workflow run. #### `aio_run_no_wait` Asynchronously trigger a workflow run without waiting for it to complete. This method is useful for starting a workflow run and immediately returning a reference to the run without blocking while the workflow runs. Parameters: Name, Type, Description, Default `input`, `TWorkflowInput`, The input data for the workflow., `cast(TWorkflowInput, EmptyModel())` `options`, `TriggerWorkflowOptions`, Additional options for workflow execution., `TriggerWorkflowOptions()` Returns: Type, Description `WorkflowRunRef`, A `WorkflowRunRef` object representing the reference to the workflow run. #### `run_many` Run a workflow in bulk and wait for all runs to complete. This method triggers multiple workflow runs, blocks until all of them complete, and returns the final results. Parameters: Name, Type, Description, Default `workflows`, `list[WorkflowRunTriggerConfig]`, A list of `WorkflowRunTriggerConfig` objects, each representing a workflow run to be triggered., _required_ `return_exceptions`, `bool`, If `True`, exceptions will be returned as part of the results instead of raising them., `False` Returns: Type, Description `list[dict[str, Any]] \, list[dict[str, Any] \, BaseException]`, A list of results for each workflow run. #### `aio_run_many` Run a workflow in bulk and wait for all runs to complete. This method triggers multiple workflow runs, blocks until all of them complete, and returns the final results. Parameters: Name, Type, Description, Default `workflows`, `list[WorkflowRunTriggerConfig]`, A list of `WorkflowRunTriggerConfig` objects, each representing a workflow run to be triggered., _required_ `return_exceptions`, `bool`, If `True`, exceptions will be returned as part of the results instead of raising them., `False` Returns: Type, Description `list[dict[str, Any]] \, list[dict[str, Any] \, BaseException]`, A list of results for each workflow run. #### `run_many_no_wait` Run a workflow in bulk without waiting for all runs to complete. This method triggers multiple workflow runs and immediately returns a list of references to the runs without blocking while the workflows run. Parameters: Name, Type, Description, Default `workflows`, `list[WorkflowRunTriggerConfig]`, A list of `WorkflowRunTriggerConfig` objects, each representing a workflow run to be triggered., _required_ Returns: Type, Description `list[WorkflowRunRef]`, A list of `WorkflowRunRef` objects, each representing a reference to a workflow run. #### `aio_run_many_no_wait` Run a workflow in bulk without waiting for all runs to complete. This method triggers multiple workflow runs and immediately returns a list of references to the runs without blocking while the workflows run. Parameters: Name, Type, Description, Default `workflows`, `list[WorkflowRunTriggerConfig]`, A list of `WorkflowRunTriggerConfig` objects, each representing a workflow run to be triggered., _required_ Returns: Type, Description `list[WorkflowRunRef]`, A list of `WorkflowRunRef` objects, each representing a reference to a workflow run. #### `schedule` Schedule a workflow to run at a specific time. Parameters: Name, Type, Description, Default `run_at`, `datetime`, The time at which to schedule the workflow., _required_ `input`, `TWorkflowInput`, The input data for the workflow., `cast(TWorkflowInput, EmptyModel())` `options`, `ScheduleTriggerWorkflowOptions`, Additional options for workflow execution., `ScheduleTriggerWorkflowOptions()` Returns: Type, Description `WorkflowVersion`, A `WorkflowVersion` object representing the scheduled workflow. #### `aio_schedule` Schedule a workflow to run at a specific time. Parameters: Name, Type, Description, Default `run_at`, `datetime`, The time at which to schedule the workflow., _required_ `input`, `TWorkflowInput`, The input data for the workflow., `cast(TWorkflowInput, EmptyModel())` `options`, `ScheduleTriggerWorkflowOptions`, Additional options for workflow execution., `ScheduleTriggerWorkflowOptions()` Returns: Type, Description `WorkflowVersion`, A `WorkflowVersion` object representing the scheduled workflow. #### `create_cron` Create a cron job for the workflow. Parameters: Name, Type, Description, Default `cron_name`, `str`, The name of the cron job., _required_ `expression`, `str`, The cron expression that defines the schedule for the cron job., _required_ `input`, `TWorkflowInput`, The input data for the workflow., `cast(TWorkflowInput, EmptyModel())` `additional_metadata`, `JSONSerializableMapping \, None`, Additional metadata for the cron job., `None` `priority`, `int \, None`, The priority of the cron job. Must be between 1 and 3, inclusive., `None` Returns: Type, Description `CronWorkflows`, A `CronWorkflows` object representing the created cron job. #### `aio_create_cron` Create a cron job for the workflow. Parameters: Name, Type, Description, Default `cron_name`, `str`, The name of the cron job., _required_ `expression`, `str`, The cron expression that defines the schedule for the cron job., _required_ `input`, `TWorkflowInput`, The input data for the workflow., `cast(TWorkflowInput, EmptyModel())` `additional_metadata`, `JSONSerializableMapping \, None`, Additional metadata for the cron job., `None` `priority`, `int \, None`, The priority of the cron job. Must be between 1 and 3, inclusive., `None` Returns: Type, Description `CronWorkflows`, A `CronWorkflows` object representing the created cron job. #### `create_bulk_run_item` Create a bulk run item for the workflow. This is intended to be used in conjunction with the various `run_many` methods. Parameters: Name, Type, Description, Default `input`, `TWorkflowInput`, The input data for the workflow., `cast(TWorkflowInput, EmptyModel())` `key`, `str \, None`, The key for the workflow run. This is used to identify the run in the bulk operation and for deduplication., `None` `options`, `TriggerWorkflowOptions`, Additional options for the workflow run., `TriggerWorkflowOptions()` Returns: Type, Description `WorkflowRunTriggerConfig`, A `WorkflowRunTriggerConfig` object that can be used to trigger the workflow run, which you then pass into the `run_many` methods. #### `list_runs` List runs of the workflow. Parameters: Name, Type, Description, Default `since`, `datetime \, None`, The start time for the runs to be listed., `None` `until`, `datetime \, None`, The end time for the runs to be listed., `None` `limit`, `int`, The maximum number of runs to be listed., `100` `offset`, `int \, None`, The offset for pagination., `None` `statuses`, `list[V1TaskStatus] \, None`, The statuses of the runs to be listed., `None` `additional_metadata`, `dict[str, str] \, None`, Additional metadata for filtering the runs., `None` `worker_id`, `str \, None`, The ID of the worker that ran the tasks., `None` `parent_task_external_id`, `str \, None`, The external ID of the parent task., `None` `only_tasks`, `bool`, Whether to list only task runs., `False` `triggering_event_external_id`, `str \, None`, The event id that triggered the task run., `None` Returns: Type, Description `list[V1TaskSummary]`, A list of `V1TaskSummary` objects representing the runs of the workflow. #### `aio_list_runs` List runs of the workflow. Parameters: Name, Type, Description, Default `since`, `datetime \, None`, The start time for the runs to be listed., `None` `until`, `datetime \, None`, The end time for the runs to be listed., `None` `limit`, `int`, The maximum number of runs to be listed., `100` `offset`, `int \, None`, The offset for pagination., `None` `statuses`, `list[V1TaskStatus] \, None`, The statuses of the runs to be listed., `None` `additional_metadata`, `dict[str, str] \, None`, Additional metadata for filtering the runs., `None` `worker_id`, `str \, None`, The ID of the worker that ran the tasks., `None` `parent_task_external_id`, `str \, None`, The external ID of the parent task., `None` `only_tasks`, `bool`, Whether to list only task runs., `False` `triggering_event_external_id`, `str \, None`, The event id that triggered the task run., `None` Returns: Type, Description `list[V1TaskSummary]`, A list of `V1TaskSummary` objects representing the runs of the workflow. #### `create_filter` Create a new filter. Parameters: Name, Type, Description, Default `expression`, `str`, The expression to evaluate for the filter., _required_ `scope`, `str`, The scope for the filter., _required_ `payload`, `JSONSerializableMapping \, None`, The payload to send with the filter., `None` Returns: Type, Description `V1Filter`, The created filter. #### `aio_create_filter` Create a new filter. Parameters: Name, Type, Description, Default `expression`, `str`, The expression to evaluate for the filter., _required_ `scope`, `str`, The scope for the filter., _required_ `payload`, `JSONSerializableMapping \, None`, The payload to send with the filter., `None` Returns: Type, Description `V1Filter`, The created filter. ## Task Bases: `Generic[TWorkflowInput, R]` Methods: Name, Description `mock_run`, Mimic the execution of a task. This method is intended to be used to unit test `aio_mock_run`, Mimic the execution of a task. This method is intended to be used to unit test ### Functions #### `mock_run` Mimic the execution of a task. This method is intended to be used to unit test tasks without needing to interact with the Hatchet engine. Use `mock_run` for sync tasks and `aio_mock_run` for async tasks. Parameters: Name, Type, Description, Default `input`, `TWorkflowInput \, None`, The input to the task., `None` `additional_metadata`, `JSONSerializableMapping \, None`, Additional metadata to attach to the task., `None` `parent_outputs`, `dict[str, JSONSerializableMapping] \, None`, Outputs from parent tasks, if any. This is useful for mimicking DAG functionality. For instance, if you have a task `step_2` that has a `parent` which is `step_1`, you can pass `parent_outputs={"step_1": {"result": "Hello, world!"}}` to `step_2.mock_run()` to be able to access `ctx.task_output(step_1)` in `step_2`., `None` `retry_count`, `int`, The number of times the task has been retried., `0` `lifespan`, `Any`, The lifespan to be used in the task, which is useful if one was set on the worker. This will allow you to access `ctx.lifespan` inside of your task., `None` `dependencies`, `dict[str, Any] \, None`, Dependencies to be injected into the task. This is useful for tasks that have dependencies defined using `Depends`. **IMPORTANT**: You must pass the dependencies _directly_, **not** the `Depends` objects themselves. For example, if you have a task that has a dependency `config: Annotated[str, Depends(get_config)]`, you should pass `dependencies={"config": "config_value"}` to `aio_mock_run`., `None` Returns: Type, Description `R`, The output of the task. Raises: Type, Description `TypeError`, If the task is an async function and `mock_run` is called, or if the task is a sync function and `aio_mock_run` is called. #### `aio_mock_run` Mimic the execution of a task. This method is intended to be used to unit test tasks without needing to interact with the Hatchet engine. Use `mock_run` for sync tasks and `aio_mock_run` for async tasks. Parameters: Name, Type, Description, Default `input`, `TWorkflowInput \, None`, The input to the task., `None` `additional_metadata`, `JSONSerializableMapping \, None`, Additional metadata to attach to the task., `None` `parent_outputs`, `dict[str, JSONSerializableMapping] \, None`, Outputs from parent tasks, if any. This is useful for mimicking DAG functionality. For instance, if you have a task `step_2` that has a `parent` which is `step_1`, you can pass `parent_outputs={"step_1": {"result": "Hello, world!"}}` to `step_2.mock_run()` to be able to access `ctx.task_output(step_1)` in `step_2`., `None` `retry_count`, `int`, The number of times the task has been retried., `0` `lifespan`, `Any`, The lifespan to be used in the task, which is useful if one was set on the worker. This will allow you to access `ctx.lifespan` inside of your task., `None` `dependencies`, `dict[str, Any] \, None`, Dependencies to be injected into the task. This is useful for tasks that have dependencies defined using `Depends`. **IMPORTANT**: You must pass the dependencies _directly_, **not** the `Depends` objects themselves. For example, if you have a task that has a dependency `config: Annotated[str, Depends(get_config)]`, you should pass `dependencies={"config": "config_value"}` to `aio_mock_run`., `None` Returns: Type, Description `R`, The output of the task. Raises: Type, Description `TypeError`, If the task is an async function and `mock_run` is called, or if the task is a sync function and `aio_mock_run` is called. ## Standalone Bases: `BaseWorkflow[TWorkflowInput]`, `Generic[TWorkflowInput, R]` Methods: Name, Description `run`, Run the workflow synchronously and wait for it to complete. `aio_run`, Run the workflow asynchronously and wait for it to complete. `run_no_wait`, Trigger a workflow run without waiting for it to complete. `aio_run_no_wait`, Asynchronously trigger a workflow run without waiting for it to complete. `run_many`, Run a workflow in bulk and wait for all runs to complete. `aio_run_many`, Run a workflow in bulk and wait for all runs to complete. `run_many_no_wait`, Run a workflow in bulk without waiting for all runs to complete. `aio_run_many_no_wait`, Run a workflow in bulk without waiting for all runs to complete. `schedule`, Schedule a workflow to run at a specific time. `aio_schedule`, Schedule a workflow to run at a specific time. `create_cron`, Create a cron job for the workflow. `aio_create_cron`, Create a cron job for the workflow. `create_bulk_run_item`, Create a bulk run item for the workflow. This is intended to be used in conjunction with the various `run_many` methods. `list_runs`, List runs of the workflow. `aio_list_runs`, List runs of the workflow. `create_filter`, Create a new filter. `aio_create_filter`, Create a new filter. `delete`, Permanently delete the workflow. `aio_delete`, Permanently delete the workflow. `get_run_ref`, Get a reference to a task run by its run ID. `get_result`, Get the result of a task run by its run ID. `aio_get_result`, Get the result of a task run by its run ID. `mock_run`, Mimic the execution of a task. This method is intended to be used to unit test `aio_mock_run`, Mimic the execution of a task. This method is intended to be used to unit test ### Functions #### `run` Run the workflow synchronously and wait for it to complete. This method triggers a workflow run, blocks until completion, and returns the extracted result. Parameters: Name, Type, Description, Default `input`, `TWorkflowInput`, The input data for the workflow., `cast(TWorkflowInput, EmptyModel())` `options`, `TriggerWorkflowOptions`, Additional options for workflow execution., `TriggerWorkflowOptions()` Returns: Type, Description `R`, The extracted result of the workflow execution. #### `aio_run` Run the workflow asynchronously and wait for it to complete. This method triggers a workflow run, awaits until completion, and returns the extracted result. Parameters: Name, Type, Description, Default `input`, `TWorkflowInput`, The input data for the workflow, must match the workflow's input type., `cast(TWorkflowInput, EmptyModel())` `options`, `TriggerWorkflowOptions`, Additional options for workflow execution like metadata and parent workflow ID., `TriggerWorkflowOptions()` Returns: Type, Description `R`, The extracted result of the workflow execution. #### `run_no_wait` Trigger a workflow run without waiting for it to complete. This method triggers a workflow run and immediately returns a reference to the run without blocking while the workflow runs. Parameters: Name, Type, Description, Default `input`, `TWorkflowInput`, The input data for the workflow, must match the workflow's input type., `cast(TWorkflowInput, EmptyModel())` `options`, `TriggerWorkflowOptions`, Additional options for workflow execution like metadata and parent workflow ID., `TriggerWorkflowOptions()` Returns: Type, Description `TaskRunRef[TWorkflowInput, R]`, A `TaskRunRef` object representing the reference to the workflow run. #### `aio_run_no_wait` Asynchronously trigger a workflow run without waiting for it to complete. This method is useful for starting a workflow run and immediately returning a reference to the run without blocking while the workflow runs. Parameters: Name, Type, Description, Default `input`, `TWorkflowInput`, The input data for the workflow., `cast(TWorkflowInput, EmptyModel())` `options`, `TriggerWorkflowOptions`, Additional options for workflow execution., `TriggerWorkflowOptions()` Returns: Type, Description `TaskRunRef[TWorkflowInput, R]`, A `TaskRunRef` object representing the reference to the workflow run. #### `run_many` Run a workflow in bulk and wait for all runs to complete. This method triggers multiple workflow runs, blocks until all of them complete, and returns the final results. Parameters: Name, Type, Description, Default `workflows`, `list[WorkflowRunTriggerConfig]`, A list of `WorkflowRunTriggerConfig` objects, each representing a workflow run to be triggered., _required_ `return_exceptions`, `bool`, If `True`, exceptions will be returned as part of the results instead of raising them., `False` Returns: Type, Description `list[R] \, list[R \, BaseException]`, A list of results for each workflow run. #### `aio_run_many` Run a workflow in bulk and wait for all runs to complete. This method triggers multiple workflow runs, blocks until all of them complete, and returns the final results. Parameters: Name, Type, Description, Default `workflows`, `list[WorkflowRunTriggerConfig]`, A list of `WorkflowRunTriggerConfig` objects, each representing a workflow run to be triggered., _required_ `return_exceptions`, `bool`, If `True`, exceptions will be returned as part of the results instead of raising them., `False` Returns: Type, Description `list[R] \, list[R \, BaseException]`, A list of results for each workflow run. #### `run_many_no_wait` Run a workflow in bulk without waiting for all runs to complete. This method triggers multiple workflow runs and immediately returns a list of references to the runs without blocking while the workflows run. Parameters: Name, Type, Description, Default `workflows`, `list[WorkflowRunTriggerConfig]`, A list of `WorkflowRunTriggerConfig` objects, each representing a workflow run to be triggered., _required_ Returns: Type, Description `list[TaskRunRef[TWorkflowInput, R]]`, A list of `WorkflowRunRef` objects, each representing a reference to a workflow run. #### `aio_run_many_no_wait` Run a workflow in bulk without waiting for all runs to complete. This method triggers multiple workflow runs and immediately returns a list of references to the runs without blocking while the workflows run. Parameters: Name, Type, Description, Default `workflows`, `list[WorkflowRunTriggerConfig]`, A list of `WorkflowRunTriggerConfig` objects, each representing a workflow run to be triggered., _required_ Returns: Type, Description `list[TaskRunRef[TWorkflowInput, R]]`, A list of `WorkflowRunRef` objects, each representing a reference to a workflow run. #### `schedule` Schedule a workflow to run at a specific time. Parameters: Name, Type, Description, Default `run_at`, `datetime`, The time at which to schedule the workflow., _required_ `input`, `TWorkflowInput`, The input data for the workflow., `cast(TWorkflowInput, EmptyModel())` `options`, `ScheduleTriggerWorkflowOptions`, Additional options for workflow execution., `ScheduleTriggerWorkflowOptions()` Returns: Type, Description `WorkflowVersion`, A `WorkflowVersion` object representing the scheduled workflow. #### `aio_schedule` Schedule a workflow to run at a specific time. Parameters: Name, Type, Description, Default `run_at`, `datetime`, The time at which to schedule the workflow., _required_ `input`, `TWorkflowInput`, The input data for the workflow., `cast(TWorkflowInput, EmptyModel())` `options`, `ScheduleTriggerWorkflowOptions`, Additional options for workflow execution., `ScheduleTriggerWorkflowOptions()` Returns: Type, Description `WorkflowVersion`, A `WorkflowVersion` object representing the scheduled workflow. #### `create_cron` Create a cron job for the workflow. Parameters: Name, Type, Description, Default `cron_name`, `str`, The name of the cron job., _required_ `expression`, `str`, The cron expression that defines the schedule for the cron job., _required_ `input`, `TWorkflowInput`, The input data for the workflow., `cast(TWorkflowInput, EmptyModel())` `additional_metadata`, `JSONSerializableMapping \, None`, Additional metadata for the cron job., `None` `priority`, `int \, None`, The priority of the cron job. Must be between 1 and 3, inclusive., `None` Returns: Type, Description `CronWorkflows`, A `CronWorkflows` object representing the created cron job. #### `aio_create_cron` Create a cron job for the workflow. Parameters: Name, Type, Description, Default `cron_name`, `str`, The name of the cron job., _required_ `expression`, `str`, The cron expression that defines the schedule for the cron job., _required_ `input`, `TWorkflowInput`, The input data for the workflow., `cast(TWorkflowInput, EmptyModel())` `additional_metadata`, `JSONSerializableMapping \, None`, Additional metadata for the cron job., `None` `priority`, `int \, None`, The priority of the cron job. Must be between 1 and 3, inclusive., `None` Returns: Type, Description `CronWorkflows`, A `CronWorkflows` object representing the created cron job. #### `create_bulk_run_item` Create a bulk run item for the workflow. This is intended to be used in conjunction with the various `run_many` methods. Parameters: Name, Type, Description, Default `input`, `TWorkflowInput`, The input data for the workflow., `cast(TWorkflowInput, EmptyModel())` `key`, `str \, None`, The key for the workflow run. This is used to identify the run in the bulk operation and for deduplication., `None` `options`, `TriggerWorkflowOptions`, Additional options for the workflow run., `TriggerWorkflowOptions()` Returns: Type, Description `WorkflowRunTriggerConfig`, A `WorkflowRunTriggerConfig` object that can be used to trigger the workflow run, which you then pass into the `run_many` methods. #### `list_runs` List runs of the workflow. Parameters: Name, Type, Description, Default `since`, `datetime \, None`, The start time for the runs to be listed., `None` `until`, `datetime \, None`, The end time for the runs to be listed., `None` `limit`, `int`, The maximum number of runs to be listed., `100` `offset`, `int \, None`, The offset for pagination., `None` `statuses`, `list[V1TaskStatus] \, None`, The statuses of the runs to be listed., `None` `additional_metadata`, `dict[str, str] \, None`, Additional metadata for filtering the runs., `None` `worker_id`, `str \, None`, The ID of the worker that ran the tasks., `None` `parent_task_external_id`, `str \, None`, The external ID of the parent task., `None` `only_tasks`, `bool`, Whether to list only task runs., `False` `triggering_event_external_id`, `str \, None`, The event id that triggered the task run., `None` Returns: Type, Description `list[V1TaskSummary]`, A list of `V1TaskSummary` objects representing the runs of the workflow. #### `aio_list_runs` List runs of the workflow. Parameters: Name, Type, Description, Default `since`, `datetime \, None`, The start time for the runs to be listed., `None` `until`, `datetime \, None`, The end time for the runs to be listed., `None` `limit`, `int`, The maximum number of runs to be listed., `100` `offset`, `int \, None`, The offset for pagination., `None` `statuses`, `list[V1TaskStatus] \, None`, The statuses of the runs to be listed., `None` `additional_metadata`, `dict[str, str] \, None`, Additional metadata for filtering the runs., `None` `worker_id`, `str \, None`, The ID of the worker that ran the tasks., `None` `parent_task_external_id`, `str \, None`, The external ID of the parent task., `None` `only_tasks`, `bool`, Whether to list only task runs., `False` `triggering_event_external_id`, `str \, None`, The event id that triggered the task run., `None` Returns: Type, Description `list[V1TaskSummary]`, A list of `V1TaskSummary` objects representing the runs of the workflow. #### `create_filter` Create a new filter. Parameters: Name, Type, Description, Default `expression`, `str`, The expression to evaluate for the filter., _required_ `scope`, `str`, The scope for the filter., _required_ `payload`, `JSONSerializableMapping \, None`, The payload to send with the filter., `None` Returns: Type, Description `V1Filter`, The created filter. #### `aio_create_filter` Create a new filter. Parameters: Name, Type, Description, Default `expression`, `str`, The expression to evaluate for the filter., _required_ `scope`, `str`, The scope for the filter., _required_ `payload`, `JSONSerializableMapping \, None`, The payload to send with the filter., `None` Returns: Type, Description `V1Filter`, The created filter. #### `delete` Permanently delete the workflow. **DANGEROUS: This will delete a workflow and all of its data** #### `aio_delete` Permanently delete the workflow. **DANGEROUS: This will delete a workflow and all of its data** #### `get_run_ref` Get a reference to a task run by its run ID. Parameters: Name, Type, Description, Default `run_id`, `str`, The ID of the run to get the reference for., _required_ Returns: Type, Description `TaskRunRef[TWorkflowInput, R]`, A `TaskRunRef` object representing the reference to the task run. #### `get_result` Get the result of a task run by its run ID. Parameters: Name, Type, Description, Default `run_id`, `str`, The ID of the run to get the result for., _required_ Returns: Type, Description `R`, The result of the task run. #### `aio_get_result` Get the result of a task run by its run ID. Parameters: Name, Type, Description, Default `run_id`, `str`, The ID of the run to get the result for., _required_ Returns: Type, Description `R`, The result of the task run. #### `mock_run` Mimic the execution of a task. This method is intended to be used to unit test tasks without needing to interact with the Hatchet engine. Use `mock_run` for sync tasks and `aio_mock_run` for async tasks. Parameters: Name, Type, Description, Default `input`, `TWorkflowInput \, None`, The input to the task., `None` `additional_metadata`, `JSONSerializableMapping \, None`, Additional metadata to attach to the task., `None` `parent_outputs`, `dict[str, JSONSerializableMapping] \, None`, Outputs from parent tasks, if any. This is useful for mimicking DAG functionality. For instance, if you have a task `step_2` that has a `parent` which is `step_1`, you can pass `parent_outputs={"step_1": {"result": "Hello, world!"}}` to `step_2.mock_run()` to be able to access `ctx.task_output(step_1)` in `step_2`., `None` `retry_count`, `int`, The number of times the task has been retried., `0` `lifespan`, `Any`, The lifespan to be used in the task, which is useful if one was set on the worker. This will allow you to access `ctx.lifespan` inside of your task., `None` `dependencies`, `dict[str, Any] \, None`, Dependencies to be injected into the task. This is useful for tasks that have dependencies defined using `Depends`. **IMPORTANT**: You must pass the dependencies _directly_, **not** the `Depends` objects themselves. For example, if you have a task that has a dependency `config: Annotated[str, Depends(get_config)]`, you should pass `dependencies={"config": "config_value"}` to `aio_mock_run`., `None` Returns: Type, Description `R`, The output of the task. #### `aio_mock_run` Mimic the execution of a task. This method is intended to be used to unit test tasks without needing to interact with the Hatchet engine. Use `mock_run` for sync tasks and `aio_mock_run` for async tasks. Parameters: Name, Type, Description, Default `input`, `TWorkflowInput \, None`, The input to the task., `None` `additional_metadata`, `JSONSerializableMapping \, None`, Additional metadata to attach to the task., `None` `parent_outputs`, `dict[str, JSONSerializableMapping] \, None`, Outputs from parent tasks, if any. This is useful for mimicking DAG functionality. For instance, if you have a task `step_2` that has a `parent` which is `step_1`, you can pass `parent_outputs={"step_1": {"result": "Hello, world!"}}` to `step_2.mock_run()` to be able to access `ctx.task_output(step_1)` in `step_2`., `None` `retry_count`, `int`, The number of times the task has been retried., `0` `lifespan`, `Any`, The lifespan to be used in the task, which is useful if one was set on the worker. This will allow you to access `ctx.lifespan` inside of your task., `None` `dependencies`, `dict[str, Any] \, None`, Dependencies to be injected into the task. This is useful for tasks that have dependencies defined using `Depends`. **IMPORTANT**: You must pass the dependencies _directly_, **not** the `Depends` objects themselves. For example, if you have a task that has a dependency `config: Annotated[str, Depends(get_config)]`, you should pass `dependencies={"config": "config_value"}` to `aio_mock_run`., `None` Returns: Type, Description `R`, The output of the task.