graphddb-runtime
The DynamoDB issuance a GraphDDB behavior module binds, for Python.
An operation is behavior: you author it as a @behavior static method over
graphddb's @leaf catalog in ordinary TypeScript, bc generate --lang python emits
the module that runs it, and graphddb-runtime supplies what one physical DynamoDB
request needs and a behavior cannot carry — the boto3 client, the logical → physical
table mapping, the AttributeValue codec, the execution bounds and the error mapping.
It interprets no specification document. Code generation and IR belong to behavior-contracts; the generated module embeds its own IR and gates its own spec version when imported.
Features
- Leaf transports —
leaf_handlers(runtime)supplies theGetItem/Query/BatchGetItem/PutItem/UpdateItem/DeleteItemissuance a compiled behavior binds. Each handler issues ONE physical request and returns the raw row(s): no ordering, no fan-out, no key derivation, no result shaping — those are the behavior's, compiled by behavior-contracts. - Cursor codecs — the opaque base64url pagination cursor, byte-identical to the TypeScript and PHP runtimes'.
Install
pip install graphddb-runtime
Requires Python 3.9+ and boto3.
Versioning.
graphddb-runtimetracks thegraphddbnpm package version: a given runtime release matches thegraphddbCLI of the same version.
Usage
Construct the runtime with a boto3 client, then hand its leaf handlers to the
generated module's bind:
import boto3
import my_behaviors as gen # bc generate --lang python --from behaviors.ts
from graphddb_runtime import GraphDDBRuntime, leaf_handlers
runtime = GraphDDBRuntime(
dynamodb_client=boto3.client("dynamodb"),
# Map logical table names to deployed physical names when they differ.
table_mapping={"UserPermissions": "UserPermissions-prod"},
)
bound = gen.bind(leaf_handlers(runtime))
user = bound["getUserByEmail"]({"email": "alice@example.com"})
groups = bound["listUserGroups"]({"userId": "alice", "limit": 20})
A write behavior returns whether it applied — a DynamoDB
ConditionalCheckFailedException is an expected outcome of a conditional write, so
it comes back as False rather than raising, and the behavior branches on it:
applied = bound["createMembership"]({"userId": "alice", "groupId": "eng", "role": "admin"})
AWS Lambda
Constructing the boto3 client and importing the generated module are both cold-start costs you want to pay once, in module scope, so they are reused across warm invocations (and frozen by SnapStart).
# handler.py — module scope runs once per execution environment (cold start).
import json
import boto3
import my_behaviors as gen
from graphddb_runtime import GraphDDBRuntime, leaf_handlers
_bound = gen.bind(
leaf_handlers(
GraphDDBRuntime(
dynamodb_client=boto3.client("dynamodb"),
table_mapping={"UserPermissions": "UserPermissions-prod"},
)
)
)
def handler(event, context):
user = _bound["getUserByEmail"]({"email": event["queryStringParameters"]["email"]})
if user is None:
return {"statusCode": 404, "body": "not found"}
return {"statusCode": 200, "body": json.dumps(user)}
SnapStart
Lambda SnapStart snapshots the initialized execution environment after the
module-scope code runs, so the client, the imported module and the bind are
captured in the snapshot and skipped on restore.
- Bind in module scope (as above), never inside the handler — that is what gets snapshotted.
- Do not cache short-lived state across the snapshot (credentials/tokens with an expiry, random seeds). The DynamoDB client and the embedded IR are safe to snapshot; refresh anything time-sensitive inside the handler.
Packaging
The deployment artifact needs three things: this runtime package, the
behavior-contracts runtime the generated module imports, and the generated module
itself. boto3/botocore are provided by the Lambda Python runtime, so they need not be
vendored (pin them only if you require a specific version).
mkdir -p build
pip install graphddb-runtime --target build # pulls in behavior-contracts
cp my_behaviors.py handler.py build/
( cd build && zip -r ../function.zip . ) # handler = handler.handler
License
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file graphddb_runtime-1.2.4.tar.gz.
File metadata
- Download URL: graphddb_runtime-1.2.4.tar.gz
- Upload date:
- Size: 41.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.12.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c65f8bcf47fb960b73ef4707bbb0b20d6267668c928caa09212064b026ec3529
|
|
| MD5 |
7f6108965e4904ea4c38cc123f4e81a6
|
|
| BLAKE2b-256 |
cc7f02ca83ab36693c4e2935be183d08bc38507051061a5280dc6132b61a180a
|
File details
Details for the file graphddb_runtime-1.2.4-py3-none-any.whl.
File metadata
- Download URL: graphddb_runtime-1.2.4-py3-none-any.whl
- Upload date:
- Size: 22.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.12.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ef55e79455ba1a439b6da5c43a0a333c9cb94d29d67a4785b6cfda1f9d8d5828
|
|
| MD5 |
0213cc6fc48ea8df6ef4077fdeb90e20
|
|
| BLAKE2b-256 |
606cffd2e6763889c79c7b9ac053fe7a391761882bda18920a0a61ef2ddd2bca
|
