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.7.9.tar.gz (135.9 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.7.9-py3-none-any.whl (72.0 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: graphddb_runtime-0.7.9.tar.gz
  • Upload date:
  • Size: 135.9 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.7.9.tar.gz
Algorithm Hash digest
SHA256 98a1fec068477547f7c836d6e4578c3ee4c2d44a7e7e750cacce59724b58a2e7
MD5 601917b551c23e0de5dd9deb1f1e3c69
BLAKE2b-256 6d2ee3b3760ca459ab81d531a79523cc62f6003f389cbbcddc0ac7bd04d80067

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for graphddb_runtime-0.7.9-py3-none-any.whl
Algorithm Hash digest
SHA256 b4ccc8b11d625200381affeff5350a05252dc853cfeddec33501212c14833bbd
MD5 884e2db1fd732e3c5eb6211cfbd446d1
BLAKE2b-256 3cead32ddccb52b5aebaaa314038d486929b79a507dc9bb9b12f1c9826219e88

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

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

This release

0.7.9 This release

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