# Python plugin SDK

This page shows how to write a Bookclerk plugin in Python with
`bookclerk-plugin-sdk` (`api_version = 3`). A Python plugin is a Python
Worker in a workerd isolate; `bookclerk-workerd` injects
`bookclerk_plugin_sdk.workerd` and the modules it uses (including
`bookclerk_plugin_sdk.db_value` for database bindings) into the isolate, so
you import them rather than vendor a path.

| Import | What it holds |
| --- | --- |
| `bookclerk_plugin_sdk.workerd` | `BookclerkEntrypoint`, `CliEntrypoint` and the `js` bridge |
| `python -m bookclerk_plugin_sdk` | The author CLI |

## Install

```bash
pip install bookclerk-plugin-sdk          # from PyPI
pip install -e packages/plugin-sdk-python # from this repository
```

Declare Python Workers in `plugin.toml`:

```toml
api_version = 3
runtime = "workerd"
[workerd]
compatibility_flags = ["python_workers", "disable_python_external_sdk"]
main_module = "plugin.py"
```

## Author model

The module-level `Default` class extends `BookclerkEntrypoint` and
implements the triggers `plugin.toml` declares: `event(batch)` for
`[[events.consumers]]`, `job(job)` for `[triggers] jobs`,
`scheduled(controller)` for `[triggers] crons` and
`database_migrations(binding)` for `[[databases]]`. Every named
entrypoint in `entrypoints = [...]` is a module-level class with the
matching name extending its base: `Storefront(StorefrontEntrypoint)`,
`Storage(StorageEntrypoint)`, `RemoteLibrary(RemoteLibraryEntrypoint)`,
`DatabaseAdapter(DatabaseAdapterEntrypoint)`, `Cli(CliEntrypoint)`,
`Oidc(OidcEntrypoint)`, `Metadata(MetadataEntrypoint)`,
`Covers(CoverEntrypoint)`, `MetadataFiles(MetadataFilesEntrypoint)`,
`Notifier(NotifierEntrypoint)`, `Ingress(IngressEntrypoint)` and
`Ai(AiEntrypoint)`. The Python SDK serves `direct`
[`[ingress]`](/docs/plugins/manifest/index.md#ingress-public-address) plugins only; the
`ORIGIN` binding a relay plugin hands requests to is in the TypeScript SDK.

```python
from bookclerk_plugin_sdk.workerd import (
    BookclerkEntrypoint,
    CliEntrypoint,
    EventBatch,
    cli_args,
    json_payload,
)

class Cli(CliEntrypoint):
    async def describe(self):
        return {"commands": [{"name": "ping", "about": "Probe", "args": []}]}

    async def invoke(self, params):
        message = cli_args(params).get("message", "hi")
        return {
            "exitCode": 0,
            "stdout": f"pong: {message}\n",
            "stderr": "",
            "payload": json_payload({"pong": message}),
        }

class Default(BookclerkEntrypoint):
    async def event(self, batch: EventBatch):
        for msg in batch.messages:
            if msg.type != "book_acquired":
                msg.reject(f"unexpected {msg.type}")
                continue
            print(f"saw {msg.json().get('titleId', '')} via {self.env.CONFIG}")
            msg.ack()
```

Identity (`apiVersion`, `id`, capabilities) comes from `plugin.toml`; an
optional `describe()` on `Default` only refines `displayName` and similar
fields.

A database adapter runs each host batch through `execute_adapter_batch`
or `execute_adapter_batch_streamed` (in `bookclerk_plugin_sdk.db_value`),
which stores the guest's replay receipt before `COMMIT` and, for a
streamed reply, rolls back when the frames do not fit one scalar or the
adapter's advertised streamed budget (`execute_stream_limits(caps)`) (see
[Isolate adapter batches](/docs/plugins/sql-contract/v1/index.md#isolate-adapter-batches-and-replay-receipts)).

## Triggers

Each `EventMessage` records one outcome, `ack()`, `retry(retry_at=...,
delay_seconds=..., reason=...)`, `reject(reason)`, `dead_letter(reason)`
or `suspend(checkpoint=..., wake_at=...)`, and the first call wins.
Untouched messages ack on return and retry on raise. A `job(job)` handler
returns to complete, raises to reject, or calls `job.suspend(...)` or
`job.retry_later(...)`.

## The `env` bindings

Granted bindings arrive on `self.env` per invocation: `CONFIG`,
`SECRETS`, `EVENTS`, `WORK_FS`, and one entry per `[[databases]]`
binding. A binding's `await limits()` returns the `DbCapabilities` its
session negotiated; a request or result over one of them raises a
`PluginError` whose `code` is `limit_exceeded` and whose `limit` names
the cap. On a host that predates `limits()` the call raises
`unsupported`. `all()` reads through the session's streamed budget when
it advertises one, `prepare(sql).iterate()` yields rows one at a time
from the same read, `db.chunk(statements)` splits a long list into
batches that each fit one request, and `db.write_chunks(...)` commits those
batches resumably; see
[Working within database limits](/docs/plugins/database-limits/index.md). A
storefront's `scan` can hand its paging to `scan_page(params, fetch)`
(`from bookclerk_plugin_sdk.scan_page import scan_page`, which also works
inside a workerd isolate), which slices the store's own pages into replies
the host accepts; see [Paged scans](/docs/plugins/abi/index.md#paged-scans). Generate a typed `Env` protocol from `plugin.toml`:

```bash
python -m bookclerk_plugin_sdk types .   # writes bookclerk_configuration.py
```

## Pushed sockets

A plugin that declares `[sockets]` (see
[Pushed sockets](/docs/plugins/abi/index.md#pushed-sockets-sockets)) gets
`self.env.SOCKETS`, a `SocketsBinding` shaped like Durable Objects'
hibernatable WebSockets. The host holds the connection, so the plugin may
sleep between messages, and each message reaches the default entrypoint:

```python
class Default(BookclerkEntrypoint):
    async def scheduled(self, controller):
        if await self.env.SOCKETS.get_web_sockets():
            return
        await self.env.SOCKETS.connect(
            "wss://abs.example.com/socket.io/?EIO=4&transport=websocket",
            headers={"Authorization": f"Bearer {self.env.SECRETS['token']}"},
            auto_responses=[("2", "3")],  # answered without waking the plugin
            attachment={"library": "main"},
        )

    async def web_socket_message(self, ws, message):
        library = ws.deserialize_attachment()["library"]
        ...

    async def web_socket_close(self, ws, code, reason, was_clean):
        ...
```

Text arrives as `str` and binary as `bytes`. `await ws.send(...)`,
`await ws.close(code, reason)` and `await ws.serialize_attachment(value)`
act on the host's socket; the attachment is JSON of at most 2 KiB, kept
for the socket's life.

A remote library whose message announced a new user returns
`{"poll_events": True}` from `web_socket_message`, and the host calls
`poll_events` right away instead of at its next scheduled poll.

## Inbound webhooks

A plugin that declares `[[webhooks]]` (see
[Inbound webhooks](/docs/plugins/abi/index.md#inbound-webhooks-webhooks)) gets
`self.env.WEBHOOKS`, a `WebhooksBinding`:

```python
class Default(BookclerkEntrypoint):
    async def scheduled(self, controller) -> None:
        page = await self.env.WEBHOOKS.pull("events", batch_size=50)
        if page.missed:
            await self.relist()  # requests expired unread: resynchronize
        for message in page.messages:
            await self.handle(json.loads(message.body))
        await self.env.WEBHOOKS.ack("events", acks=[m.lease_id for m in page.messages])

    async def webhook_delivered(self, name: str, waiting: int) -> None:
        """Optional: called on a running plugin as soon as a request is stored."""
```

`await self.env.WEBHOOKS.url("events")` returns the URL to hand the
outside service, or `None` when the library has no public `https`
address or webhooks are off. Each `WebhookMessage` has `lease_id`,
`timestamp` (a UTC `datetime`), `attempts`, `headers` and `body` (`bytes`).

## Network grant

`self.env.NETWORK` is the grant in effect, as a dict (see
[Network grant](/docs/plugins/abi/index.md#network-grant-envnetwork)). A setting whose
destination still awaits approval shows `"state": "pending"`:

```python
rows = self.env.NETWORK["settings"]
row = next((r for r in rows if r["key"] == "server_url"), None)
if row and row["state"] == "pending":
    raise RuntimeError(f"Approve {row['destination']} on the plugin's consent form")
```

A refused fetch answers `403` with an `x-bookclerk-error:
network_not_granted` header; report it rather than retrying.

## Testing database code

`create_test_database()` from `bookclerk_plugin_sdk.testkit` gives a
pytest suite the same binding a host grants, served by the
`bookclerk-db-testkit` executable under one capability profile with the
plugin's `database_migrations` applied. `bookclerk-plugin test .` runs the
suite once per profile (`first-party`, `d1` and `minimum`):

```python
from bookclerk_plugin_sdk.testkit import create_test_database

async with await create_test_database(migrations=MIGRATIONS) as db:  # profile from `bookclerk-plugin test`
    await db.binding.prepare("INSERT INTO notes (body) VALUES (?)").bind(body).run()
```

The `echo_workerd_python` example (`examples/plugins-echo-workerd-python/`)
is a worked plugin: a `notes` table it writes with `chunk()`, lists with
`iterate()` or key-paged reads, sizes with `limits()`, and tests under
every profile. A plugin's own `pyproject.toml` is what makes
`bookclerk-plugin test` run pytest. See
[Testing against the limits](/docs/plugins/database-limits/index.md#testing-against-the-limits).

## Author tools

```bash
python -m bookclerk_plugin_sdk check .
python -m bookclerk_plugin_sdk types .
python -m bookclerk_plugin_sdk package --out dist .
python -m bookclerk_plugin_sdk smoke .   # download the pinned workerd, then describe + health
```

`smoke` does not need a built `bookclerk-workerd`. It downloads the
pinned Cloudflare `workerd` into `~/.cache/bookclerk/workerd` (override
with `BOOKCLERK_WORKERD_CACHE` or `BOOKCLERK_WORKERD_BIN`).

## Next steps

- [plugin.toml](/docs/plugins/manifest/index.md): declare the entrypoints and
  triggers the classes above implement.
- [Entrypoints, events and the ABI](/docs/plugins/abi/index.md): every method and
  event in detail.
- [`examples/plugins-echo-workerd-python`](https://github.com/Bookclerk/bookclerk/tree/main/examples/plugins-echo-workerd-python/):
  a complete Python plugin.

## Reference

The sections below are generated from the SDK's source: one page per
module, and what the package itself exports.

## Modules

| Module | Summary |
| --- | --- |
| [`bookclerk_plugin_sdk.abi`](/docs/plugins/sdk/python/abi/index.md) | GENERATED FILE - do not edit. Run `python3 scripts/gen-plugin-abi.py --write` after changing crates/bookclerk-plugin-abi/schema/plugin.capnp. |
| [`bookclerk_plugin_sdk.cli`](/docs/plugins/sdk/python/cli/index.md) | CLI entry: `bookclerk-plugin` / `python -m bookclerk_plugin_sdk`. |
| [`bookclerk_plugin_sdk.db_value`](/docs/plugins/sdk/python/db_value/index.md) | Universal Cap'n database value domain (`DbValue`) and unpacked codec. |
| [`bookclerk_plugin_sdk.guest_sql`](/docs/plugins/sdk/python/guest_sql/index.md) | Guest SQL classification — must match host `guest_statement_kind`. |
| [`bookclerk_plugin_sdk.limits`](/docs/plugins/sdk/python/limits/index.md) | Typed `limit_exceeded` errors: the SQL-v1 cap a request or result broke. |
| [`bookclerk_plugin_sdk.path_guard`](/docs/plugins/sdk/python/path_guard/index.md) | Path containment helpers for authoring tools and sparse workerd launchers. |
| [`bookclerk_plugin_sdk.plugin_migration`](/docs/plugins/sdk/python/plugin_migration/index.md) | Resource bounds for plugin-owned `databaseMigrations` registration. |
| [`bookclerk_plugin_sdk.scan_page`](/docs/plugins/sdk/python/scan_page/index.md) | Paging helper for a storefront's `scan`. |
| [`bookclerk_plugin_sdk.sparse_workerd`](/docs/plugins/sdk/python/sparse_workerd/index.md) | Sparse out-of-tree workerd launcher (no Rust `bookclerk-workerd` binary). |
| [`bookclerk_plugin_sdk.sparse_workerd.config`](/docs/plugins/sdk/python/sparse_workerd/config/index.md) | Materialize Cap'n Proto workerd config + bridge (mirrors config.rs). |
| [`bookclerk_plugin_sdk.sparse_workerd.ensure`](/docs/plugins/sdk/python/sparse_workerd/ensure/index.md) | Download / refresh the pinned Cloudflare `workerd` binary (mirrors ensure.rs). |
| [`bookclerk_plugin_sdk.sparse_workerd.smoke`](/docs/plugins/sdk/python/sparse_workerd/smoke/index.md) | Out-of-tree workerd plugin smoke: ensure → materialize → describe + health. |
| [`bookclerk_plugin_sdk.testkit`](/docs/plugins/sdk/python/testkit/index.md) | Contract conformance test kit: a plugin database binding like the host's. |
| [`bookclerk_plugin_sdk.tools`](/docs/plugins/sdk/python/tools/index.md) | check / fmt / types / package / sync-embed — mirrors Rust/TS author tools. |
| [`bookclerk_plugin_sdk.workerd`](/docs/plugins/sdk/python/workerd/index.md) | Workerd author runtime — `BookclerkEntrypoint` and the named entrypoints. |

Bookclerk Python plugin guest SDK.

Provides the workerd guest surface via [`bookclerk_plugin_sdk.workerd`](/docs/plugins/sdk/python/workerd/index.md).
Authors define a module-level `Default` class extending
[`bookclerk_plugin_sdk.workerd.BookclerkEntrypoint`](/docs/plugins/sdk/python/workerd/index.md#bookclerkentrypoint) (`event(batch)` /
`job(job)` triggers) plus one class per `plugin.toml` entrypoint
(`class Cli(CliEntrypoint)`, `class Storage(StorageEntrypoint)`, …).
Native guests use the Rust SDK (`serve` / `PluginWorker`). See `docs/plugins/README.md`.

Typical import:

- Workerd: `from bookclerk_plugin_sdk.workerd import BookclerkEntrypoint, CliEntrypoint, js`
- Tools: `python -m bookclerk_plugin_sdk check|fmt|types|package|smoke`

Every ABI struct, union, enum, and interface in [`bookclerk_plugin_sdk.abi`](/docs/plugins/sdk/python/abi/index.md)
and the product constants in `bookclerk_plugin_sdk._abi` are generated
from `crates/bookclerk-plugin-abi/schema/plugin.capnp` — the single ABI
source of truth.

| Name | Kind | Summary |
| --- | --- | --- |
| [`WriteChunksError`](#writechunkserror) | class | A `DatabaseBinding.write_chunks` run that failed part way. |
| [`PLUGIN_ERROR_CODES`](#plugin_error_codes) | constant | Stable `PluginError.code` strings. Unknown future codes are forwarded as-is; SDKs surface them as a local `unknown` while keeping the raw wire code. |
| [`PRODUCT_API_VERSION`](#product_api_version) | constant | Product ABI version (`plugin.toml` `api_version` / `describe().apiVersion`). |

## Re-exports

- [`Brand`](/docs/plugins/sdk/python/abi/index.md#brand) from `bookclerk_plugin_sdk.abi`
- [`CliInvokeParams`](/docs/plugins/sdk/python/abi/index.md#cliinvokeparams) from `bookclerk_plugin_sdk.abi`
- [`CliInvokeResult`](/docs/plugins/sdk/python/abi/index.md#cliinvokeresult) from `bookclerk_plugin_sdk.abi`
- [`CliSchema`](/docs/plugins/sdk/python/abi/index.md#clischema) from `bookclerk_plugin_sdk.abi`
- [`D1ExecResult`](/docs/plugins/sdk/python/db_value/index.md#d1execresult) from `bookclerk_plugin_sdk.db_value`
- [`Entrypoint`](/docs/plugins/sdk/python/abi/index.md#entrypoint) from `bookclerk_plugin_sdk.abi`
- [`D1Meta`](/docs/plugins/sdk/python/db_value/index.md#d1meta) from `bookclerk_plugin_sdk.db_value`
- [`D1Result`](/docs/plugins/sdk/python/db_value/index.md#d1result) from `bookclerk_plugin_sdk.db_value`
- [`DatabaseBinding`](/docs/plugins/sdk/python/db_value/index.md#databasebinding) from `bookclerk_plugin_sdk.db_value`
- [`DiagnoseResult`](/docs/plugins/sdk/python/abi/index.md#diagnoseresult) from `bookclerk_plugin_sdk.abi`
- [`ExecuteStreamDecoder`](/docs/plugins/sdk/python/db_value/index.md#executestreamdecoder) from `bookclerk_plugin_sdk.db_value`
- [`ExecuteStreamLimits`](/docs/plugins/sdk/python/db_value/index.md#executestreamlimits) from `bookclerk_plugin_sdk.db_value`
- [`FetchTitleParams`](/docs/plugins/sdk/python/abi/index.md#fetchtitleparams) from `bookclerk_plugin_sdk.abi`
- [`HealthOk`](/docs/plugins/sdk/python/abi/index.md#healthok) from `bookclerk_plugin_sdk.abi`
- [`Invocation`](/docs/plugins/sdk/python/abi/index.md#invocation) from `bookclerk_plugin_sdk.abi`
- [`LoginParams`](/docs/plugins/sdk/python/abi/index.md#loginparams) from `bookclerk_plugin_sdk.abi`
- [`PluginDescribe`](/docs/plugins/sdk/python/abi/index.md#plugindescribe) from `bookclerk_plugin_sdk.abi`
- [`PluginErrorCode`](/docs/plugins/sdk/python/abi/index.md#pluginerrorcode) from `bookclerk_plugin_sdk.abi`
- [`MAX_WRITE_KEY_BYTES`](/docs/plugins/sdk/python/db_value/index.md#max_write_key_bytes) from `bookclerk_plugin_sdk.db_value`
- [`RetryToken`](/docs/plugins/sdk/python/db_value/index.md#retrytoken) from `bookclerk_plugin_sdk.db_value`
- [`WriteProgress`](/docs/plugins/sdk/python/db_value/index.md#writeprogress) from `bookclerk_plugin_sdk.db_value`
- [`write_chunks_operation_id`](/docs/plugins/sdk/python/db_value/index.md#write_chunks_operation_id) from `bookclerk_plugin_sdk.db_value`
- [`FetchStorePage`](/docs/plugins/sdk/python/scan_page/index.md#fetchstorepage) from `bookclerk_plugin_sdk.scan_page`
- [`ScanParams`](/docs/plugins/sdk/python/abi/index.md#scanparams) from `bookclerk_plugin_sdk.abi`
- [`StorePage`](/docs/plugins/sdk/python/scan_page/index.md#storepage) from `bookclerk_plugin_sdk.scan_page`
- [`scan_page`](/docs/plugins/sdk/python/scan_page/index.md#scan_page) from `bookclerk_plugin_sdk.scan_page`
- [`canonical_execute_request_hash`](/docs/plugins/sdk/python/db_value/index.md#canonical_execute_request_hash) from `bookclerk_plugin_sdk.db_value`
- [`chunk_indexes`](/docs/plugins/sdk/python/db_value/index.md#chunk_indexes) from `bookclerk_plugin_sdk.db_value`
- [`create_database_binding`](/docs/plugins/sdk/python/db_value/index.md#create_database_binding) from `bookclerk_plugin_sdk.db_value`
- [`decode_db_value`](/docs/plugins/sdk/python/db_value/index.md#decode_db_value) from `bookclerk_plugin_sdk.db_value`
- [`decode_execute_request`](/docs/plugins/sdk/python/db_value/index.md#decode_execute_request) from `bookclerk_plugin_sdk.db_value`
- [`decode_db_capabilities_reply`](/docs/plugins/sdk/python/db_value/index.md#decode_db_capabilities_reply) from `bookclerk_plugin_sdk.db_value`
- [`decode_execute_result_reply`](/docs/plugins/sdk/python/db_value/index.md#decode_execute_result_reply) from `bookclerk_plugin_sdk.db_value`
- [`decode_execute_stream`](/docs/plugins/sdk/python/db_value/index.md#decode_execute_stream) from `bookclerk_plugin_sdk.db_value`
- [`encode_db_capabilities_reply`](/docs/plugins/sdk/python/db_value/index.md#encode_db_capabilities_reply) from `bookclerk_plugin_sdk.db_value`
- [`LimitExceeded`](/docs/plugins/sdk/python/limits/index.md#limitexceeded) from `bookclerk_plugin_sdk.limits`
- [`limit_exceeded_message`](/docs/plugins/sdk/python/limits/index.md#limit_exceeded_message) from `bookclerk_plugin_sdk.limits`
- [`parse_limit_exceeded`](/docs/plugins/sdk/python/limits/index.md#parse_limit_exceeded) from `bookclerk_plugin_sdk.limits`
- [`encode_db_value`](/docs/plugins/sdk/python/db_value/index.md#encode_db_value) from `bookclerk_plugin_sdk.db_value`
- [`encode_execute_request`](/docs/plugins/sdk/python/db_value/index.md#encode_execute_request) from `bookclerk_plugin_sdk.db_value`
- [`encode_execute_result_reply`](/docs/plugins/sdk/python/db_value/index.md#encode_execute_result_reply) from `bookclerk_plugin_sdk.db_value`
- [`execute_reply_to_d1_results`](/docs/plugins/sdk/python/db_value/index.md#execute_reply_to_d1_results) from `bookclerk_plugin_sdk.db_value`
- [`execute_stream_limits`](/docs/plugins/sdk/python/db_value/index.md#execute_stream_limits) from `bookclerk_plugin_sdk.db_value`
- [`raw_stream_ceiling`](/docs/plugins/sdk/python/db_value/index.md#raw_stream_ceiling) from `bookclerk_plugin_sdk.db_value`
- [`streams_results`](/docs/plugins/sdk/python/db_value/index.md#streams_results) from `bookclerk_plugin_sdk.db_value`
- [`parse_db_value`](/docs/plugins/sdk/python/db_value/index.md#parse_db_value) from `bookclerk_plugin_sdk.db_value`
- [`statement_result_to_d1_result`](/docs/plugins/sdk/python/db_value/index.md#statement_result_to_d1_result) from `bookclerk_plugin_sdk.db_value`

## Classes

### WriteChunksError

```python
class WriteChunksError(PluginError)
```

A [`DatabaseBinding.write_chunks`](/docs/plugins/sdk/python/db_value/index.md#databasebindingwrite_chunks) run that failed part way.

`code`, `message` and `details` are the failed batch's.

**Attributes**

- `next`: Statements committed before the failure; resume with `start=next`. The failed batch may have committed with its reply lost: resuming resends it under the same operation id, so the host replays its receipt instead of writing it twice.

#### WriteChunksError.__init__

```python
def __init__(self, next_offset: int, cause: PluginError) -> None
```

## Constants

### PLUGIN_ERROR_CODES

```python
PLUGIN_ERROR_CODES: tuple[str, ...] = ('invalid_params', 'unauthorized', 'forbidden', 'not_found', 'unavailable', '...
```

Stable `PluginError.code` strings. Unknown future codes are forwarded
as-is; SDKs surface them as a local `unknown` while keeping the raw wire
code.

Wire strings of `PluginErrorCode` in ordinal order (snake_case `Text` codes).

### PRODUCT_API_VERSION

```python
PRODUCT_API_VERSION: int = 3
```

Product ABI version (`plugin.toml` `api_version` / `describe().apiVersion`).
