### Install PyZeebe

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/index.rst.txt

Install the PyZeebe library using pip. Ensure you have Python 3.10+.

```bash
$
pip install pyzeebe
```

--------------------------------

### Example Logging Decorator

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/decorators.rst.txt

Illustrates a synchronous and an asynchronous logging decorator that processes a Job instance.

```python
def logging_decorator(job: Job) -> Job:
    logging.info(job)
    return job
```

```python
async def logging_decorator(job: Job) -> Job:
    await async_logger.info(job)
    return job
```

--------------------------------

### Create a Zeebe Client

Source: https://camunda-community-hub.github.io/pyzeebe/index.html

Initialize a Zeebe client to interact with the Zeebe engine. This example shows how to run a process, with and without variables.

```python
from pyzeebe import ZeebeClient, create_insecure_channel

channel = create_insecure_channel()
client = ZeebeClient(channel)

await client.run_process("my_process")

# Run process with variables:
await client.run_process("my_process", variables={"x": 0})

```

--------------------------------

### Create a Zeebe Client

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/index.rst.txt

Initialize a Zeebe client to interact with the Zeebe engine. Use this to start processes with or without variables.

```python
from pyzeebe import ZeebeClient, create_insecure_channel

channel = create_insecure_channel()
client = ZeebeClient(channel)

await client.run_process("my_process")

# Run process with variables:
await client.run_process("my_process", variables={"x": 0})
```

--------------------------------

### CreateProcessInstanceResponse

Source: https://camunda-community-hub.github.io/pyzeebe/client_reference.html

Runs a process and creates a process instance. This method starts a new instance of a specified BPMN process.

```APIDOC
## run_process

### Description
Runs a process and creates a process instance. This method starts a new instance of a specified BPMN process.

### Method
POST (conceptual, as this is an SDK method)

### Endpoint
(Not directly applicable for SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **bpmn_process_id** (str) - The unique process id of the process.
- **variables** (dict) - A dictionary containing all the starting variables the process needs. Must be JSONable.
- **version** (int) - The version of the process. Default: -1 (latest)
- **tenant_id** (str) - The tenant ID of the process definition. New in Zeebe 8.3.

### Request Example
```json
{
  "bpmn_process_id": "order-process",
  "variables": {
    "orderId": "12345",
    "customer": "John Doe"
  },
  "version": 1,
  "tenant_id": "tenant-a"
}
```

### Response
#### Success Response (200)
- **CreateProcessInstanceResponse** - response from Zeebe.

#### Response Example
(Response structure not provided in source)

ERROR HANDLING:
- **ProcessDefinitionNotFoundError** – No process with bpmn_process_id exists
- **InvalidJSONError** – variables is not JSONable
- **ProcessDefinitionHasNoStartEventError** – The specified process does not have a start event
- **ZeebeBackPressureError** – If Zeebe is currently in back pressure (too many requests)
- **ZeebeGatewayUnavailableError** – If the Zeebe gateway is unavailable
- **ZeebeInternalError** – If Zeebe experiences an internal error
- **UnknownGrpcStatusCodeError** – If Zeebe returns an unexpected status code
```

--------------------------------

### Create a Basic Task

Source: https://camunda-community-hub.github.io/pyzeebe/worker_tasks.html

Defines a simple task that performs no action and returns an empty dictionary. This serves as a foundational example for task creation.

```python
from pyzeebe import worker

@worker.task(task_type="my_task")
async def my_task():
    return {}

```

--------------------------------

### CreateProcessInstanceWithResultResponse

Source: https://camunda-community-hub.github.io/pyzeebe/client_reference.html

Runs a process and waits for its result. This method starts a new process instance and returns its result upon completion.

```APIDOC
## run_process_with_result

### Description
Runs a process and waits for its result. This method starts a new process instance and returns its result upon completion.

### Method
POST (conceptual, as this is an SDK method)

### Endpoint
(Not directly applicable for SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **bpmn_process_id** (str) - The unique process id of the process.
- **variables** (dict) - A dictionary containing all the starting variables the process needs. Must be JSONable.
- **version** (int) - The version of the process. Default: -1 (latest)
- **timeout** (int) - How long to wait until a timeout occurs. Default: 0 (Zeebe default timeout)
- **variables_to_fetch** (list[str]) - Which variables to get from the finished process
- **tenant_id** (str) - The tenant ID of the process definition. New in Zeebe 8.3.

### Request Example
```json
{
  "bpmn_process_id": "order-process",
  "variables": {
    "orderId": "12345",
    "customer": "John Doe"
  },
  "version": 1,
  "timeout": 5000,
  "variables_to_fetch": ["orderStatus", "totalAmount"],
  "tenant_id": "tenant-a"
}
```

### Response
#### Success Response (200)
- **CreateProcessInstanceWithResultResponse** - response from Zeebe.

#### Response Example
(Response structure not provided in source)

ERROR HANDLING:
- **ProcessDefinitionNotFoundError** – No process with bpmn_process_id exists
- **InvalidJSONError** – variables is not JSONable
- **ProcessDefinitionHasNoStartEventError** – The specified process does not have a start event
- **ProcessTimeoutError** – The process was not finished within the set timeout
- **ZeebeBackPressureError** – If Zeebe is currently in back pressure (too many requests)
- **ZeebeGatewayUnavailableError** – If the Zeebe gateway is unavailable
- **ZeebeInternalError** – If Zeebe experiences an internal error
- **UnknownGrpcStatusCodeError** – If Zeebe returns an unexpected status code
```

--------------------------------

### Create a Zeebe Worker

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/index.rst.txt

Set up a Zeebe worker to process tasks. This example defines a task 'my_task' that increments an integer.

