graphddb-runtime 0.1.0__py3-none-any.whl

graphddb_runtime-0.1.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: graphddb-runtime
+Version: 0.1.0
+Summary: Thin DynamoDB executor for GraphDDB-generated Python repositories (single-operation core, issue #44).
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: boto3>=1.26
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+
+# graphddb-runtime
+
+Thin DynamoDB executor for [GraphDDB](https://www.npmjs.com/package/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
+
+```bash
+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:
+
+```python
+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`.
+
+```python
+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).
+
+```python
+# 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).
+
+```bash
+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

graphddb_runtime-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+graphddb_runtime/__init__.py,sha256=vPHDIK7NUKoeZrMeDkv0XNj0BJ2Sa9tonskJWBIHax4,1584
+graphddb_runtime/async_runtime.py,sha256=uNncUcrbXFyFL6PcpwguA2iluzeLxJwgRYKm2LO3xp8,3807
+graphddb_runtime/batch.py,sha256=N2xbzDR1_69CUlUhM2GrRp3qEYUnh2jrRQlikUABNMs,7919
+graphddb_runtime/concurrency.py,sha256=zvw-VXuRar8z0Rne4Fo3cuczpXkhTRSaVaJlw7mYS6U,3975
+graphddb_runtime/cursor.py,sha256=sAIPsOkY0xPi9TJOv1oZEUYkfH4CgYUvkrFT9W0umHA,1935
+graphddb_runtime/errors.py,sha256=7x5Qq73trwNmYA6N7Z8rmmIy6J4kd2yVdEMniOaaRGQ,2828
+graphddb_runtime/filters.py,sha256=RKQgBSM019xXBQYbmmLvVTATOJYnwUmU73MBBarW5rI,6190
+graphddb_runtime/hydration.py,sha256=JOqBfsNLnttyA3v3vQ9TLsI_sEiFw3aELP-L5cv1_yo,2660
+graphddb_runtime/limits.py,sha256=gx8UycrSM3RM2xEMr9wTEE23VCPK18F36f4M0Fqc0O4,613
+graphddb_runtime/per_key_cursor.py,sha256=qxN-nK86ZHwAYttmil1Zkjgf_y3qaEEpq7xjWIoHqeY,4469
+graphddb_runtime/relations.py,sha256=XgSYTVcmY9W1zTV4Dsr6Bm-WK7qwD8w0YUC073D4ULo,8175
+graphddb_runtime/runtime.py,sha256=eZTleUqpje2qcqU5ZAKs_-J_ozrVZ9K-8ewXK4dcfJw,73895
+graphddb_runtime/templates.py,sha256=4CY7MHHf3I7BdsfRbjnc5RTj_YkSbmdQokc1kYCkGMQ,5270
+graphddb_runtime/transactions.py,sha256=qUq0d0MXXHficuN12Loj_kflN4tomakx6-EMnHfYvfg,19971
+graphddb_runtime-0.1.0.dist-info/METADATA,sha256=eQd3mp9l0XjJ-hTKrKYsMhpmaR0VGmdywGzijBPVyEU,5793
+graphddb_runtime-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+graphddb_runtime-0.1.0.dist-info/top_level.txt,sha256=UwvRUZAyjTrHzBVaj4g8M4DNlwavxVs88i16Tv-4JqU,17
+graphddb_runtime-0.1.0.dist-info/RECORD,,

graphddb_runtime-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

graphddb_runtime-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+graphddb_runtime