graphddb-runtime

Thin DynamoDB executor for GraphDDB-generated Python repositories.

graphddb-runtime is the small, hand-written package that generated repositories.py modules import as from graphddb_runtime import GraphDDBRuntime. It interprets the manifest.json / operations.json specifications produced by graphddb generate python and executes the validated access patterns against DynamoDB through boto3 — no scans, no hand-written key logic.

Features

  • Single-operation core — GetItem / Query reads and PutItem / UpdateItem / DeleteItem writes.
  • Relations & assembly — relation traversal, multi-operation assembly, BatchGetItem, result limits, and explain.
  • Conditional & transactional writes — conditional writes, declarative transactions (execute_transaction, with forEach / when expansion and TransactWriteItems batching up to 25 items).
  • Async adapter — AsyncGraphDDBRuntime exposes an await-able surface with behavior identical to the synchronous runtime.

Install

pip install graphddb-runtime

Requires Python 3.9+ and boto3.

Versioning. graphddb-runtime tracks the graphddb npm package version: a given runtime release matches the graphddb CLI of the same version, so the generated manifest.json / operations.json and the runtime that interprets them always stay in sync. Install the graphddb-runtime whose version equals the graphddb CLI you generated with.

Usage

Point the runtime at the two JSON specs emitted by graphddb generate python and pass a boto3 DynamoDB client. The generated repositories wrap it with typed methods:

import boto3
from graphddb_runtime import GraphDDBRuntime
from generated import UserRepository

runtime = GraphDDBRuntime(
    dynamodb_client=boto3.client("dynamodb"),
    manifest_path="generated/manifest.json",
    operations_path="generated/operations.json",
    # Map logical table names to deployed physical names when they differ.
    table_mapping={"UserPermissions": "UserPermissions-prod"},
)

users = UserRepository(runtime)
user = users.get_user_by_email(email="alice@example.com")

Async

boto3 is a synchronous SDK, so the runtime core is synchronous. AsyncGraphDDBRuntime is a thin adapter that runs each blocking call in a worker thread via asyncio.to_thread, giving an await-able surface with identical behavior (same params, specs, results, and error types). It does not require aioboto3.

import boto3
from graphddb_runtime import GraphDDBRuntime, AsyncGraphDDBRuntime

sync = GraphDDBRuntime(
    dynamodb_client=boto3.client("dynamodb"),
    manifest_path="generated/manifest.json",
    operations_path="generated/operations.json",
)
runtime = AsyncGraphDDBRuntime(sync)

user = await runtime.execute_query("getUser", {"userId": "alice"})
await runtime.execute_transaction("addManyMembers", {"groupId": "eng", "members": [...]})

The wrapped synchronous runtime is available as runtime.sync for callers that need the blocking API directly.

AWS Lambda

The runtime loads the JSON specs from disk and constructs a boto3 client — both are 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
from graphddb_runtime import GraphDDBRuntime
from generated import UserRepository

_runtime = GraphDDBRuntime(
    dynamodb_client=boto3.client("dynamodb"),
    manifest_path="generated/manifest.json",
    operations_path="generated/operations.json",
    table_mapping={"UserPermissions": "UserPermissions-prod"},
)
_users = UserRepository(_runtime)


def handler(event, context):
    user = _users.get_user_by_email(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 global client + GraphDDBRuntime(...) construction is captured in the snapshot and skipped on restore.

  • Initialize the runtime and repositories 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 loaded specs are safe to snapshot; refresh anything time-sensitive inside the handler.

Packaging

The deployment artifact needs three things: this runtime package, the generated bindings, and the two JSON specs. 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    # the runtime
cp -r generated build/generated                # manifest.json, operations.json, *.py
cp handler.py build/
( cd build && zip -r ../function.zip . )        # handler = handler.handler

Make sure the manifest_path / operations_path you pass to GraphDDBRuntime resolve relative to the deployed working directory (e.g. generated/... when the specs are zipped under a generated/ folder at the artifact root).

License

MIT

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.2.4)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for foo-ogawa from gravatar.com foo-ogawa

License

MIT

Requires

Python >=3.9

Provides Extra

test

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

graphddb_runtime-0.9.1.tar.gz (160.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

graphddb_runtime-0.9.1-py3-none-any.whl (86.5 kB view details)

Uploaded Python 3

File details

Details for the file graphddb_runtime-0.9.1.tar.gz.

File metadata

  • Download URL: graphddb_runtime-0.9.1.tar.gz
  • Upload date:
  • Size: 160.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.12.13

File hashes

Hashes for graphddb_runtime-0.9.1.tar.gz
Algorithm Hash digest
SHA256 def1b48d062158ad0b77e0d59468fc94049774c465da7ac33e35d562f8b7a1ce
MD5 97cae9d2dc16908f47b42750d8d2ff2b
BLAKE2b-256 600483662811d8f95db11f8b4f725330f51c8739abbbfbc7ec3ee8fce71b1684

See more details on using hashes here.

File details

Details for the file graphddb_runtime-0.9.1-py3-none-any.whl.

File metadata

File hashes

Hashes for graphddb_runtime-0.9.1-py3-none-any.whl
Algorithm Hash digest
SHA256 ebd1331449f3c6665e0eadf0f67202ec9a6881bfbb36b92dcfc65d638a2fa45d
MD5 31af0b1d6b6443a99e30b2fd8c444500
BLAKE2b-256 54d06c393fbc2918af1e2019e0a3b8878499886d3fb92f4ff4ab152d74b82ad7

See more details on using hashes here.

Release history Release notifications | RSS feed

1.2.4

2 files

1.2.3

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

1.1.1

2 files

1.1.0

2 files

1.0.9

2 files

1.0.8

2 files

1.0.7

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.9.3

2 files

0.9.2

2 files

This release

0.9.1 This release

2 files

0.9.0

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.10

2 files

0.7.9

2 files

0.7.8

2 files

0.7.7

2 files

0.7.6

2 files

0.7.5

2 files

0.7.4

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.0

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.1

2 files

0.3.0

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.1

2 files

0.1.0

2 files

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