```python
from pyzeebe import ZeebeWorker, create_insecure_channel

channel = create_insecure_channel()
worker = ZeebeWorker(channel)

@worker.task(task_type="my_task")
async def my_task(x: int):
   return {"y": x + 1}

await worker.work()
```

--------------------------------

### run_process

Source: https://camunda-community-hub.github.io/pyzeebe/client_reference.html

Starts a process instance. This method is used to initiate a new workflow based on a BPMN process ID.

```APIDOC
## run_process

### Description
Starts a process instance.

### Method
run_process

### Parameters
#### Path Parameters
- **_bpmn_process_id** (str) - Required - The BPMN process ID to start.
- **_variables** (Variables | None) - Optional - A dictionary of variables to pass to the process instance.
- **_version** (int) - Optional - The version of the process to start. Defaults to -1 (latest).
- **_tenant_id** (str | None) - Optional - The tenant ID for the process instance.

### Returns
- **CreateProcessInstanceResponse** - The response from Zeebe.

### Raises
- **MessageAlreadyExistsError** - If a message with message_id already exists.
- **ZeebeBackPressureError** - If Zeebe is currently in back pressure (too many requests).
- **ZeebeGatewayUnavailableError** - If the Zeebe gateway is unavailable.
- **ZeebeInternalError** - If Zeebe experiences an internal error.
- **UnknownGrpcStatusCodeError** - If Zeebe returns an unexpected status code.
```

--------------------------------

### Create a Zeebe Worker

Source: https://camunda-community-hub.github.io/pyzeebe/index.html

Set up a Zeebe worker to process tasks. This example defines a task handler for 'my_task' that increments an integer.

```python
from pyzeebe import ZeebeWorker, create_insecure_channel

channel = create_insecure_channel()
worker = ZeebeWorker(channel)

@worker.task(task_type="my_task")
async def my_task(x: int):
   return {"y": x + 1}

await worker.work()

```

--------------------------------

### run_process_with_result

Source: https://camunda-community-hub.github.io/pyzeebe/client_reference.html

Starts a process instance and waits for its completion, returning the result. This is useful for synchronous process execution.

```APIDOC
## run_process_with_result

### Description
Starts a process instance and waits for its completion, returning the result.

### Method
run_process_with_result

### Parameters
#### Path Parameters
- **_bpmn_process_id** (str) - Required - The BPMN process ID to start.
- **_variables** (Variables | None) - Optional - A dictionary of variables to pass to the process instance.
- **_version** (int) - Optional - The version of the process to start. Defaults to -1 (latest).
- **_timeout** (int) - Optional - The timeout in milliseconds to wait for the process to complete. Defaults to 0 (no timeout).
- **_variables_to_fetch** (list[str] | None) - Optional - A list of variables to fetch from the process instance.
- **_tenant_id** (str | None) - Optional - The tenant ID for the process instance.

### Returns
- **CreateProcessInstanceWithResultResponse** - The response from Zeebe, including process variables.

### Raises
- **MessageAlreadyExistsError** - If a message with message_id already exists.
- **ZeebeBackPressureError** - If Zeebe is currently in back pressure (too many requests).
- **ZeebeGatewayUnavailableError** - If the Zeebe gateway is unavailable.
- **ZeebeInternalError** - If Zeebe experiences an internal error.
- **UnknownGrpcStatusCodeError** - If Zeebe returns an unexpected status code.
```

--------------------------------

### Create and Start a Worker with Event Loop

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/worker_quickstart.rst.txt

This snippet demonstrates how to create and run a Zeebe worker using Python's asyncio event loop. It's crucial for managing asynchronous operations within the worker.

```python
import asyncio

from pyzeebe import ZeebeWorker, create_insecure_channel

channel = create_insecure_channel()
worker = ZeebeWorker(channel)


@worker.task(task_type="my_task")
async def my_task(x: int):
    return {"y": x + 1}

loop = asyncio.get_event_loop()
loop.run_until_complete(worker.work())
```

--------------------------------

### ZeebeWorker Methods

Source: https://camunda-community-hub.github.io/pyzeebe/worker_reference.html

Provides methods for interacting with the Zeebe worker, including checking its health, adding task routers, stopping the worker, and starting the main work loop.

```APIDOC
## ZeebeWorker Methods

### `healthcheck()`

#### Description
Ping Zeebe Gateway using GRPC Health Checking Protocol.

### `include_router(*routers: ZeebeTaskRouter)`

#### Description
Adds all router’s tasks to the worker.

#### Raises
* **DuplicateTaskTypeError** – If a task from the router already exists in the worker

### `stop()`

#### Description
Stop the worker. This will emit a signal asking tasks to complete the current task and stop polling for new.

### `work()`

#### Description
Start the worker. The worker will poll zeebe for jobs of each task in a different asyncio task.

#### Raises
* **ActivateJobsRequestInvalidError** – If one of the worker’s task has invalid types
* **ZeebeBackPressureError** – If Zeebe is currently in back pressure (too many requests)
* **ZeebeGatewayUnavailableError** – If the Zeebe gateway is unavailable
* **ZeebeInternalError** – If Zeebe experiences an internal error
* **UnknownGrpcStatusCodeError** – If Zeebe returns an unexpected status code
```

--------------------------------

### Create a ZeebeTaskRouter Instance

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/worker_taskrouter.rst.txt

Instantiate the ZeebeTaskRouter to begin organizing your tasks. This router will manage task definitions.

```python
from pyzeebe import ZeebeTaskRouter

router = ZeebeTaskRouter()
```

--------------------------------

### Deploy a Zeebe Process Resource

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/client_quickstart.rst.txt

Deploy a BPMN process file to the Zeebe cluster. Ensure the file path is correct.

