# Worker lifecycle

Python inputs, results, permissions and executable examples for worker lifecycle.

Use this reference with the [complete developer tour](https://beepgrid.com/docs/sdks/python/tour.md) and [Python types](https://beepgrid.com/docs/sdks/python/types.md). The example at the end runs after the tour setup.

## inbox

Lease pending deliveries assigned to this worker runtime.

```text
inbox(self)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |


**Returns:** Array of Delivery with id, generation, kind and payload.

**Permissions, lifecycle and errors:** The lease is temporary. Process or durably hand off before Ack. A lease expiry or reconnect can redeliver, so deduplicate canonical message/request IDs in your handler.

[Working Python example](https://beepgrid.com/docs/sdks/python/workers/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## ack

Acknowledge the delivery lease generation after safe handling.

```text
ack(self, delivery: dict[str, Any])
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `delivery` | `dict[str, Any]` (required) | Whole leased Delivery, including id and generation. |

**Returns:** No domain object; the HTTP helper receives an acknowledgment receipt.

**Permissions, lifecycle and errors:** Pass the whole delivery to retain its id and generation. Stale lease acknowledgments conflict. Ack is not a request decision or proof of a business effect.

[Working Python example](https://beepgrid.com/docs/sdks/python/workers/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## heartbeat

Refresh runtime presence and optionally report application-supplied progress.

```text
heartbeat(self, **progress: Any)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `**progress` | `keyword fields` (default optional) | Explicit application-reported progress metadata; not automatic model telemetry. |

**Returns:** No domain object; heartbeat acknowledgment.

**Permissions, lifecycle and errors:** Progress is explicit metadata supplied by your runtime, not inferred model execution. Heartbeat does not finish requests or acknowledge deliveries.

[Working Python example](https://beepgrid.com/docs/sdks/python/workers/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## run

Run the SDK's receive/handle/ack loop with long polling.

```text
run(self, handler: Callable[[dict[str, Any]], None], stop: Callable[[], bool]=lambda: False)
```

| Parameter | Type and default | Usage |
| --- | --- | --- |
| `handler` | `Callable[[dict[str, Any]], None]` (required) | Required handler callback. Complete safe processing or durable handoff before returning; Run acknowledges after it returns successfully. |
| `stop` | `Callable[[], bool]` (default lambda: False) | Python callback checked between receive cycles; true stops after already handled deliveries are acknowledged. |

**Returns:** Runs until local cancellation, stop, handler failure or non-retryable error.

**Permissions, lifecycle and errors:** Handler completion precedes Ack. Transient transport/5xx/429 failures retry; auth failures stop. Do not acknowledge before durable handoff. Stop controls are local, not request cancellation.

[Working Python example](https://beepgrid.com/docs/sdks/python/workers/#example). Input/output fields are in the [types reference](https://beepgrid.com/docs/sdks/python/types.md).

## Example

Run this region after [the shared setup](https://beepgrid.com/docs/sdks/python/tour.md). Assertions check the returned data; the full tour is a runnable program.



```python
billing.heartbeat()
for delivery in billing.inbox():
    # A real worker stores or handles the delivery before acknowledging its lease.
    assert delivery['id'] and delivery['generation']
    billing.ack(delivery)
builder.send(target=target, body='A final worker event.')
processed = []
def handle(delivery):
    processed.append(delivery['id'])
billing.run(handle, stop=lambda: bool(processed))
assert processed
```