[Python] Refactor: v2.0.0 Prep

[mrkaye97]

Description

[1.29.0] - 2026-03-16

Added

• Adds wait_for_result parameter to run(), aio_run(), run_many(), and aio_run_many() on both Workflow and Standalone. Passing wait_for_result=False replaces the run_no_wait / aio_run_no_wait / run_many_no_wait / aio_run_many_no_wait methods.
• Exports WorkerLabel from the top-level hatchet_sdk package, alongside the existing DesiredWorkerLabel and WorkerLabelComparator.
• Exports Priority, ConcurrencyExpression, ConcurrencyLimitStrategy, RateLimit, RateLimitDuration, StickyStrategy, SlotType, BulkPushEventOptions, BulkPushEventWithMetadata, PushEventOptions, and WorkflowRunTriggerConfig from the top-level hatchet_sdk package.
• Adds a current_context property to Hatchet as a replacement for the deprecated get_current_context() method.

Changed

• worker_labels and desired_worker_labels are now stored internally as list[WorkerLabel] / list[DesiredWorkerLabel] and converted to the protobuf representation at the last moment, rather than eagerly at construction time.

Deprecated

• run_no_wait(), aio_run_no_wait(), run_many_no_wait(), and aio_run_many_no_wait() are deprecated in favor of run(wait_for_result=False), aio_run(wait_for_result=False), run_many(wait_for_result=False), and aio_run_many(wait_for_result=False) respectively.
• Passing duration parameters (e.g. schedule_timeout, execution_timeout) as strings is deprecated. Use timedelta objects instead.
• Non-async durable tasks are deprecated. Please convert durable task functions to async.
• Passing worker_labels as a dict to hatchet.worker() is deprecated. Use a list[WorkerLabel] with the key field set instead.
• Passing desired_worker_labels as a dict to task decorators (@workflow.task, @hatchet.task, etc.) is deprecated. Use a list[DesiredWorkerLabel] with the key field set instead.
• Passing desired_worker_label as a dict to TriggerWorkflowOptions is deprecated. Use a list[DesiredWorkerLabel] with the key field set instead.
• Passing priority as an int to task and workflow decorators is deprecated. Use Priority.LOW, Priority.MEDIUM, or Priority.HIGH instead.
• Passing comparator as an int to DesiredWorkerLabel is deprecated. Use WorkerLabelComparator enum values instead.
• The debug parameter on Hatchet() is deprecated. Set debug mode via the HATCHET_CLIENT_DEBUG environment variable instead.
• The client parameter on Hatchet() is deprecated and will be removed in v2.0.0.
• Hatchet.get_current_context() is deprecated. Use the Hatchet.current_context property instead.
• Context.step_run_id is deprecated. Use Context.task_run_id instead.
• Context.workflow_input and Context.input are deprecated. Use the input argument passed directly to the task function instead.
• Context.aio_task_output() is deprecated. Use Context.task_output() instead.
• Context.done is deprecated. Use Context.is_cancelled instead.
• Context.fetch_task_run_error() is deprecated. Use Context.get_task_run_error() instead.
• Deprecates a number of internal properties and methods on the Worker and Context that are not intended for public use. These will be removed in v2.0.0.

Type of change

• New feature (non-breaking change which adds functionality)
• Refactor (non-breaking changes to code which doesn't change any behaviour)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hatchet-docs	Ready	Preview, Comment	Mar 17, 2026 9:33pm

[Copilot]

Pull request overview

Prepares the Python SDK for v2.0.0 by introducing new, more consistent execution APIs and adding deprecations for soon-to-be-removed behaviors (no-wait methods, string durations, non-async durable tasks, and internal Context/client accessors).

Changes:

• Add wait_for_result to workflow/task run* and aio_run* APIs, deprecating the *_no_wait variants.
• Add deprecation warnings for string duration inputs and non-async durable tasks.
• Deprecate internal Context/RunsClient properties via private fields + warning-emitting accessors; bump version and changelog.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
sdks/python/pyproject.toml	Bumps SDK version to 1.29.0.
sdks/python/hatchet_sdk/utils/timedelta_to_expression.py	Adds helper to warn on deprecated string durations.
sdks/python/hatchet_sdk/utils/aio.py	Extends gather_max_concurrency typing/behavior to support return_exceptions.
sdks/python/hatchet_sdk/runnables/workflow.py	Adds wait_for_result across run APIs; deprecates no-wait methods; updates async bulk result collection.
sdks/python/hatchet_sdk/runnables/task.py	Warns on deprecated non-async durable tasks.
sdks/python/hatchet_sdk/hatchet.py	Deprecates debug/client ctor params and adjusts config/debug handling.
sdks/python/hatchet_sdk/features/runs.py	Converts internal dependencies to private fields and adds warning properties for internal access.
sdks/python/hatchet_sdk/context/context.py	Deprecates internal Context fields via warning properties; adds new cancellation and async helper methods.
sdks/python/hatchet_sdk/config.py	Adds debug to ClientConfig settings.
sdks/python/hatchet_sdk/conditions.py	Warns when SleepCondition is constructed with string duration.
sdks/python/CHANGELOG.md	Documents 1.29.0 additions/deprecations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The overload for run_many(..., *, wait_for_result: Literal[False]) makes wait_for_result keyword-only, but the implementation allows it positionally (def run_many(..., return_exceptions=False, wait_for_result=True)). Align the implementation signature with the overload (e.g., make wait_for_result keyword-only) to avoid type-checker/runtime inconsistencies.

Suggested change

	return_exceptions: bool = False,
	return_exceptions: bool = False,
	*,

[Copilot]

The overload for run_many(..., *, wait_for_result: Literal[False]) makes wait_for_result keyword-only, but the implementation allows it positionally. Adjust the implementation signature to match the overload to keep typing consistent for Standalone.run_many.

Suggested change

	return_exceptions: bool = False,
	return_exceptions: bool = False,
	*,

[Copilot]

The overload for aio_run_many(..., *, wait_for_result: Literal[False]) makes wait_for_result keyword-only, but the implementation allows it positionally. Update the implementation signature (keyword-only) or the overload so type checkers and runtime calls agree for Standalone.aio_run_many.

[Copilot]

The overload for aio_run_many(..., *, wait_for_result: Literal[False]) makes wait_for_result keyword-only, but the implementation allows it positionally. Make wait_for_result keyword-only in the implementation (or remove the * from the overload) so the type hints match actual call semantics.

[promptless-for-oss]

📝 Documentation updates detected!

New suggestion: Document Python SDK v2.0.0 deprecations and new Context API

---

Tip: Sort by Shortest Review in the Dashboard to find quick wins ⚡

[promptless-for-oss]

📝 Documentation updates detected!

New suggestion: Document Python SDK v2.0.0 deprecations and new Context API

---

Tip: Use Vale? Add your vale.ini when setting up your Docs Collection.

[Copilot]

Pull request overview

Copilot reviewed 252 out of 252 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

sdks/python/hatchet_sdk/clients/dispatcher/dispatcher.py:247

• async_upsert_worker_labels still accepts a dict[str, str | int] and manually builds WorkerLabels, while upsert_worker_labels was changed to accept list[WorkerLabel]. This inconsistency makes the API confusing and undermines the new label type; consider updating the async method to accept list[WorkerLabel] (or deprecate/remove it) and share the same conversion logic.