```python
await client.deploy_resource("process_file.bpmn")
```

--------------------------------

### Run a Zeebe Process Instance

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/client_quickstart.rst.txt

Execute a Zeebe process by its BPMN process ID. This snippet shows how to initiate a process instance.

```python
process_instance_key = await client.run_process("bpmn_process_id")
```

--------------------------------

### Applying Decorators to a TaskRouter

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/decorators.rst.txt

Demonstrates how to register decorators globally for all tasks within a ZeebeTaskRouter using 'before' and 'after' methods.

```python
from pyzeebe import ZeebeTaskRouter, Job

router = ZeebeTaskRouter()

def my_decorator(job: Job) -> Job:
    print(job)
    return job


router.before(my_decorator)
router.after(my_decorator)
```

--------------------------------

### create_process_instance

Source: https://camunda-community-hub.github.io/pyzeebe/zeebe_adapter_reference.html

Asynchronously creates a new process instance for a given BPMN process ID and version, with optional variables and tenant ID.

```APIDOC
## create_process_instance

### Description
Creates a new process instance based on a BPMN process ID and version.

### Method
async

### Parameters
- **_bpmn_process_id** (str) - The ID of the BPMN process to instantiate.
- **_version** (int) - The version of the BPMN process.
- **_variables** (Variables) - A dictionary of initial variables for the process instance.
- **_tenant_id** (str | None) - Optional. The tenant ID to associate with the process instance.
```

--------------------------------

### Create a Basic Task

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/worker_tasks.rst.txt

Defines a simple task with a specific task type. This task returns an empty dictionary, which is not sent back to Zeebe.

```python
    @worker.task(task_type="my_task")
    async def my_task():
        return {}

```

--------------------------------

### Worker Startup Workaround with asyncio.run

Source: https://camunda-community-hub.github.io/pyzeebe/worker_quickstart.html

A workaround for issues when using `asyncio.run` directly with a worker. This approach ensures a new event loop is not created, preventing conflicts.

```python
async def main():
    channel = create_insecure_channel()
    worker = ZeebeWorker(channel)
    await worker.work()

asyncio.run(main())

```

--------------------------------

### ZeebeClient Methods

Source: https://camunda-community-hub.github.io/pyzeebe/client.html

Reference for the asynchronous `ZeebeClient` methods available for interacting with Zeebe.

```APIDOC
## ZeebeClient Methods

### Description
Provides access to asynchronous operations for interacting with the Zeebe cluster.

### Methods
- `__init__()`: Initializes the `ZeebeClient`.
- `broadcast_signal()`: Broadcasts a signal to the Zeebe cluster.
- `cancel_process_instance()`: Cancels a running process instance.
- `deploy_resource()`: Deploys a process or decision resource.
- `evaluate_decision()`: Evaluates a decision in the Zeebe cluster.
- `healthcheck()`: Checks the health status of the Zeebe cluster.
- `publish_message()`: Publishes a message to the Zeebe cluster.
- `run_process()`: Starts a new process instance.
- `run_process_with_result()`: Starts a new process instance and waits for its completion.
- `topology()`: Retrieves the topology of the Zeebe cluster.
```

--------------------------------

### CreateProcessInstanceWithResultResponse

Source: https://camunda-community-hub.github.io/pyzeebe/zeebe_adapter_reference.html

Represents the response from creating a process instance with results.

```APIDOC
## CreateProcessInstanceWithResultResponse

### Description
This object is returned when a process instance is created and its results are retrieved.

### Fields
- **process_definition_key** (int) - The key of the process definition used.
- **bpmn_process_id** (str) - The BPMN process ID of the process definition.
- **version** (int) - The version of the process definition.
- **process_instance_key** (int) - The unique identifier for the created process instance.
- **variables** (Variables) - All visible variables to the root scope.
- **tenant_id** (str | None) - The tenant ID associated with the process instance.
```

--------------------------------

### ZeebeAdapter Constructor

Source: https://camunda-community-hub.github.io/pyzeebe/zeebe_adapter_reference.html

Initializes the ZeebeAdapter with a gRPC channel and an optional maximum number of connection retries.

```APIDOC
## __init__

### Description
Initializes the ZeebeAdapter.

### Parameters
- **_grpc_channel** (Channel) - The gRPC channel to use for communication.
- **_max_connection_retries** (int) - Optional. The maximum number of retries for establishing a connection. Defaults to -1 (infinite retries).
```

--------------------------------

### Run a Zeebe Process with Result

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/client_quickstart.rst.txt

Execute a Zeebe process and retrieve its result directly. The result is returned as a dictionary.

```python
process_instance_key, result = await client.run_process_with_result("bpmn_process_id")

    # result will be a dict
```

--------------------------------

### Run a Zeebe Process with Result

Source: https://camunda-community-hub.github.io/pyzeebe/client_quickstart.html

Execute a Zeebe process and retrieve its result directly. The result is returned as a dictionary.

```python
process_instance_key, result = await client.run_process_with_result("bpmn_process_id")

# result will be a dict
```

--------------------------------

### Create a Zeebe Client

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/client_quickstart.rst.txt

Instantiate a Zeebe client with default channel configuration. You can customize connection retry behavior by setting `max_connection_retries`. The default is 10 retries; set to -1 for infinite retries.

```python
from pyzeebe import ZeebeClient, create_insecure_channel

channel = create_insecure_channel()  # Will use ZEEBE_ADDRESS environment variable or localhost:26500
client = ZeebeClient(channel)
```

```python
client = ZeebeClient(grpc_channel, max_connection_retries=1)  # Will only accept one failure and disconnect upon the second
```

--------------------------------

### SyncZeebeClient Methods

