Skip to main content

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.

Several outbound requests at once

The Python SDK has no outbound HTTP helper yet, for one request or several. componentize-py's own bindings for wasi:http are in the component, and they can keep several requests open together: start each with wit_world.imports.outgoing_handler.handle, then wait on their futures' pollables at once with wit_world.imports.poll.poll, keeping each future's result the first time get() returns one (a second get() fails). Tried by hand, outside the shared tests; the Rust, TypeScript and Go SDKs have helpers for it (http::fetch_all, http.fetchAll, FetchAll).

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.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wasmkeep 0.5.0
File Size Uploaded Provenance Actions
wasmkeep-0.5.0.tar.gz 71.0 kB With provenance Details for wasmkeep-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wasmkeep 0.5.0
File Interpreter ABI Platform Actions
wasmkeep-0.5.0-py3-none-any.whl Python 3 none any Details for wasmkeep-0.5.0-py3-none-any.whl

Total release size: 141.1 kB

Release files / wasmkeep-0.5.0.tar.gz

Download URL wasmkeep-0.5.0.tar.gz
Size 71.0 kB
Tags Source
SHA-256 checksum
How to use checksums
c75e7e950a7727ed3bf9046640107731b73bb4317ed48c72fb9419ef05bdceaa
BLAKE2b-256 checksum
How to use checksums
5b3f694b21b77d2bc411d9d3ebe1ce1e6b85fdef820f655060af048d59951df1
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 17, 2026.

Transparency log

Release files / wasmkeep-0.5.0-py3-none-any.whl

Download URL wasmkeep-0.5.0-py3-none-any.whl
Size 70.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f8ec2cf4bfa85ccd7fb154789222ae53cb857ead06d4577f0f1b56c13a38b360
BLAKE2b-256 checksum
How to use checksums
1fb88d470de7fab3342a071fbe6914f6cb6c146f4cc68171d6b3677588e43195
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 17, 2026.

Transparency log

Security for wasmkeep 0.5.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.

Select from 2 files

Attestation for wasmkeep-0.5.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 17, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page