# Hatchet Python SDK Reference

This is the Python SDK reference, documenting methods available for interacting with Hatchet resources. Check out the [user guide](../../home) for an introduction for getting your first tasks running.

## The Hatchet Python Client

Main client for interacting with the Hatchet SDK.

This class provides access to various client interfaces and utility methods for working with Hatchet workers, workflows, tasks, and our various feature clients.

Methods:

| Name           | Description                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| `worker`       | Create a Hatchet worker on which to run workflows.                                                            |
| `workflow`     | Define a Hatchet workflow, which can then declare `task`s and be `run`, `schedule`d, etc.                     |
| `task`         | A decorator to transform a function into a standalone Hatchet task that runs as part of a workflow.           |
| `durable_task` | A decorator to transform a function into a standalone Hatchet _durable_ task that runs as part of a workflow. |

### Attributes

#### `cron`

The cron client is a client for managing cron workflows within Hatchet.

#### `event`

The event client, which you can use to push events to Hatchet.

#### `logs`

The logs client is a client for interacting with Hatchet's logs API.

#### `metrics`

The metrics client is a client for reading metrics out of Hatchet's metrics API.

#### `rate_limits`

The rate limits client is a wrapper for Hatchet's gRPC API that makes it easier to work with rate limits in Hatchet.

#### `runs`

The runs client is a client for interacting with task and workflow runs within Hatchet.

#### `scheduled`

The scheduled client is a client for managing scheduled workflows within Hatchet.

#### `workers`

The workers client is a client for managing workers programmatically within Hatchet.

#### `workflows`

The workflows client is a client for managing workflows programmatically within Hatchet.

Note that workflows are the declaration, _not_ the individual runs. If you're looking for runs, use the `RunsClient` instead.

#### `tenant_id`

The tenant id you're operating in.

#### `namespace`

The current namespace you're interacting with.

### Functions

#### `worker`

Create a Hatchet worker on which to run workflows.

Parameters:

| Name            | Type                              | Description                                                                                                                                                | Default    |
| --------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `name`          | `str`                             | The name of the worker.                                                                                                                                    | _required_ |
| `slots`         | `int \| None`                     | Slot count for standard tasks.                                                                                                                             | `None`     |
| `durable_slots` | `int \| None`                     | Slot count for durable tasks.                                                                                                                              | `None`     |
| `labels`        | `dict[str, str \| int] \| None`   | A dictionary of labels to assign to the worker. For more details, view examples on affinity and worker labels.                                             | `None`     |
| `workflows`     | `list[BaseWorkflow[Any]] \| None` | A list of workflows to register on the worker, as a shorthand for calling `register_workflow` on each or `register_workflows` on all of them.              | `None`     |
| `lifespan`      | `LifespanFn \| None`              | A lifespan function to run on the worker. This function will be called when the worker is started, and can be used to perform any setup or teardown tasks. | `None`     |

Returns:

| Type     | Description                                                                                                    |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| `Worker` | The created `Worker` object, which exposes an instance method `start` which can be called to start the worker. |

Raises:

| Type        | Description                                                                                                                                                                                                                                                                                                             |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TypeError` | If any of the items in `workflows` is not an instance of `Workflow` or `Standalone`, which are the two types of workflow objects that can be passed to a worker. This is to catch a common mistake where users pass the result of a task declaration method like `Workflow.task` instead of the workflow object itself. |

#### `workflow`

Define a Hatchet workflow, which can then declare `task`s and be `run`, `schedule`d, etc.

Parameters:

| Name                          | Type                                                                  | Description                                                                                                                                                                                | Default          |
| ----------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- |
| `name`                        | `str`                                                                 | The name of the workflow.                                                                                                                                                                  | _required_       |
| `description`                 | `str \| None`                                                         | A description for the workflow                                                                                                                                                             | `None`           |
| `input_validator`             | `type[TWorkflowInput] \| None`                                        | A Pydantic model to use as a validator for the `input` to the tasks in the workflow. If no validator is provided, defaults to an `EmptyModel` under the hood.                              | `None`           |
| `on_events`                   | `list[str] \| None`                                                   | A list of event triggers for the workflow - events which cause the workflow to be run.                                                                                                     | `None`           |
| `on_crons`                    | `list[str] \| None`                                                   | A list of cron triggers for the workflow.                                                                                                                                                  | `None`           |
| `version`                     | `str \| None`                                                         | A version for the workflow                                                                                                                                                                 | `None`           |
| `sticky`                      | `StickyStrategy \| None`                                              | A sticky strategy for the workflow                                                                                                                                                         | `None`           |
| `default_priority`            | `int \| Priority`                                                     | The priority of the workflow. Higher values will cause this workflow to have priority in scheduling over other, lower priority ones.                                                       | `LOW`            |
| `concurrency`                 | `int \| ConcurrencyExpression \| list[ConcurrencyExpression] \| None` | A concurrency object controlling the concurrency settings for this workflow. If an integer is provided, it is treated as a constant concurrency limit with a `GROUP_ROUND_ROBIN` strategy. | `None`           |
| `task_defaults`               | `TaskDefaults`                                                        | A `TaskDefaults` object controlling the default task settings for this workflow.                                                                                                           | `TaskDefaults()` |
| `default_filters`             | `list[DefaultFilter] \| None`                                         | A list of filters to create with the workflow is created.                                                                                                                                  | `None`           |
| `default_additional_metadata` | `JSONSerializableMapping \| None`                                     | A dictionary of additional metadata to attach to each run of this workflow by default.                                                                                                     | `None`           |

Returns:

| Type                                               | Description                                                                                     |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `Workflow[EmptyModel] \| Workflow[TWorkflowInput]` | The created `Workflow` object, which can be used to declare tasks, run the workflow, and so on. |

#### `task`

A decorator to transform a function into a standalone 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`                  |
| `description`                 | `str \| None`                                                         | An optional description for the task.                                                                                                                                                  | `None`                  |
| `input_validator`             | `type[TWorkflowInput] \| None`                                        | A Pydantic model to use as a validator for the input to the task. If no validator is provided, defaults to an `EmptyModel`.                                                            | `None`                  |
| `on_events`                   | `list[str] \| None`                                                   | A list of event triggers for the task - events which cause the task to be run.                                                                                                         | `None`                  |
| `on_crons`                    | `list[str] \| None`                                                   | A list of cron triggers for the task.                                                                                                                                                  | `None`                  |
| `version`                     | `str \| None`                                                         | A version for the task.                                                                                                                                                                | `None`                  |
| `sticky`                      | `StickyStrategy \| None`                                              | A sticky strategy for the task.                                                                                                                                                        | `None`                  |
| `default_priority`            | `int \| Priority`                                                     | The priority of the task. Higher values will cause this task to have priority in scheduling.                                                                                           | `LOW`                   |
| `concurrency`                 | `int \| ConcurrencyExpression \| list[ConcurrencyExpression] \| None` | A concurrency object controlling the concurrency settings for this task. If an integer is provided, it is treated as a constant concurrency limit with a `GROUP_ROUND_ROBIN` strategy. | `None`                  |
| `schedule_timeout`            | `Duration`                                                            | The maximum time allowed for scheduling the task.                                                                                                                                      | `timedelta(minutes=5)`  |
| `execution_timeout`           | `Duration`                                                            | The maximum time allowed for executing the task.                                                                                                                                       | `timedelta(seconds=60)` |
| `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] \| list[DesiredWorkerLabel] \| None`   | A dictionary of desired worker labels that determine to which worker the task should be assigned.                                                                                      | `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`                  |
| `default_filters`             | `list[DefaultFilter] \| None`                                         | A list of filters to create with the task is created.                                                                                                                                  | `None`                  |
| `default_additional_metadata` | `JSONSerializableMapping \| None`                                     | A dictionary of additional metadata to attach to each run of this task by default.                                                                                                     | `None`                  |