Source: https://camunda-community-hub.github.io/pyzeebe/client_reference.html

Methods available on the synchronous SyncZeebeClient for interacting with the Zeebe cluster.

```APIDOC
## SyncZeebeClient

### Description
Provides a synchronous interface to interact with the Zeebe cluster.

### Methods

- `__init__()`
- `broadcast_signal()`
- `cancel_process_instance()`
- `deploy_resource()`
- `evaluate_decision()`
- `healthcheck()`
- `publish_message()`
- `run_process()`
- `run_process_with_result()`
- `topology()`
```

--------------------------------

### create_process_instance_with_result

Source: https://camunda-community-hub.github.io/pyzeebe/zeebe_adapter_reference.html

Asynchronously creates a process instance and waits for its completion, returning the result. Includes options for timeout and variables to fetch.

```APIDOC
## create_process_instance_with_result

### Description
Creates a process instance and waits for its completion, returning the final state or result.

### Method
async

### Parameters
- **_bpmn_process_id** (str) - The ID of the BPMN process to instantiate.
- **_version** (int) - The version of the BPMN process.
- **_variables** (Variables) - A dictionary of initial variables for the process instance.
- **_timeout** (int) - The timeout in milliseconds for waiting for the process instance to complete.
- **_variables_to_fetch** (Iterable[str]) - A list of variable names to fetch upon completion.
- **_tenant_id** (str | None) - Optional. The tenant ID to associate with the process instance.
```

--------------------------------

### deploy_resource

Source: https://camunda-community-hub.github.io/pyzeebe/client_reference.html

Deploy one or more processes, DMN decisions, or forms to Zeebe.

```APIDOC
## deploy_resource (*resource_file_path, tenant_id=None)

### Description
Deploy one or more processes.

### Method
`deploy_resource`

### Parameters
#### Path Parameters
- **resource_file_path** (str) - Required - The file path to a resource definition file (bpmn/dmn/form)
- **tenant_id** (str | None) - Optional - The tenant ID of the resources to deploy. New in Zeebe 8.3.

### Raises
- **ProcessInvalidError** – If one of the process file definitions is invalid
- **ZeebeBackPressureError** – If Zeebe is currently in back pressure (too many requests)
- **ZeebeGatewayUnavailableError** – If the Zeebe gateway is unavailable
- **ZeebeInternalError** – If Zeebe experiences an internal error
- **UnknownGrpcStatusCodeError** – If Zeebe returns an unexpected status code
```

--------------------------------

### ZeebeClient (Async)

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/client_reference.rst.txt

The asynchronous ZeebeClient provides methods for interacting with the Zeebe cluster using async/await syntax. It exposes various operations for workflow management, job handling, and cluster interaction.

```APIDOC
## Class: pyzeebe.ZeebeClient

### Description
Represents the asynchronous client for interacting with the Zeebe cluster.

### Methods
This class exposes numerous methods for interacting with Zeebe. Refer to the `pyzeebe` documentation for a complete list and detailed explanations of each method, including parameters and return values.
```

--------------------------------

### Equivalent Task Returning a Dictionary

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/worker_tasks.rst.txt

Demonstrates the equivalent of a single-value return task, explicitly returning a dictionary with the specified variable name.

```python
    @worker.task(task_type="my_task")
    def my_task(x: int) -> dict:
        return {"y": x + 1}

```

--------------------------------

### ZeebeAdapter Methods

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/zeebe_adapter_reference.rst.txt

This section lists the public methods available in the ZeebeAdapter class, which are directly callable by users.

```APIDOC
## ZeebeAdapter

This class provides the interface for interacting with Zeebe.

### Methods

- **__init__**
- **create_process_instance**
- **create_process_instance_with_result**
- **cancel_process_instance**
- **deploy_resource**
- **evaluate_decision**
- **broadcast_signal**
- **publish_message**
- **complete_job**
- **fail_job**
- **throw_error**
- **topology**
- **health_check**
```

--------------------------------

### deploy_resource

Source: https://camunda-community-hub.github.io/pyzeebe/client_reference.html

Deploys one or more process, DMN, or form resources to the Zeebe cluster.

```APIDOC
## deploy_resource

### Description
Deploy one or more processes.
New in Zeebe 8.0.

### Method
`async deploy_resource(*resource_file_path: str | PathLike[str], tenant_id: str | None = None)`

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* **resource_file_path** (str) - Required - The file path to a resource definition file (bpmn/dmn/form)
* **tenant_id** (str) - Optional - The tenant ID of the resources to deploy. New in Zeebe 8.3.

### Request Example
```python
await zeebe_client.deploy_resource(resource_file_path="path/to/process.bpmn")
```

### Response
#### Success Response
- **DeployResourceResponse** - response from Zeebe.

#### Response Example
```json
{
  "key": 1234567890,
  "processes": [
    {
      "bpmnProcessId": "process-id",
      "version": 1,
      "resourceName": "process.bpmn"
    }
  ]
}
```

### Errors
* **ProcessInvalidError**: If one of the process file definitions is invalid
* **ZeebeBackPressureError**: If Zeebe is currently in back pressure (too many requests)
* **ZeebeGatewayUnavailableError**: If the Zeebe gateway is unavailable
* **ZeebeInternalError**: If Zeebe experiences an internal error
* **UnknownGrpcStatusCodeError**: If Zeebe returns an unexpected status code
```

--------------------------------

### CreateProcessInstanceResponse

Source: https://camunda-community-hub.github.io/pyzeebe/zeebe_adapter_reference.html

Represents the response from creating a process instance.

