hatchet-dev/hatchet py/2.0.0a1 on GitHub

Overview

V2 removes everything that was deprecated in V1 and tightens the types that were previously coerced. See the V2 migration guide for before and after examples of every breaking change, including a quick reference table suitable for handing to a coding agent.

Removed

The run_no_wait, aio_run_no_wait, run_many_no_wait, and aio_run_many_no_wait methods. Pass wait_for_result=False to run, aio_run, run_many, and aio_run_many instead.
The options parameter on run, aio_run, schedule, aio_schedule, and create_bulk_run_item, and on events.push and events.aio_push. Pass the fields as keyword arguments instead. PushEventOptions and BulkPushEventOptions have been removed.
The key parameter on create_bulk_run_item. Use child_key instead.
The parent_id, parent_step_run_id, child_index, key, and namespace fields on TriggerWorkflowOptions and ScheduleTriggerWorkflowOptions, and the key field on WorkflowRunTriggerConfig.
The desired_worker_id parameter on run, aio_run, and create_bulk_run_item, and the desired_worker_id field on TriggerWorkflowOptions. Pass sticky=True to run a child on the same worker as the task that triggers it.
EmptyModel. Tasks and workflows with no input validator now receive None as their input, and running a task that returns nothing gives None.
Every SDK enum. Fixed sets of choices are plain strings typed as Literals: RunStatus ("QUEUED", "RUNNING", "COMPLETED", "CANCELLED", "FAILED"), Priority ("LOW", "MEDIUM", "HIGH"), WorkerLabelComparator ("EQUAL", "LESS_THAN", ...), SlotType ("default", "durable"), HTTPMethod, OTelAttribute (the span attribute name, such as "step_name"), and WorkerStatus. These names survive as Literal type aliases. ConcurrencyLimitStrategy, StickyStrategy, RateLimitDuration, and MCPProvider are gone entirely; pass the member name as a string (for example "CANCEL_IN_PROGRESS", "SOFT", "MINUTE", "CLAUDE"). QUEUE_NEWEST and QUEUE_OLDEST have no replacement, since the engine no longer supports them.
String durations such as "10s". execution_timeout, schedule_timeout, ctx.refresh_timeout, ctx.aio_sleep_for, and SleepCondition only accept a timedelta.
Integer priorities. Every priority and default_priority parameter and field only accepts "LOW", "MEDIUM", or "HIGH". Use priority_to_int from hatchet_sdk.types.priority to compare them.
TaskDefaults.priority, which was never read. Set default_priority on the workflow instead.
dict values for desired_worker_labels, and integer comparator values on DesiredWorkerLabel. Use a list[DesiredWorkerLabel] and a comparator name such as "EQUAL".
dict values for the labels argument to hatchet.worker and the Worker constructor. Use a list[WorkerLabel].
Synchronous durable tasks. Declaring one raises a TypeError.
ctx.step_run_id, ctx.workflow_input, ctx.input, ctx.done, ctx.exit_flag, ctx.aio_task_output, ctx.fetch_task_run_error, and ctx.worker, along with the WorkerContext class. Use ctx.task_run_id, the task's input argument, ctx.is_cancelled, ctx.task_output, ctx.get_task_run_error, ctx.worker_id, ctx.worker_labels, and ctx.upsert_worker_labels.
ctx.trigger_data. Use ctx.filter_payload, which holds its filter_payload entry.
The raise_on_error parameter on ctx.log and ctx.aio_log.
Internal Context properties: data, action, dispatcher_client, admin_client, event_client, runs_client, log_sender, and durable_event_listener, and DurableContext.wait_index.
Hatchet.get_current_context(). Use the hatchet.current_context property.
The debug and client parameters on the Hatchet constructor, the debug parameter on the Worker constructor, and the internal hatchet_sdk.client.Client class. Set HATCHET_CLIENT_DEBUG=true and pass config=ClientConfig(...) instead.
The handle_kill parameter on the Worker constructor. Worker.start() returns after a graceful shutdown instead of exiting the process.
The hatchet.listener and hatchet.dispatcher properties, the log, stream, and aio_stream methods and the token and namespace attributes on the events client, and the workflow_run_listener, workflow_run_event_listener, and admin_client properties on hatchet.runs, WorkflowRunRef, and TaskRunRef.
runs.list_with_pagination and runs.aio_list_with_pagination. runs.list and runs.aio_list now paginate internally.
workers.update and workers.aio_update. Use workers.pause and workers.unpause, or their aio_ variants.
The statuses parameter on scheduled.bulk_delete and scheduled.aio_bulk_delete. The API has no status filter for bulk deletes, so it was ignored.
The stream method on WorkflowRunRef and TaskRunRef. Use hatchet.streams, or the deprecated hatchet.runs.aio_subscribe_to_stream(ref.workflow_run_id).
The create_traceparent, parse_carrier_from_metadata, and inject_traceparent_into_metadata functions in hatchet_sdk.opentelemetry.instrumentor. HatchetInstrumentor has propagated the traceparent automatically since 1.11.0.
WorkerStartOptions and the options parameter on Worker.start, and Worker.register_workflow_from_opts.
Internal Worker, Workflow, Task, and condition attributes and methods, including worker.config, worker.slot_config, worker.labels, worker.action_registry, worker.exit_gracefully, workflow.config, workflow.client, workflow.service_name, workflow.create_action_name, workflow.to_proto, task.fn, task.slot_requests, task.call, task.aio_call, task.to_proto, the task settings (task.type, task.retries, task.execution_timeout, task.schedule_timeout, task.parents, task.rate_limits, task.desired_worker_labels, task.backoff_factor, task.backoff_max_seconds, task.concurrency, task.wait_for, task.skip_if, task.cancel_if, task.batch, and task.eviction_policy), Standalone.is_async_function, the base attribute and to_proto method on conditions, the hatchet_sdk.conditions.Action enum, and Depends(...).fn. task.name is still public.
TaskRunError.serialize, TaskRunError.deserialize, and TaskRunError.from_exception. Use str(error), or the exc, exc_type, and trace attributes.
The config, tracer_provider, and meter_provider attributes and the extract_bound_args method on HatchetInstrumentor.
The StepRunEventType and WorkflowRunEventType exports, and the StepRunEvent class. runs.aio_subscribe_to_stream yields plain str chunks, so there are no event types to match on.
The event_timestamp field on Event and its eventTimestamp and additionalMetadata aliases. Use seen_at and additional_metadata.
The hatchet_sdk.labels, hatchet_sdk.rate_limit, and hatchet_sdk.utils.priority module aliases.
The re-exports in the hatchet_sdk.types package (DesiredWorkerLabel, WorkerLabelComparator, Priority, RateLimit, and SlotType). Import them from hatchet_sdk.
Top-level hatchet_sdk exports of the V0 REST models, the pagination wrapper types, and CreateWorkflowVersionOpts. Import REST models from hatchet_sdk.clients.rest.models.
The PARENT_ID, PARENT_STEP_RUN_ID, CHILD_INDEX, and DESIRED_WORKER_ID members of OTelAttribute. Their values (parent_id, parent_step_run_id, child_index, desired_worker_id) are no longer valid entries in OpenTelemetryConfig.excluded_attributes or HATCHET_CLIENT_OPENTELEMETRY_EXCLUDED_ATTRIBUTES.
The hatchet.namespace and hatchet.key attributes on the run, bulk run, and schedule spans. The child key is still reported as hatchet.child_key. The run, bulk run, and durable spawn spans also no longer set hatchet.desired_worker_id.
The V1TaskStatus export from hatchet_sdk. Use RunStatus instead.
RunStatus.from_proto, RunStatus.from_v1_task_status, and RunStatus.to_v1_task_status.
ctx.pause_rate_limit and ctx.aio_pause_rate_limit. Use hatchet.rate_limits.pause and hatchet.rate_limits.aio_pause.
The ScheduledRunStatus, CronWorkflowsOrderByField, ScheduledWorkflowsOrderByField, RateLimitOrderByField, RateLimitOrderByDirection, WorkflowRunOrderByDirection, V1WebhookSourceName, V1WebhookHMACAlgorithm, V1WebhookHMACEncoding, V1WebhookBasicAuth, V1WebhookAPIKeyAuth, and V1WebhookHMACAuth exports from hatchet_sdk.
The TriggerWorkflowOptions, ScheduleTriggerWorkflowOptions, RunEventListener, and WorkflowConfig exports from hatchet_sdk. No public method accepts them now that the options parameters are gone. To build a WorkflowRunTriggerConfig, use create_bulk_run_item instead of constructing one by hand.

