WasmKeep actors in Python
Write WasmKeep actors as plain Python classes. WasmKeep is a self-hosted platform for actors: WebAssembly components, each with its own SQLite database, handling one event at a time. This package is the SDK and the command that builds your module into such a component, with componentize-py (CPython embedded). WasmKeep is pre-alpha.
Install
python3 -m venv .venv && . .venv/bin/activate
pip install wasmkeep
That is all a build needs: the package carries the WIT files of the
wasmkeep:actor world, and componentize-py comes with it at the version
the SDK is written for. To run the result you need the wasmkeep server:
install a release of the
same version as the package.
A first actor
app.py:
from wasmkeep import Actor, storage
class Hits(Actor):
# Once per deployed version, before any other event: create tables here.
def init(self):
storage.exec("CREATE TABLE IF NOT EXISTS hits (at INTEGER NOT NULL)")
# One HTTP request at a time, in arrival order: no locks needed.
def fetch(self, req):
storage.exec("INSERT INTO hits (at) VALUES (unixepoch())")
[row] = storage.query("SELECT count(*) AS n FROM hits")
return {"hits": row["n"], "path": req.path} # a dict is sent as JSON
WitWorld, IncomingHandler = Hits.exports()
Build it into a component and serve it:
python -m wasmkeep build app -o actor.wasm
wasmkeep serve --actor hits=actor.wasm
In another terminal:
curl localhost:8080/actor/hits/alice # {"hits": 1, "path": "/"}
curl localhost:8080/actor/hits/alice # {"hits": 2, "path": "/"}
curl localhost:8080/actor/hits/bob # {"hits": 1, "path": "/"}: another actor, its own database
build takes the module's name (app for app.py), found in the current
directory; -p DIR (repeatable) names other directories to find it and
what it imports in. Pure-Python packages installed in the same environment
are bundled too. The last line of app.py is what the component exports:
keep it at module level.
The other hooks, all optional:
from wasmkeep import Actor, sockets
class Room(Actor):
# The alarm set with alarms.set(...) fired (at least once).
def alarm(self):
pass
def websocket_open(self, conn, path):
sockets.send(conn, "welcome") # return False to refuse
def websocket_message(self, conn, data):
sockets.broadcast(data)
def websocket_close(self, conn, code, reason):
pass
Versions
| The package | The version of the WasmKeep server it is released with; use the two at the same version |
| componentize-py | 0.25.1 exactly, installed with the package: the SDK imports the bindings that version generates |
| Python, to run the build | 3.10 or later (CI builds with 3.13) |
| Python, in the component | CPython 3.14, the one componentize-py 0.25.1 embeds, whatever Python ran the build |
| The interface | wasmkeep:actor@0.2.0, versioned on its own: wasmkeep.WIT_VERSION, the WIT files in the package's wit/ |
python -m wasmkeep --version prints the package's version and the
interface's.
Outside a component
The host's functions (storage, alarms, actors, sockets, env, and
exports()) exist only inside a built component, running on a WasmKeep
node. Under plain CPython the package imports, so an editor resolves it and
the build command runs, but calling one of them raises RuntimeError: an
actor is tried by building it and serving it (wasmkeep serve runs on a
laptop). Keep logic you want to unit-test in functions that take and return
plain values.
API
storage.exec(sql, *params) |
Runs a statement; returns the rows changed |
storage.exec_durable(sql, *params) |
The same, returning once the write is durable (inside a transaction, only COMMIT) |
storage.query(sql, *params) |
Rows as dicts, by column name |
storage.delete_self() |
Deletes this actor when the event ends |
alarms.set(at_ms), alarms.get(), alarms.clear() |
The actor's single alarm, in ms since the Unix epoch |
env.get(name, default=None) |
The class's configuration value or secret (deploy --config, secrets set, serve --env; last wins; see env), or default |
actors.self_address() |
This actor's ActorAddress (tenant, class_name, name) |
actors.call("class/name", method=, path=, headers=, body=) |
Calls another actor; returns a CallResponse (status, headers, body, text(), json()) |
sockets.send(conn, data), broadcast(data, except_conn=), close(conn, code, reason), connections() |
The actor's WebSockets (str is text, bytes binary) |
Response(body, status, headers), json(value, status) |
Full responses; a handler may also return str, bytes, a dict or a list |
SQL values are None, int, float, str and bytes (bool binds as 0
or 1). Failures raise SqlError (with .kind: syntax, constraint, bind, ...)
and CallError (.kind: invalid-address, reentrant, too-large, timeout,
failed). An exception in fetch becomes a 500; in init or alarm it fails
the event (an alarm is retried).
One instance of your class handles events until the actor hibernates; keep
anything that must survive in storage, not on self.
Key-value and queues
wasmkeep.kv and wasmkeep.queue are clients for key-value shards and
queues built from actors (ADR 0015).
The shard and queue classes are the Rust SDK's: deploy the components of
examples/jobs
as classes kv and queue (a release carries them already built, kv.wasm
and queue.wasm). These clients speak their protocol over actors.call, byte for byte like the
Rust and TypeScript clients, so all of them share the same data.
from wasmkeep import Actor, kv, queue
store = kv.Client("kv", 8).with_read_cache(60_000) # 8 shards; get may serve 60 s old reads
jobs = queue.Client("queue/jobs")
class App(Actor):
def fetch(self, req):
if queue.is_delivery(req): # a push from a queue
return queue.handle_delivery(req, lambda _queue, m: "ack")
version = store.put("user:42", "Ada")
store.compare_and_set("user:42", version, "Ada L.") # KvError "conflict" if it moved
jobs.send("resize 42")
return store.get("user:42").value
WitWorld, IncomingHandler = App.exports()
kv.Client(class_name, shards) |
Keys over shards actors class_name/shard-<i>; every caller uses the same count |
get(key), get_fresh(key) |
An Entry (value, version, expires_at) or None; get_fresh skips the read cache |
put(key, value), put_with(key, value, expect=, ttl_ms=, durable=) |
The new version; expect is "any", "absent" or a version |
compare_and_set(key, expected, value) |
put only at version expected (None: absent) |
delete(key), delete_if(key, version) |
True if the key was there |
list(prefix, after=None, limit=100) |
Keys (bytes) from every shard, in byte order |
queue.Client(address) |
One queue actor, class/name |
send(body), send_delayed(body, ms), send_batch(bodies) |
Ids, once durable; a batch (up to 1,000) is all or none |
lease(max, visibility_ms), ack(m), retry(m, delay_ms=None), settle(items) |
Pull consumers; ack and retry are False for a stale lease |
stats(), dead_letters(limit) |
Stats (ready, delayed, in_flight, dead) and DeadLetters |
queue.is_delivery(req), queue.handle_delivery(req, handle) |
Push consumers: handle(queue, message) returns "ack", "retry" or queue.RetryAfter(ms) |
Failures raise kv.KvError (.kind: conflict, key-too-long, storage, call,
refused with .status) and queue.QueueError (storage, call, refused);
numbers outside Rust's u32/u64 raise ValueError. The
guide covers the semantics and
limits; examples/py-jobs is a working app.
Workflows
wasmkeep.workflow starts and follows durable workflows
(ADR 0019): the
workflow class is written with the Rust SDK's runner (as
examples/workflows/orders,
which a release carries already built, workflows-orders.wasm), one actor
per instance, and this client speaks its protocol over actors.call, like
the Rust workflow::Client. Only the client side is in Python.
from wasmkeep import workflow
orders = workflow.Client("orders") # instance `id` is actor `orders/<id>`
orders.start("order-42", "item=book") # a Status; idempotent while kept
orders.send_event("order-42", "approved", b"")
status = orders.status("order-42") # status.state, .output, .error, ...
orders.cancel("order-42")
workflow.Client(cls) |
Instances of the workflow class cls |
start(id, input=b"") |
Records the start (the instance runs in its own event, right after); returns its Status |
status(id), cancel(id) |
The instance's Status; cancel stops it (a finished one is unchanged) |
send_event(id, name, payload=b"") |
Delivers an event, recorded durably |
Status |
state ("running", "waiting", "completed", "failed", "cancelled"), wake_at, waiting_for, output, error, positions, is_finished |
Failures raise workflow.WorkflowError (.kind: unknown, finished, call,
refused with .status). The guide covers
the semantics.
From a clone
The examples build
against the SDK in the repository, with the same command
(examples/py-counter/build.sh): counter,
chat room,
jobs
(key-value, queues and workflow orders). The protocol code
(wasmkeep/wire.py) imports no host bindings, so the SDK's unit tests run
under plain CPython, without componentize-py:
sdks/python/test/run.sh # python3 -m unittest discover -s test
Python components are large (about 19 MB, CPython included) and slower than Rust: see languages.
License
Apache-2.0; see LICENSE and NOTICE in the package.
Metadata
Release files for wasmkeep 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| wasmkeep-0.2.0.tar.gz | 69.2 kB | With provenance | Details for wasmkeep-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| wasmkeep-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for wasmkeep-0.2.0-py3-none-any.whl |
Total release size: 137.4 kB
Release files / wasmkeep-0.2.0.tar.gz
| Download URL | wasmkeep-0.2.0.tar.gz |
|---|---|
| Size | 69.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
312ff8e629620410462f6a396075b226dedc3300b92a7bb861780044181b0f77
|
|
BLAKE2b-256 checksum How to use checksums |
5d9f16863c756b8d156feecef8ba6cbe3397d0509d0bb71ed6faafa145b2060e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / wasmkeep-0.2.0-py3-none-any.whl
| Download URL | wasmkeep-0.2.0-py3-none-any.whl |
|---|---|
| Size | 68.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
03cdf092f0d90d11331d91c854554625be54773d7654d24579f15d5f504f7b1f
|
|
BLAKE2b-256 checksum How to use checksums |
7520ede416c2fec062477f01485124c499992749310a36b030f96ab3d6c621a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logSecurity for wasmkeep 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for wasmkeep-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.