```APIDOC
## CreateProcessInstanceResponse

### Description
This object is returned when a process instance is successfully created.

### Fields
- **process_definition_key** (int) - The key of the process definition used.
- **bpmn_process_id** (str) - The BPMN process ID of the process definition.
- **version** (int) - The version of the process definition.
- **process_instance_key** (int) - The unique identifier for the created process instance.
- **tenant_id** (str | None) - The tenant ID associated with the process instance.
```

--------------------------------

### pyzeebe.create_camunda_cloud_channel

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/channels_reference.rst.txt

Creates a secure gRPC channel for connecting to Camunda Cloud.

```APIDOC
## create_camunda_cloud_channel

### Description
Creates a secure gRPC channel for connecting to Camunda Cloud.

### Function Signature
`pyzeebe.create_camunda_cloud_channel(client_id: str, client_secret: str, cluster_id: str, cluster_region: str)`

### Parameters
#### Path Parameters
- **client_id** (str) - The Camunda Cloud client ID.
- **client_secret** (str) - The Camunda Cloud client secret.
- **cluster_id** (str) - The Camunda Cloud cluster ID.
- **cluster_region** (str) - The Camunda Cloud cluster region.

### Returns
A gRPC channel object.
```

--------------------------------

### create_camunda_cloud_channel()

Source: https://camunda-community-hub.github.io/pyzeebe/channels.html

Creates a channel specifically for connecting to Camunda Cloud (SaaS) using OAuth2 client credentials. This simplifies connection to the managed Zeebe service.

```APIDOC
## create_camunda_cloud_channel()

### Description
Creates a channel for connecting to Camunda Cloud (SaaS) using OAuth2 client credentials.

### Method
`create_camunda_cloud_channel()`

### Parameters
- **client_id** (str) - Required - Your Camunda Cloud client ID.
- **client_secret** (str) - Required - Your Camunda Cloud client secret.
- **cluster_id** (str) - Required - Your Camunda Cloud cluster ID.
- **cluster_region** (str) - Required - The region of your Camunda Cloud cluster (e.g., 'eu-frankfurt-1').

### Request Example
```python
from pyzeebe.channel import create_camunda_cloud_channel

channel = create_camunda_cloud_channel(client_id='your-client-id', client_secret='your-client-secret', cluster_id='your-cluster-id', cluster_region='eu-frankfurt-1')
```

### Response
Returns a channel object configured for Camunda Cloud.
```

--------------------------------

### DeployResourceResponse

Source: https://camunda-community-hub.github.io/pyzeebe/zeebe_adapter_reference.html

Represents the response from deploying resources.

```APIDOC
## DeployResourceResponse

### Description
This object is returned after successfully deploying resources to Zeebe.

### Fields
- **key** (int) - The key of the deployment.
- **deployments** (list[ProcessMetadata | DecisionMetadata | DecisionRequirementsMetadata | FormMetadata]) - A list of metadata for the deployed items.
- **tenant_id** (str | None) - The tenant ID associated with the deployment.
```

--------------------------------

### Create OAuth2 Channel with Custom Options

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/channels_quickstart.rst.txt

Configure an OAuth2 client credentials channel with custom gRPC channel options. This allows fine-tuning of connection parameters like keep-alive intervals or port reuse.

```python
import grpc
from pyzeebe import create_oauth2_client_credentials_channel
from pyzeebe.types import ChannelArgumentType

channel_options: ChannelArgumentType  = (("grpc.so_reuseport", 0),)

channel = create_oauth2_client_credentials_channel(
    grpc_address=ZEEBE_ADDRESS,
    client_id=ZEEBE_CLIENT_ID,
    client_secret=ZEEBE_CLIENT_SECRET,
    authorization_server=ZEEBE_AUTHORIZATION_SERVER_URL,
    scope="profile email",
    audience="zeebe-api",
    channel_options=channel_options,
)
```

--------------------------------

### Create Camunda Cloud Channel

Source: https://camunda-community-hub.github.io/pyzeebe/channels_configuration.html

Connects to Camunda Cloud using specific variables. Requires CAMUNDA_CLUSTER_ID, CAMUNDA_CLUSTER_REGION, CAMUNDA_CLIENT_ID, CAMUNDA_CLIENT_SECRET, and CAMUNDA_OAUTH_URL.

```python
pyzeebe.create_camunda_cloud_channel()
```

--------------------------------

### Create OAuth2 Client Credentials Channel

Source: https://camunda-community-hub.github.io/pyzeebe/channels_configuration.html

Establishes a channel using OAuth2 client credentials. Requires CAMUNDA_CLIENT_ID, CAMUNDA_CLIENT_SECRET, and CAMUNDA_OAUTH_URL (or their ZEEBE_ equivalents).

```python
pyzeebe.create_oauth2_client_credentials_channel()
```

--------------------------------

### Partition

Source: https://camunda-community-hub.github.io/pyzeebe/zeebe_adapter_reference.html

Information about a partition on a broker.

```APIDOC
## Partition

### Description
Information about a partition on a broker.

### Fields
- **partition_id** (int) - the unique ID of this partition
- **role** (PartitionBrokerRole) - the role of the broker for this partition
- **health** (PartitionBrokerHealth) - the health of this partition
```

--------------------------------

### SyncZeebeClient (Sync)

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/client_reference.rst.txt

The synchronous ZeebeClient provides methods for interacting with the Zeebe cluster using standard blocking calls. It offers the same core functionality as the asynchronous client but in a synchronous manner.

```APIDOC
## Class: pyzeebe.SyncZeebeClient

### Description
Represents the synchronous client for interacting with the Zeebe cluster.

### Methods
This class exposes numerous methods for interacting with Zeebe. Refer to the `pyzeebe` documentation for a complete list and detailed explanations of each method, including parameters and return values.
```

--------------------------------

### pyzeebe.create_oauth2_client_credentials_channel

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/channels_reference.rst.txt