Changed

Python 3.11 or newer is required.
Optional parameters that follow a method's main arguments are keyword-only, so passing them positionally raises a TypeError. This covers run, aio_run, run_many, aio_run_many, create_bulk_run_item, schedule, aio_schedule, create_cron, aio_create_cron, create_filter, aio_create_filter, list_runs, aio_list_runs, pause, aio_pause, mock_run, and aio_mock_run on workflows and tasks; the task, durable_task, batch_task, on_failure_task, and on_success_task decorators on a workflow (after name); hatchet.worker and the Worker constructor; poll_interval on WorkflowRunRef.result and TaskRunRef.result; SleepCondition, UserEventCondition, and ParentCondition; the label parameter on ctx.aio_sleep_for and ctx.aio_sleep_until; streams.aio_reset; every HatchetInstrumentor parameter; and, along with their aio_ variants, cel.debug, crons.create, crons.list, events.push, events.list, filters.create, filters.list, logs.list, metrics.get_task_metrics, rate_limits.put, rate_limits.list, runs.list, runs.create, runs.reset_durable_task, scheduled.create, scheduled.list, streams.topic_metadata, webhooks.create, webhooks.update, webhooks.list, workflows.list, workflows.get_version, and workflows.pause. Pass these arguments by keyword. input and additional_metadata on crons.create and scheduled.create are still required.
hatchet.event has been renamed to hatchet.events, and hatchet.cron has been renamed to hatchet.crons, consistent with the other (plural) feature clients.
runs.subscribe_to_stream has been renamed to runs.aio_subscribe_to_stream, consistent with the aio_ prefix on every other async method.
streams.publish has been renamed to streams.aio_publish, and streams.subscribe has been renamed to streams.aio_subscribe, since both are async.
runs.bulk_replay_by_filters_with_pagination and runs.bulk_cancel_by_filters_with_pagination, and their aio_ variants, have been renamed to bulk_replay_by_filters_in_chunks and bulk_cancel_by_filters_in_chunks. Their sleep_time parameter (an integer number of seconds) has been renamed to delay_between_chunks and takes a timedelta.
ConcurrencyExpression has been renamed to ConcurrencyStrategy, and its limit_strategy field has been renamed to strategy.
TriggerWorkflowOptions.desired_worker_label has been renamed to desired_worker_labels and only accepts a list[DesiredWorkerLabel].
Every list and aio_list method on the feature clients returns a plain list instead of a paginated wrapper, so there is no .rows to unwrap.
crons.create, crons.get, crons.list, their aio_ variants, and workflow.create_cron return the SDK's CronTrigger instead of the CronWorkflows REST model. Read cron.id instead of cron.metadata.id, cron.created_at and cron.updated_at instead of cron.metadata.created_at and cron.metadata.updated_at, and cron.expression instead of cron.cron. input and additional_metadata are empty dictionaries instead of None when unset.
scheduled.create, scheduled.update, scheduled.get, scheduled.list, their aio_ variants, and workflow.schedule and workflow.aio_schedule return the SDK's ScheduledRun. The scheduled client previously returned the ScheduledWorkflows REST model, so read scheduled.id instead of scheduled.metadata.id. workflow.schedule previously returned the V0 WorkflowVersion protobuf, so read scheduled.id instead of scheduled.scheduled_workflows[0].id. ScheduledRun.workflow_run_status is a RunStatus, or None before the schedule has triggered: PENDING, QUEUED, and BACKOFF become QUEUED, and SUCCEEDED becomes COMPLETED. input and additional_metadata are empty dictionaries instead of None when unset.
runs.list, runs.get_task_run, their aio_ variants, and workflow.list_runs and workflow.aio_list_runs return the SDK's TaskRunSummary instead of the V1TaskSummary REST model. Read run.id instead of run.metadata.id, task_run_id instead of task_external_id, workflow_run_id instead of workflow_run_external_id, and parent_task_run_id instead of parent_task_external_id. duration is a timedelta instead of an integer number of milliseconds, and additional_metadata is an empty dictionary instead of None when unset. The internal task_id, task_inserted_at, step_id, action_id, and workflow_config fields have been dropped.
The workflow.id property has been replaced by workflow.get_id() and workflow.aio_get_id(), which fetch the ID on the first call and cache it.
filters.update and filters.aio_update take expression, scope, and payload keyword arguments instead of a V1UpdateFilterRequest. Fields left as None are not changed.
ctx.aio_wait_for returns a list[SleepResult | EventWaitResult | OrGroupResult] instead of a dict, and ctx.aio_wait_for_event returns an EventWaitResult whose .payload holds the event data.
ctx.aio_wait_for no longer takes a signal key as its first argument. Pass the conditions directly, and pass signal_key= by keyword if you need a specific key. When it is left out, the key is generated from the order of the wait within the task run, which is stable across replays.
ctx.refresh_timeout, ctx.aio_refresh_timeout, ctx.put_stream, and ctx.aio_put_stream raise when the request fails, instead of logging the error and returning.
ctx.priority now returns "LOW", "MEDIUM", "HIGH", or None instead of int | None.
ctx.worker_labels is a list[WorkerLabel] instead of a dict, and ctx.upsert_worker_labels and ctx.aio_upsert_worker_labels take a list[WorkerLabel], matching the labels argument to hatchet.worker.
The task_run_errors parameter on mock_run and aio_mock_run takes a dict[str, TaskRunError] instead of serialized error strings, matching ctx.task_run_errors. Their trigger_data parameter has been replaced by filter_payload, which sets ctx.filter_payload.
from hatchet_sdk import Event now resolves to the SDK's own event class instead of the V0 REST model. Every method on the events client returns it: push, bulk_push, get, and list, along with their aio_ variants. get and list previously returned the V1Event REST model, so read event.id instead of event.metadata.id.
Event.event_id has been renamed to Event.id.
Event.payload and Event.additional_metadata are now dictionaries instead of JSON strings, so there is no need to call json.loads on them. additional_metadata is an empty dictionary when the event has none.
BulkPushEventWithMetadata.key is now required.
workflow.input_validator and workflow.input_validator_type return None for a workflow with no input validator.
Worker.register_workflow now raises on registration failure instead of calling sys.exit(1), and Worker.start() raises if the action listener process fails to start, also instead of calling sys.exit(1).
Worker.start() returns after a graceful shutdown (on SIGTERM or SIGINT, or after terminate_worker_after_num_tasks tasks) instead of calling sys.exit(0), so code after worker.start() now runs. A forced shutdown still exits with status 1.
FailedTaskRunExceptionGroup is now an ExceptionGroup[TaskRunError] instead of a ValueError. except ValueError no longer catches it, and except* TaskRunError does. .exceptions is a tuple instead of a list, and holds a single TaskRunError carrying the message when the run failed without reporting any task errors. str() is unchanged, and .message now holds the same text, the run's failure message followed by each task error, so pytest.raises(FailedTaskRunExceptionGroup, match=...) still matches on task errors.
backoff_max_seconds (an integer number of seconds) has been renamed to backoff_max and takes a timedelta, on every task decorator and on TaskDefaults. It is sent to the engine as whole seconds.
poll_interval on WorkflowRunRef.result and TaskRunRef.result takes a timedelta instead of a number of seconds.
ClientConfig.sync_result_poll_interval is a timedelta instead of a float. HATCHET_CLIENT_SYNC_RESULT_POLL_INTERVAL is still a number of seconds. DEFAULT_SYNC_RESULT_POLL_INTERVAL_SECONDS in hatchet_sdk.config has been renamed to DEFAULT_SYNC_RESULT_POLL_INTERVAL and is a timedelta.
ClientConfig.listener_v2_timeout (an integer number of seconds) has been renamed to action_listener_timeout and takes a timedelta. Its environment variable is now HATCHET_CLIENT_ACTION_LISTENER_TIMEOUT, still a number of seconds.
EmbeddedHatchetConfig.ready_timeout_seconds has been renamed to ready_timeout and takes a timedelta. Its environment variable is now HATCHET_CLIENT_EMBEDDED_READY_TIMEOUT, still a number of seconds. DEFAULT_READY_TIMEOUT_SECONDS in hatchet_sdk.config has been renamed to DEFAULT_EMBEDDED_READY_TIMEOUT and is a timedelta.
OpenTelemetryConfig.include_task_name_in_start_step_run_span_name has been renamed to include_task_name_in_span_name, and its environment variable to HATCHET_CLIENT_OPENTELEMETRY_INCLUDE_TASK_NAME_IN_SPAN_NAME.
HealthcheckConfig.event_loop_block_threshold_seconds has been renamed to event_loop_block_threshold, and its environment variable to HATCHET_CLIENT_WORKER_HEALTHCHECK_EVENT_LOOP_BLOCK_THRESHOLD.
ClientTLSConfig.strategy is now typed as Literal["tls", "mtls", "none"].
TaskDefaults rejects unknown fields, so a leftover field such as backoff_max_seconds or priority raises a ValidationError instead of being ignored.
WorkerLabel.key is required, and DesiredWorkerLabel no longer subclasses WorkerLabel.
The default readable_data_key of a ParentCondition is the parent task's name, followed by : and the expression when one is set. It previously also included the time the condition was created, so the workflow definition changed every time the worker started. Two ParentConditions on the same task with the same parent and expression now need distinct readable_data_key values, or registering the workflow raises a ValueError.
RunStatus is now the only run status type. Every status the SDK accepts or returns is a RunStatus, including TaskRunSummary.status, ScheduledRun.workflow_run_status, the status field on REST models, and the statuses filters on runs.list and events.list.
The statuses filter on scheduled.list and scheduled.aio_list takes RunStatus values, plus "SCHEDULED" for schedules that have not triggered yet, instead of ScheduledRunStatus.
The order_by_field and order_by_direction parameters on crons.list, scheduled.list, rate_limits.list, and their aio_ variants take snake_case strings ("created_at", "trigger_at", "limit_value", ...) and "asc" or "desc", instead of the REST ordering enums.
webhooks.create and webhooks.aio_create take WebhookBasicAuth, WebhookAPIKeyAuth, or WebhookHMACAuth, with snake_case fields and string HMAC algorithms and encodings, instead of the V1Webhook*Auth REST models. source_name on webhooks.create and source_names on webhooks.list are strings.
NotFoundException has been renamed to NotFoundError.
The events client module has moved from hatchet_sdk.clients.events to hatchet_sdk.features.events, alongside the other feature clients.
The parent_step_run_id parameter on scheduled.bulk_delete and scheduled.aio_bulk_delete has been renamed to parent_task_run_id.
Worker log messages and error messages refer to tasks instead of steps.
NonRetryableException has been renamed to NonRetryableError, and RetryAfterException has been renamed to RetryAfterError.
ctx.task_run_errors returns a dict[str, TaskRunError] instead of a dictionary of serialized error strings, and no longer logs an error when there are no upstream errors.
BulkCancelReplayOpts has been renamed to BulkCancelReplayOptions, and the opts parameter on runs.bulk_cancel and runs.bulk_replay has been renamed to options.
The run_at parameter on schedule and aio_schedule has been renamed to trigger_at, matching the scheduled runs client and the trigger_at field on scheduled runs.
Run ID parameters now use one name per kind of ID. runs.get_result, runs.get_details, and the get_run_ref, get_result, and aio_get_result methods on a standalone task take workflow_run_id. runs.reset_durable_task takes task_run_id instead of task_external_id. runs.cancel and runs.replay keep run_id, since they accept either kind. The parent_task_external_id and triggering_event_external_id filters on runs.list, metrics.get_task_metrics, workflow.list_runs, and their aio_ variants have been renamed to parent_task_run_id and triggering_event_id.
runs.list, runs.aio_list, workflow.list_runs, and workflow.aio_list_runs page through every result internally, and leaving limit unset returns every matching run. In V1, runs.list returned the first 50 runs, and workflow.list_runs returned up to 100 runs for each day in the range. limit and offset now apply to the whole time range.
from hatchet_sdk import Workflow now resolves to the workflow class returned by hatchet.workflow() instead of the REST model, and the WorkflowVersion REST model is no longer exported from hatchet_sdk.
Passing an input when running, scheduling, or bulk running a task or workflow that has no input_validator raises a TypeError instead of silently dropping the input. Declare input_validator=dict[str, Any] to accept untyped input.
schedule_timeout, execution_timeout, and retries on Workflow.task, Workflow.durable_task, Workflow.on_failure_task, and Workflow.on_success_task, and schedule_timeout and execution_timeout on Workflow.batch_task, default to None, which falls back to the workflow's task_defaults and then to the built-in defaults (5 minutes, 60 seconds, and 0). on_failure_task and on_success_task previously ignored task_defaults, including backoff_factor and backoff_max. An explicit value that equals a built-in default, such as retries=0, is no longer replaced by task_defaults.
IdempotencyCollisionError and BulkTriggerIdempotencyCollisionError now carry a message naming the colliding runs.
Scheduling a run with a timezone-aware, non-UTC datetime no longer logs a warning. The datetime was already converted correctly.
result and aio_result on WorkflowRunRef and TaskRunRef raise RuntimeError instead of ValueError when fetching the run's status fails repeatedly. A cancelled run still raises ValueError.
ctx.aio_wait_for_event raises a ValueError if the wait completes without a matching event.
ctx.aio_wait_for raises a ValueError if two of its conditions have the same readable_data_key, which includes identical conditions with default keys in different OrGroups. Previously one of their results was silently dropped.
ctx.task_output(parent) returns a dict for a parent task with no return annotation, and running a hatchet.stubs.task with no output_validator returns the remote task's output as a dict, both instead of an EmptyModel with attribute access.
hatchet_sdk.types.idempotency.BaseIdemotencyConfig has been renamed to BaseIdempotencyConfig.
hatchet_sdk.runnables.contextvars.ctx_step_run_id has been renamed to ctx_task_run_external_id.
The generated REST client packages import their models and APIs on first use, which makes import hatchet_sdk faster.

