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 |
pip install bookclerk-plugin-sdk # from PyPI
pip install -e packages/plugin-sdk-python # from this repository
Declare Python Workers in plugin.toml:
api_version = 3
runtime = "workerd"
[workerd]
compatibility_flags = ["python_workers", "disable_python_external_sdk"]
main_module = "plugin.py"
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] plugins only; the
ORIGIN binding a relay plugin hands requests to is in the TypeScript SDK.
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).
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(...).
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. 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. Generate a typed Env protocol from plugin.toml:
python -m bookclerk_plugin_sdk types . # writes bookclerk_configuration.py
A plugin that declares [sockets] (see
Pushed 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:
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.
A plugin that declares [[webhooks]] (see
Inbound webhooks) gets
self.env.WEBHOOKS, a WebhooksBinding:
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).
self.env.NETWORK is the grant in effect, as a dict (see
Network grant). A setting whose
destination still awaits approval shows "state": "pending":
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.
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):
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.
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).
- plugin.toml: declare the entrypoints and triggers the classes above implement.
- Entrypoints, events and the ABI: every method and event in detail.
examples/plugins-echo-workerd-python: a complete Python plugin.
The sections below are generated from the SDK's source: one page per module, and what the package itself exports.
| Module | Summary |
|---|---|
bookclerk_plugin_sdk.abi |
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 |
CLI entry: bookclerk-plugin / python -m bookclerk_plugin_sdk. |
bookclerk_plugin_sdk.db_value |
Universal Cap'n database value domain (DbValue) and unpacked codec. |
bookclerk_plugin_sdk.guest_sql |
Guest SQL classification — must match host guest_statement_kind. |
bookclerk_plugin_sdk.limits |
Typed limit_exceeded errors: the SQL-v1 cap a request or result broke. |
bookclerk_plugin_sdk.path_guard |
Path containment helpers for authoring tools and sparse workerd launchers. |
bookclerk_plugin_sdk.plugin_migration |
Resource bounds for plugin-owned databaseMigrations registration. |
bookclerk_plugin_sdk.scan_page |
Paging helper for a storefront's scan. |
bookclerk_plugin_sdk.sparse_workerd |
Sparse out-of-tree workerd launcher (no Rust bookclerk-workerd binary). |
bookclerk_plugin_sdk.sparse_workerd.config |
Materialize Cap'n Proto workerd config + bridge (mirrors config.rs). |
bookclerk_plugin_sdk.sparse_workerd.ensure |
Download / refresh the pinned Cloudflare workerd binary (mirrors ensure.rs). |
bookclerk_plugin_sdk.sparse_workerd.smoke |
Out-of-tree workerd plugin smoke: ensure → materialize → describe + health. |
bookclerk_plugin_sdk.testkit |
Contract conformance test kit: a plugin database binding like the host's. |
bookclerk_plugin_sdk.tools |
check / fmt / types / package / sync-embed — mirrors Rust/TS author tools. |
bookclerk_plugin_sdk.workerd |
Workerd author runtime — BookclerkEntrypoint and the named entrypoints. |
Bookclerk Python plugin guest SDK.
Provides the workerd guest surface via bookclerk_plugin_sdk.workerd.
Authors define a module-level Default class extending
bookclerk_plugin_sdk.workerd.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
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 |
class | A DatabaseBinding.write_chunks run that failed part way. |
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 |
constant | Product ABI version (plugin.toml api_version / describe().apiVersion). |
Brandfrombookclerk_plugin_sdk.abiCliInvokeParamsfrombookclerk_plugin_sdk.abiCliInvokeResultfrombookclerk_plugin_sdk.abiCliSchemafrombookclerk_plugin_sdk.abiD1ExecResultfrombookclerk_plugin_sdk.db_valueEntrypointfrombookclerk_plugin_sdk.abiD1Metafrombookclerk_plugin_sdk.db_valueD1Resultfrombookclerk_plugin_sdk.db_valueDatabaseBindingfrombookclerk_plugin_sdk.db_valueDiagnoseResultfrombookclerk_plugin_sdk.abiExecuteStreamDecoderfrombookclerk_plugin_sdk.db_valueExecuteStreamLimitsfrombookclerk_plugin_sdk.db_valueFetchTitleParamsfrombookclerk_plugin_sdk.abiHealthOkfrombookclerk_plugin_sdk.abiInvocationfrombookclerk_plugin_sdk.abiLoginParamsfrombookclerk_plugin_sdk.abiPluginDescribefrombookclerk_plugin_sdk.abiPluginErrorCodefrombookclerk_plugin_sdk.abiMAX_WRITE_KEY_BYTESfrombookclerk_plugin_sdk.db_valueRetryTokenfrombookclerk_plugin_sdk.db_valueWriteProgressfrombookclerk_plugin_sdk.db_valuewrite_chunks_operation_idfrombookclerk_plugin_sdk.db_valueFetchStorePagefrombookclerk_plugin_sdk.scan_pageScanParamsfrombookclerk_plugin_sdk.abiStorePagefrombookclerk_plugin_sdk.scan_pagescan_pagefrombookclerk_plugin_sdk.scan_pagecanonical_execute_request_hashfrombookclerk_plugin_sdk.db_valuechunk_indexesfrombookclerk_plugin_sdk.db_valuecreate_database_bindingfrombookclerk_plugin_sdk.db_valuedecode_db_valuefrombookclerk_plugin_sdk.db_valuedecode_execute_requestfrombookclerk_plugin_sdk.db_valuedecode_db_capabilities_replyfrombookclerk_plugin_sdk.db_valuedecode_execute_result_replyfrombookclerk_plugin_sdk.db_valuedecode_execute_streamfrombookclerk_plugin_sdk.db_valueencode_db_capabilities_replyfrombookclerk_plugin_sdk.db_valueLimitExceededfrombookclerk_plugin_sdk.limitslimit_exceeded_messagefrombookclerk_plugin_sdk.limitsparse_limit_exceededfrombookclerk_plugin_sdk.limitsencode_db_valuefrombookclerk_plugin_sdk.db_valueencode_execute_requestfrombookclerk_plugin_sdk.db_valueencode_execute_result_replyfrombookclerk_plugin_sdk.db_valueexecute_reply_to_d1_resultsfrombookclerk_plugin_sdk.db_valueexecute_stream_limitsfrombookclerk_plugin_sdk.db_valueraw_stream_ceilingfrombookclerk_plugin_sdk.db_valuestreams_resultsfrombookclerk_plugin_sdk.db_valueparse_db_valuefrombookclerk_plugin_sdk.db_valuestatement_result_to_d1_resultfrombookclerk_plugin_sdk.db_value
class WriteChunksError(PluginError)
A DatabaseBinding.write_chunks run that failed part way.
code, message and details are the failed batch's.
Attributes
next: Statements committed before the failure; resume withstart=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.
def __init__(self, next_offset: int, cause: PluginError) -> None
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: int = 3
Product ABI version (plugin.toml api_version / describe().apiVersion).
Source: docs/plugins/sdk/python/README.md at main · View as Markdown