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-1.0.4.tar.gz (161.8 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-1.0.4-py3-none-any.whl (87.5 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for graphddb_runtime-1.0.4.tar.gz
Algorithm Hash digest
SHA256 4e94b250c2c7b1ae279a25e72c6b78b7ad0bb298b99d709c536901d3c431628f
MD5 12b1888c5491f26e75ea952f4fb99855
BLAKE2b-256 62a3aeef6e946d1b86b91f7a4f2e519d8a05b874789d96465a69954d387c27e5

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for graphddb_runtime-1.0.4-py3-none-any.whl
Algorithm Hash digest
SHA256 1c34c75d2d8a3fc5c85c07ab51c232c0034a1638b7f89a4846c507facac7e0f4
MD5 4ac49b1138f77dbd627fdbfb125d8f66
BLAKE2b-256 48c28069d58f46f6c97d4506cd8155d5ba6350e546f950b42165cafc2d320222

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

This release

1.0.4 This release

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

0.9.1

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