Returns:

| Type                                                                                                                                                                                                                                 | Description                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| `Callable[[Callable[Concatenate[EmptyModel, Context, P], R \| CoroutineLike[R]]], Standalone[EmptyModel, R]] \| Callable[[Callable[Concatenate[TWorkflowInput, Context, P], R \| CoroutineLike[R]]], Standalone[TWorkflowInput, R]]` | A decorator which creates a `Standalone` task object. |

#### `durable_task`

A decorator to transform a function into a standalone Hatchet _durable_ 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`                                 |
| `description`                 | `str \| None`                                                         | An optional description for the task.                                                                                                                                                  | `None`                                 |
| `input_validator`             | `type[TWorkflowInput] \| None`                                        | A Pydantic model to use as a validator for the input to the task. If no validator is provided, defaults to an `EmptyModel`.                                                            | `None`                                 |
| `on_events`                   | `list[str] \| None`                                                   | A list of event triggers for the task - events which cause the task to be run.                                                                                                         | `None`                                 |
| `on_crons`                    | `list[str] \| None`                                                   | A list of cron triggers for the task.                                                                                                                                                  | `None`                                 |
| `version`                     | `str \| None`                                                         | A version for the task.                                                                                                                                                                | `None`                                 |
| `sticky`                      | `StickyStrategy \| None`                                              | A sticky strategy for the task.                                                                                                                                                        | `None`                                 |
| `default_priority`            | `int \| Priority`                                                     | The priority of the task. Higher values will cause this task to have priority in scheduling.                                                                                           | `LOW`                                  |
| `concurrency`                 | `int \| ConcurrencyExpression \| list[ConcurrencyExpression] \| None` | A concurrency object controlling the concurrency settings for this task. If an integer is provided, it is treated as a constant concurrency limit with a `GROUP_ROUND_ROBIN` strategy. | `None`                                 |
| `schedule_timeout`            | `Duration`                                                            | The maximum time allowed for scheduling the task.                                                                                                                                      | `timedelta(minutes=5)`                 |
| `execution_timeout`           | `Duration`                                                            | The maximum time allowed for executing the task.                                                                                                                                       | `timedelta(seconds=60)`                |
| `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] \| list[DesiredWorkerLabel] \| None`   | A dictionary of desired worker labels that determine to which worker the task should be assigned.                                                                                      | `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`                                 |
| `default_filters`             | `list[DefaultFilter] \| None`                                         | A list of filters to create with the task is created.                                                                                                                                  | `None`                                 |
| `default_additional_metadata` | `JSONSerializableMapping \| None`                                     | A dictionary of additional metadata to attach to each run of this task by default.                                                                                                     | `None`                                 |
| `eviction_policy`             | `EvictionPolicy \| None`                                              | An optional eviction policy controlling when idle durable tasks are evicted from workers.                                                                                              | `DEFAULT_DURABLE_TASK_EVICTION_POLICY` |

Returns:

| Type                                                                                                                                                                                                                                               | Description                                           |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `Callable[[Callable[Concatenate[EmptyModel, DurableContext, P], R \| CoroutineLike[R]]], Standalone[EmptyModel, R]] \| Callable[[Callable[Concatenate[TWorkflowInput, DurableContext, P], R \| CoroutineLike[R]]], Standalone[TWorkflowInput, R]]` | A decorator which creates a `Standalone` task object. |