Creates a secure gRPC channel using OAuth2 client credentials for authentication.

```APIDOC
## create_oauth2_client_credentials_channel

### Description
Creates a secure gRPC channel using OAuth2 client credentials for authentication.

### Function Signature
`pyzeebe.create_oauth2_client_credentials_channel(host: str, port: int, client_id: str, client_secret: str, audience: str)`

### Parameters
#### Path Parameters
- **host** (str) - The hostname of the Zeebe gateway.
- **port** (int) - The port of the Zeebe gateway.
- **client_id** (str) - The OAuth2 client ID.
- **client_secret** (str) - The OAuth2 client secret.
- **audience** (str) - The OAuth2 audience.

### Returns
A gRPC channel object.
```

--------------------------------

### Channel Configuration

Source: https://camunda-community-hub.github.io/pyzeebe/channels_reference.html

This section outlines the parameters used to configure a gRPC channel for connecting to Camunda Cloud. These parameters allow customization of region, authentication, credentials, and other channel-specific options.

```APIDOC
## Channels

This function configures and returns a gRPC channel for connecting to Camunda Cloud.

### Parameters

*   **region** (_str_, optional): The region of the cluster. Defaults to the value from the `CAMUNDA_CLUSTER_REGION` environment variable or 'bru-2'.
*   **authorization_server** (_str_, optional): The authorization server issuing access tokens. Defaults to the value from `CAMUNDA_OAUTH_URL` or `ZEEBE_AUTHORIZATION_SERVER_URL` environment variable or 'https://login.cloud.camunda.io/oauth/token'.
*   **scope** (_str_ | None, optional): The scope of the access request.
*   **audience** (_str_ | None, optional): The audience for authentication. Defaults to the value from `CAMUNDA_TOKEN_AUDIENCE` or `ZEEBE_TOKEN_AUDIENCE` environment variable or 'zeebe.camunda.io'.
*   **channel_credentials** (_grpc.ChannelCredentials_ | None): The gRPC channel credentials. Defaults to `grpc.ssl_channel_credentials`.
*   **channel_options** (_ChannelArgumentType_ | None): Additional options for the gRPC channel. Defaults to None. See https://grpc.github.io/grpc/python/glossary.html#term-channel_arguments
*   **leeway** (_int_): The number of seconds to consider the token as expired before the actual expiration time. Defaults to 60.
*   **expire_in** (_int_ | None): The number of seconds the token is valid for. Defaults to None. Should only be used if the token does not contain an "expires_in" attribute.

### Returns

The gRPC channel for connecting to Camunda Cloud.

### Return Type

grpc.aio.Channel
```

--------------------------------

### activate_jobs

Source: https://camunda-community-hub.github.io/pyzeebe/zeebe_adapter_reference.html

Asynchronously activates a list of jobs for a given task type and worker, with options for timeout, maximum jobs to activate, variables to fetch, and tenant IDs.

```APIDOC
## activate_jobs

### Description
Asynchronously activates jobs for a specified task type and worker.

### Method
async

### Parameters
- **_task_type** (str) - The type of tasks to activate.
- **_worker** (str) - The identifier of the worker requesting the jobs.
- **_timeout** (int) - The timeout in milliseconds for completing the activated jobs.
- **_max_jobs_to_activate** (int) - The maximum number of jobs to activate in this call.
- **_variables_to_fetch** (Iterable[str]) - A list of variable names to fetch with the jobs.
- **_request_timeout** (int) - The timeout for the request itself in milliseconds.
- **_tenant_ids** (Iterable[str] | None) - Optional. A list of tenant IDs to filter jobs by.
```

--------------------------------

### ZeebeWorker Initialization

Source: https://camunda-community-hub.github.io/pyzeebe/worker_reference.html

Initializes a ZeebeWorker to connect to a Zeebe gateway and perform tasks. It accepts various parameters for configuration, including connection details, task decorators, exception handling, and streaming options.

```APIDOC
## ZeebeWorker

### Description
A zeebe worker that can connect to a zeebe instance and perform tasks.

### Parameters

#### `grpc_channel` (_grpc.aio.Channel_)
GRPC Channel connected to a Zeebe gateway

#### `name` (_str_)
Name of zeebe worker

#### `request_timeout` (_int_)
Longpolling timeout for getting tasks from zeebe. If 0 default value is used

#### `before` (_list_ _[__TaskDecorator_ _]_)
Decorators to be performed before each task

#### `after` (_list_ _[__TaskDecorator_ _]_)
Decorators to be performed after each task

#### `exception_handler` (_ExceptionHandler_)
Handler that will be called when a job fails.

#### `max_connection_retries` (_int_)
Amount of connection retries before worker gives up on connecting to zeebe. To setup with infinite retries use -1

#### `poll_retry_delay` (_int_)
The number of seconds to wait before attempting to poll again when reaching max amount of running jobs

#### `tenant_ids` (_list_ _[__str_ _]_)
A list of tenant IDs for which to activate jobs. New in Zeebe 8.3.

#### `stream_enabled` (_bool_)
Enables the job worker to stream jobs. It will still poll for older jobs, but streaming is favored. New in Zeebe 8.4.

#### `stream_request_timeout` (_int_)
If streaming is enabled, this sets the timeout on the underlying job stream. It’s useful to set a few hours to load-balance your streams over time. New in Zeebe 8.4.
```

--------------------------------

### ProcessMetadata

Source: https://camunda-community-hub.github.io/pyzeebe/zeebe_adapter_reference.html

Metadata for a deployed process.

