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.8.tar.gz (162.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-1.0.8-py3-none-any.whl (88.1 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: graphddb_runtime-1.0.8.tar.gz
  • Upload date:
  • Size: 162.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-1.0.8.tar.gz
Algorithm Hash digest
SHA256 ca28b0632a122e099c123e08d51b26d0d67842f9c407c8189df711d83dbb589a
MD5 f951dd65fbc567a60fabc7ef983b71bf
BLAKE2b-256 ffa06583d8b1c8562a8238a5eecb9a51727b5f096da40ebd1c067868caea2f0b

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for graphddb_runtime-1.0.8-py3-none-any.whl
Algorithm Hash digest
SHA256 4a96a7693ce27be0e15136160e81927f3680533523b14b81b4ba08115e6b7d5b
MD5 9d46c28f3c2276070dfefd25ea4677ed
BLAKE2b-256 af177350534093119bc4cbb73464b5cf4454c8983860b432b6f4e934899b580d

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

This release

1.0.8 This release

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

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