This release is a pre-release and may not be stable for production use.
Clappform
Python client for the Clappform gRPC APIs. Version 6 is a ground-up rewrite: the full API surface is generated from the shared proto definitions, with a hand-written ergonomic layer for DataFrame workflows, multi-cluster configuration, and typed errors.
Status: under active development on the
Major/6branch. The published 4.x/5.x packages are unrelated to this codebase.
Install
pip install --pre "clappform[pandas]"
Version 6 is in pre-release, so --pre is required. Without it pip resolves to
the unrelated 4.x package noted above. Quote the extra so zsh does not glob it.
Core dependencies are grpcio and protobuf only. The DataFrame flows below
need the pandas extra; polars and arrow are also declared, and
clappform[all] pulls in everything.
Quickstart
A client is one binding: a cluster, a tenant (location), and a credential.
Nothing is read from the environment; you pass everything in.
from clappform import Clappform
# The cluster is discovered from DNS, so location and an API key are all you need.
cf = Clappform(location="acme", api_key="cf_live_...")
with cf:
orders = cf.data.collection("sales_orders")
# Read a filtered slice straight into a pandas DataFrame.
df = orders.read(where={"status": "open"}, fields=["order_id", "amount"])
# Mutate it and write the changed rows back, matched on _id by default.
df["amount"] *= 1.08
orders.update(df)
cluster is the host extension ("prod", "qa", "" for the main cluster);
omit it and the client discovers it from DNS. location is your tenant
subdomain, sent as metadata on every call. Nothing is global, so two clusters
or tenants coexist in one process.
What you can do
| Task | How |
|---|---|
| Read / filter into a DataFrame | cf.data.collection(ref).read(where=..., fields=..., limit=...) |
| Aggregate (custom pipeline) | .aggregate([{"$match": ...}, {"$group": ...}, {"$sort": ...}]) |
| Aggregate (saved query) | cf.data.query(ref).read() |
| Insert new rows | .append(df) |
| Update existing rows | .update(df) (keys on _id) |
| Upsert / sync on a business key | .upsert(df, on="order_id") |
| Server-side mutate / delete | .replace_where(where, set_values) / .delete(where=...) / .clear() |
| Memory-bounded reads | .iter_batches(batch_size=...) |
| Start an actionflow | cf.client.actionflow.start(id=...) |
| List collections / apps / queries | cf.client.collection.iter_get_all() (and app, query, cronjob) |
| Move a whole app between instances | src.client.transfer.export_app(...) → dst.client.transfer.import_app(...) |
Errors are typed: every failure derives from ClappformError and carries the
call context (method, cluster, location), so you never import grpc to handle
one.
Testing without infrastructure
LocalMock is an in-process transport double: seed a data store, point a client
at it, and the full DataFrame surface round-trips with no network. Other RPCs
are stubbed with .on(method_path, response).
from clappform import Clappform
from clappform.testing import LocalMock
mock = LocalMock()
mock.seed_collection_slug("sales_orders", id="so-id")
mock.seed("so-id", [{"order_id": "A-1", "amount": 120.0, "status": "open"}])
with Clappform(location="acme", cluster="prod", api_key="test", transport=mock) as cf:
assert len(cf.data.collection("sales_orders").read(where={"status": "open"})) == 1
Documentation
Full guides and the generated API reference live at
clappform.readthedocs.io: quickstart,
DataFrame flows, actionflows & listings, multi-cluster / multi-tenant, error
handling & retries, and testing with LocalMock. Every code example in the
guides is a runnable snippet exercised against LocalMock in CI, so the docs
can't drift from the client.
Development
pip install -e ".[dev,pandas]"
make generate # regenerate clappform/gen and clappform/services from protos
make check # ruff + mypy + pytest
make docs-test # run the doc snippets, then build the site with --strict
make audit # pip-audit the installed tree against the advisory databases
make apicheck # public API removals and signature changes vs origin/Major/6
Code generation reads the proto definitions from the commons repository at
the tag pinned in COMMONS_VERSION. Point CLAPPFORM_COMMONS_DIR at a local
clone of commons (defaults to a sibling ../commons checkout).
Generated code under src/clappform/gen/ and src/clappform/services/ is
committed; do not edit it by hand.
License
Apache License 2.0 — see LICENSE.
Generated stubs under src/clappform/gen/google/ and
src/clappform/gen/grpc/ come from googleapis (Apache-2.0) and grpc-gateway
(BSD-3-Clause); NOTICE carries their terms.
1 maintainer
Release files for clappform 6.0.0a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| clappform-6.0.0a1.tar.gz | 338.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| clappform-6.0.0a1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 801.2 kB
Release files / clappform-6.0.0a1.tar.gz
| Download URL | clappform-6.0.0a1.tar.gz |
|---|---|
| Size | 338.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
aff38ecb745835ae68f0346b09043d477db237bb71493e6ba31ffeda5d514ae6
|
|
BLAKE2b-256 checksum How to use checksums |
ec3e05c71dfcbd179d9d44411808d4b768bcddbe43954a4c25ae766c77548ef1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Aug 25, 2026.
Transparency logRelease files / clappform-6.0.0a1-py3-none-any.whl
| Download URL | clappform-6.0.0a1-py3-none-any.whl |
|---|---|
| Size | 463.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3e890e31f7ddd286af58cd5913475bd10361ed7addf59aad21bd99b0193eb33b
|
|
BLAKE2b-256 checksum How to use checksums |
b07c9948be26d3145b0265bcf5fc216d453e865423b484f86964678149299a75
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Aug 25, 2026.
Transparency log