```APIDOC
## ProcessMetadata

### Description
Contains metadata for a process that has been deployed.

### Fields
- **bpmn_process_id** (str) - The BPMN process ID.
- **version** (int) - The deployed version of the process.
- **process_definition_key** (int) - The unique key identifying this process definition.
- **resource_name** (str) - The name of the resource file from which the process was parsed.
- **tenant_id** (str | None) - The tenant ID of the deployed process.
```

--------------------------------

### Applying Decorators to a Worker

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/decorators.rst.txt

Illustrates how to add decorators to a ZeebeWorker, which will then apply to all tasks managed by that worker.

```python
from pyzeebe import ZeebeWorker, Job

worker = ZeebeWorker()

def my_decorator(job: Job) -> Job:
    print(job)
    return job


worker.before(my_decorator)
worker.after(my_decorator)
```

--------------------------------

### create_oauth2_client_credentials_channel()

Source: https://camunda-community-hub.github.io/pyzeebe/channels.html

Creates a channel to a Zeebe gateway using OAuth2 client credentials. This is commonly used for service-to-service authentication.

```APIDOC
## create_oauth2_client_credentials_channel()

### Description
Creates a channel to a Zeebe gateway using OAuth2 client credentials flow.

### Method
`create_oauth2_client_credentials_channel()`

### Parameters
- **client_id** (str) - Required - The OAuth2 client ID.
- **client_secret** (str) - Required - The OAuth2 client secret.
- **authorization_url** (str) - Required - The URL for obtaining OAuth2 tokens.
- **audience** (str) - Optional - The intended audience for the token.
- **ca_cert** (str) - Optional - Path to the Certificate Authority certificate file for the authorization server.

### Request Example
```python
from pyzeebe.channel import create_oauth2_client_credentials_channel

channel = create_oauth2_client_credentials_channel(client_id='your-client-id', client_secret='your-client-secret', authorization_url='https://login.example.com/oauth/token', audience='zeebe.example.com')
```

### Response
Returns a channel object authenticated via OAuth2 client credentials.
```

--------------------------------

### Workaround for asyncio.run with Zeebe Worker

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/worker_quickstart.rst.txt

This workaround addresses issues when using `asyncio.run` directly with a Zeebe worker that uses an async gRPC channel. It ensures a new event loop is correctly managed.

```python
async def main():
    channel = create_insecure_channel()
    worker = ZeebeWorker(channel)
    await worker.work()

asyncio.run(main())
```

--------------------------------

### Create Secure Channel

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/channels_quickstart.rst.txt

Create a gRPC channel with a secure connection to a Zeebe Gateway using TLS. You must provide valid channel credentials, typically obtained using grpc.ssl_channel_credentials.

```python
import grpc
from pyzeebe import create_secure_channel


credentials = grpc.ssl_channel_credentials(root_certificates="<root_certificate>", private_key="<private_key>")
channel = create_secure_channel(grpc_address="host:port", channel_credentials=credentials)
```

--------------------------------

### Applying Decorator to a Task

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/decorators.rst.txt

Shows how to add a decorator to a specific task using the 'before' and 'after' arguments in the task decorator.

```python
from pyzeebe import Job


def my_decorator(job: Job) -> Job:
    print(job)
    return job


@worker.task(task_type="my_task", before=[my_decorator], after=[my_decorator])
def my_task():
    return {}
```

--------------------------------

### ZeebeTaskRouter Class Reference

Source: https://camunda-community-hub.github.io/pyzeebe/worker.html

Reference for the ZeebeTaskRouter class, used for organizing and routing tasks to workers.

```APIDOC
## ZeebeTaskRouter

### Description
Manages the routing of tasks to specific handlers within a worker.

### Methods
- `__init__()`: Initializes the ZeebeTaskRouter.
- `after(task_decorator)`: Registers a decorator to be applied after task execution.
- `before(task_decorator)`: Registers a decorator to be applied before task execution.
- `exception_handler(exception_handler)`: Sets a custom exception handler for tasks.
- `get_task(task_type)`: Retrieves a registered task handler.
- `remove_task(task_type)`: Removes a registered task handler.
- `task(task_type)`: Decorator to register a task handler.
```

--------------------------------

### ZeebeWorker Initialization

Source: https://camunda-community-hub.github.io/pyzeebe/worker_reference.html

The ZeebeWorker class inherits from ZeebeTaskRouter. Its constructor accepts optional lists of decorators to be applied before and after task execution, and an exception handler.

```APIDOC
## __init__

### Description
Initializes the ZeebeWorker with optional before and after decorators, and an exception handler.

### Parameters
* **before** (_list_[Callable[[Job], Job] | Callable[[Job], Awaitable[Job]]] | None) – Decorators to be performed before each task.
* **after** (_list_[Callable[[Job], Job] | Callable[[Job], Awaitable[Job]]] | None) – Decorators to be performed after each task.
* **exception_handler** (ExceptionHandler | None) – Handler that will be called when a job fails.
```

--------------------------------

### Task with Timeout Configuration

Source: https://camunda-community-hub.github.io/pyzeebe/worker_tasks.html

Configures a task with a specific timeout in milliseconds. If the task exceeds this duration, Zeebe will reactivate the job for another worker.

```python
from pyzeebe import worker

@worker.task(task_type="my_task", timeout_ms=20000)
def my_task(input: str):
    return {"output": f"Hello World, {input}!"}

```

--------------------------------

### Secure Channel Creation

Source: https://camunda-community-hub.github.io/pyzeebe/channels_quickstart.html

Creates a gRPC channel with a secure connection to a Zeebe Gateway using TLS.

```APIDOC
## Secure Channel

Creates a gRPC channel with a secure connection to a Zeebe Gateway with TLS.

### Method

```python
import grpc
from pyzeebe import create_secure_channel