Added

result and aio_result on WorkflowRunRef and TaskRunRef accept an optional timeout (a timedelta) and raise TimeoutError when it elapses.
CronTrigger, ScheduledRun, and TaskRunSummary, the SDK's own models for cron triggers, scheduled runs, and task run summaries.
SleepResult, EventWaitResult, OrGroupResult, HTTPMethod, CronTrigger, ScheduledRun, TaskRunSummary, TaskRunDetail, WorkflowRunDetail, TaskMetrics, NotFoundError, WebhookBasicAuth, WebhookAPIKeyAuth, WebhookHMACAuth, WebhookSourceName, WebhookHMACAlgorithm, and WebhookHMACEncoding are exported from hatchet_sdk, so every type a public method accepts or returns can be imported from the top level.
durable_task decorators accept slot_cost, controlling how many durable slots the task consumes.
hatchet.batch_task accepts on_events, on_crons, cron_input, and default_additional_metadata, matching the other standalone task decorators.
hatchet.tenant, a client for reading details about the current tenant.
Standalone, the class returned by the hatchet.task, hatchet.durable_task, and hatchet.batch_task decorators, is exported from hatchet_sdk.

Deprecated

ctx.put_stream, ctx.aio_put_stream, and hatchet.runs.aio_subscribe_to_stream, which now emit a DeprecationWarning. Use durable streams (hatchet.streams.aio_publish and hatchet.streams.aio_subscribe) instead.