credentials = grpc.ssl_channel_credentials(root_certificates="<root_certificate>", private_key="<private_key>")
channel = create_secure_channel(grpc_address="host:port", channel_credentials=credentials)
```
```

--------------------------------

### ZeebeTaskRouter

Source: https://camunda-community-hub.github.io/pyzeebe/worker_reference.html

Manages task routing and associated decorators for worker operations.

```APIDOC
## ZeebeTaskRouter

Manages task routing and associated decorators for worker operations.

### Methods

- `__init__()`: Initializes the ZeebeTaskRouter.
- `after(decorator)`: Registers a decorator to be applied after task execution.
- `before(decorator)`: Registers a decorator to be applied before task execution.
- `exception_handler(handler)`: Registers a custom exception handler.
- `get_task(task_type)`: Retrieves a task handler for a given task type.
- `remove_task(task_type)`: Removes a task handler for a given task type.
- `task(task_type)`: Decorator to register a function as a task handler.
```

--------------------------------

### create_secure_channel()

Source: https://camunda-community-hub.github.io/pyzeebe/channels.html

Creates a secure channel to a Zeebe gateway using TLS encryption. This is recommended for production environments to ensure data security.

```APIDOC
## create_secure_channel()

### Description
Creates a secure channel to a Zeebe gateway using TLS.

### Method
`create_secure_channel()`

### Parameters
- **ca_cert** (str) - Optional - Path to the Certificate Authority certificate file.
- **client_cert** (str) - Optional - Path to the client certificate file.
- **client_key** (str) - Optional - Path to the client private key file.

### Request Example
```python
from pyzeebe.channel import create_secure_channel

channel = create_secure_channel(host='your-zeebe-host.com', port=26500, ca_cert='path/to/ca.pem', client_cert='path/to/client.pem', client_key='path/to/client.key')
```

### Response
Returns a secure channel object for communicating with the Zeebe gateway.
```

--------------------------------

### Create Secure Channel

Source: https://camunda-community-hub.github.io/pyzeebe/channels_configuration.html

Use this function to establish a secure gRPC channel to the Zeebe Gateway. Ensure ZEEBE_ADDRESS is set if not using the default.

```python
pyzeebe.create_secure_channel()
```

--------------------------------

### pyzeebe.create_secure_channel

Source: https://camunda-community-hub.github.io/pyzeebe/_sources/channels_reference.rst.txt

Creates a secure gRPC channel to connect to a Zeebe gateway using TLS.

```APIDOC
## create_secure_channel

### Description
Creates a secure gRPC channel to connect to a Zeebe gateway using TLS.

### Function Signature
`pyzeebe.create_secure_channel(host: str, port: int)`

### Parameters
#### Path Parameters
- **host** (str) - The hostname of the Zeebe gateway.
- **port** (int) - The port of the Zeebe gateway.

### Returns
A gRPC channel object.
```

--------------------------------

### Job Class

Source: https://camunda-community-hub.github.io/pyzeebe/worker_reference.html

Represents a job received from Zeebe, containing details about the task, process instance, and variables.

```APIDOC
## Job Class

### Description
Represents a job received from Zeebe.

### Attributes

* **key** (_int_)
* **type** (_str_)
* **process_instance_key** (_int_)
* **bpmn_process_id** (_str_)
* **process_definition_version** (_int_)
* **process_definition_key** (_int_)
* **element_id** (_str_)
* **element_instance_key** (_int_)
* **custom_headers** (_Headers_)
* **worker** (_str_)
* **retries** (_int_)
* **deadline** (_int_)
* **variables** (_Variables_)
* **tenant_id** (_str | None_)
* **status** (_JobStatus_)
* **task_result** (_Any_)

### `set_task_result(task_result: Any)`

Sets the result of the task.
```

--------------------------------

### Task with Custom Exception Handler

Source: https://camunda-community-hub.github.io/pyzeebe/worker_tasks.html

Shows how to define and attach a custom exception handler to a task. The handler receives the exception, job, and job controller to manage task failures.

```python
from pyzeebe import Job, JobController, worker


async def my_exception_handler(exception: Exception, job: Job, job_controller: JobController) -> None:
    print(exception)
    await job_controller.set_failure_status(job, message=str(exception))


@worker.task(task_type="my_task", exception_handler=my_exception_handler)
def my_task():
    raise Exception()

```

--------------------------------

### broadcast_signal

Source: https://camunda-community-hub.github.io/pyzeebe/zeebe_adapter_reference.html

Asynchronously broadcasts a signal to process instances, optionally specifying variables and a tenant ID.

```APIDOC
## broadcast_signal

### Description
Broadcasts a signal to trigger waiting process instances.

### Method
async

### Parameters
- **_signal_name** (str) - The name of the signal to broadcast.
- **_variables** (Variables) - A dictionary of variables to send with the signal.
- **_tenant_id** (str | None) - Optional. The tenant ID to associate with the signal.
```

--------------------------------

### publish_message

Source: https://camunda-community-hub.github.io/pyzeebe/zeebe_adapter_reference.html

Asynchronously publishes a message to Zeebe, which can be used to correlate with process instances, with options for time-to-live, variables, and message ID.

```APIDOC
## publish_message

### Description
Publishes a message to the Zeebe cluster, which can be used for correlation or triggering events.

### Method
async

### Parameters
- **_name** (str) - The name of the message.
- **_correlation_key** (str) - The key used to correlate the message with process instances.
- **_time_to_live_in_milliseconds** (int) - The time-to-live for the message in milliseconds.
- **_variables** (Variables) - A dictionary of variables to send with the message.
- **_message_id** (str | None) - Optional. A unique identifier for the message.
- **_tenant_id** (str | None) - Optional. The tenant ID to associate with the message.
```