Fixed

Running a standalone task that returned {} or None no longer gives the caller a dictionary keyed by the task name. A task annotated to return a dict gives {}, and a task with no return annotation or one that allows None gives None.
A hatchet.batch_task with no input_validator now receives None for each item, like every other task with no input validator.
Passing a tuple of ConcurrencyStrategy objects as concurrency to hatchet.task or hatchet.durable_task no longer discards them, and passing a single ConcurrencyStrategy to workflow.task, workflow.durable_task, workflow.on_failure_task, or workflow.on_success_task no longer fails when the workflow is registered.
mock_run and aio_mock_run now pass a dict input through to the task instead of replacing it with {}.
Cron expressions that use day or month names, or ranges with steps, such as 0 9 * * MON-FRI, are no longer rejected before they reach the engine.
ctx.aio_sleep_until with a time in the past completes immediately instead of sleeping for a negative duration.
HATCHET_CLIENT_TENACITY_* environment variables set after hatchet_sdk is imported are now read when a ClientConfig is created.
TaskRunError sets args, so it can be pickled.
The hatchet.durable.wait_for span reports the actual number of conditions in hatchet.num_conditions instead of always 2, and leaves out hatchet.signal_key when the key was generated.
HatchetInstrumentor.uninstrument() now also unwraps events.aio_push and events.aio_bulk_push.