graphddb-runtime 1.1.0__tar.gz → 1.2.0__tar.gz

graphddb_runtime-1.2.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: graphddb-runtime
+Version: 1.2.0
+Summary: The DynamoDB issuance a GraphDDB behavior module binds: the leaf transports, table mapping, AttributeValue codec and cursor codecs.
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: boto3>=1.26
+Requires-Dist: behavior-contracts==0.11.16
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+
+# graphddb-runtime
+
+The DynamoDB issuance a [GraphDDB](https://www.npmjs.com/package/graphddb) behavior
+module binds, for Python.
+
+An operation is **behavior**: you author it as a `@behavior static` method over
+graphddb's `@leaf` catalog in ordinary TypeScript, `bc generate --lang python` emits
+the module that runs it, and `graphddb-runtime` supplies what one physical DynamoDB
+request needs and a behavior cannot carry — the boto3 client, the logical → physical
+table mapping, the AttributeValue codec, the execution bounds and the error mapping.
+
+It interprets no specification document. Code generation and IR belong to
+[behavior-contracts](https://pypi.org/project/behavior-contracts/); the generated
+module embeds its own IR and gates its own spec version when imported.
+
+## Features
+
+- **Leaf transports** — `leaf_handlers(runtime)` supplies the `GetItem` / `Query` /
+  `BatchGetItem` / `PutItem` / `UpdateItem` / `DeleteItem` issuance a compiled
+  behavior binds. Each handler issues ONE physical request and returns the raw
+  row(s): no ordering, no fan-out, no key derivation, no result shaping — those are
+  the behavior's, compiled by behavior-contracts.
+- **Cursor codecs** — the opaque base64url pagination cursor, byte-identical to the
+  TypeScript and PHP runtimes'.
+
+## 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.
+
+## Usage
+
+Construct the runtime with a boto3 client, then hand its leaf handlers to the
+generated module's `bind`:
+
+```python
+import boto3
+import my_behaviors as gen          # bc generate --lang python --from behaviors.ts
+from graphddb_runtime import GraphDDBRuntime, leaf_handlers
+
+runtime = GraphDDBRuntime(
+    dynamodb_client=boto3.client("dynamodb"),
+    # Map logical table names to deployed physical names when they differ.
+    table_mapping={"UserPermissions": "UserPermissions-prod"},
+)
+bound = gen.bind(leaf_handlers(runtime))
+
+user = bound["getUserByEmail"]({"email": "alice@example.com"})
+groups = bound["listUserGroups"]({"userId": "alice", "limit": 20})
+```
+
+A write behavior returns whether it applied — a DynamoDB
+`ConditionalCheckFailedException` is an expected outcome of a conditional write, so
+it comes back as `False` rather than raising, and the behavior branches on it:
+
+```python
+applied = bound["createMembership"]({"userId": "alice", "groupId": "eng", "role": "admin"})
+```
+
+## AWS Lambda
+
+Constructing the boto3 client and importing the generated module are both 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
+import my_behaviors as gen
+from graphddb_runtime import GraphDDBRuntime, leaf_handlers
+
+_bound = gen.bind(
+    leaf_handlers(
+        GraphDDBRuntime(
+            dynamodb_client=boto3.client("dynamodb"),
+            table_mapping={"UserPermissions": "UserPermissions-prod"},
+        )
+    )
+)
+
+
+def handler(event, context):
+    user = _bound["getUserByEmail"]({"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 client, the imported module and the `bind` are
+captured in the snapshot and skipped on restore.
+
+- **Bind 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 embedded IR are safe to
+  snapshot; refresh anything time-sensitive inside the handler.
+
+### Packaging
+
+The deployment artifact needs three things: this runtime package, the
+`behavior-contracts` runtime the generated module imports, and the generated module
+itself. 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    # pulls in behavior-contracts
+cp my_behaviors.py handler.py build/
+( cd build && zip -r ../function.zip . )        # handler = handler.handler
+```
+
+## License
+
+MIT

graphddb_runtime-1.2.0/README.md

@@ -0,0 +1,124 @@
+# graphddb-runtime
+
+The DynamoDB issuance a [GraphDDB](https://www.npmjs.com/package/graphddb) behavior
+module binds, for Python.
+
+An operation is **behavior**: you author it as a `@behavior static` method over
+graphddb's `@leaf` catalog in ordinary TypeScript, `bc generate --lang python` emits
+the module that runs it, and `graphddb-runtime` supplies what one physical DynamoDB
+request needs and a behavior cannot carry — the boto3 client, the logical → physical
+table mapping, the AttributeValue codec, the execution bounds and the error mapping.
+
+It interprets no specification document. Code generation and IR belong to
+[behavior-contracts](https://pypi.org/project/behavior-contracts/); the generated
+module embeds its own IR and gates its own spec version when imported.
+
+## Features
+
+- **Leaf transports** — `leaf_handlers(runtime)` supplies the `GetItem` / `Query` /
+  `BatchGetItem` / `PutItem` / `UpdateItem` / `DeleteItem` issuance a compiled
+  behavior binds. Each handler issues ONE physical request and returns the raw
+  row(s): no ordering, no fan-out, no key derivation, no result shaping — those are
+  the behavior's, compiled by behavior-contracts.
+- **Cursor codecs** — the opaque base64url pagination cursor, byte-identical to the
+  TypeScript and PHP runtimes'.
+
+## 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.
+
+## Usage
+
+Construct the runtime with a boto3 client, then hand its leaf handlers to the
+generated module's `bind`:
+
+```python
+import boto3
+import my_behaviors as gen          # bc generate --lang python --from behaviors.ts
+from graphddb_runtime import GraphDDBRuntime, leaf_handlers
+
+runtime = GraphDDBRuntime(
+    dynamodb_client=boto3.client("dynamodb"),
+    # Map logical table names to deployed physical names when they differ.
+    table_mapping={"UserPermissions": "UserPermissions-prod"},
+)
+bound = gen.bind(leaf_handlers(runtime))
+
+user = bound["getUserByEmail"]({"email": "alice@example.com"})
+groups = bound["listUserGroups"]({"userId": "alice", "limit": 20})
+```
+
+A write behavior returns whether it applied — a DynamoDB
+`ConditionalCheckFailedException` is an expected outcome of a conditional write, so
+it comes back as `False` rather than raising, and the behavior branches on it:
+
+```python
+applied = bound["createMembership"]({"userId": "alice", "groupId": "eng", "role": "admin"})
+```
+
+## AWS Lambda
+
+Constructing the boto3 client and importing the generated module are both 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
+import my_behaviors as gen
+from graphddb_runtime import GraphDDBRuntime, leaf_handlers
+
+_bound = gen.bind(
+    leaf_handlers(
+        GraphDDBRuntime(
+            dynamodb_client=boto3.client("dynamodb"),
+            table_mapping={"UserPermissions": "UserPermissions-prod"},
+        )
+    )
+)
+
+
+def handler(event, context):
+    user = _bound["getUserByEmail"]({"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 client, the imported module and the `bind` are
+captured in the snapshot and skipped on restore.
+
+- **Bind 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 embedded IR are safe to
+  snapshot; refresh anything time-sensitive inside the handler.
+
+### Packaging
+
+The deployment artifact needs three things: this runtime package, the
+`behavior-contracts` runtime the generated module imports, and the generated module
+itself. 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    # pulls in behavior-contracts
+cp my_behaviors.py handler.py build/
+( cd build && zip -r ../function.zip . )        # handler = handler.handler
+```
+
+## License
+
+MIT

graphddb_runtime-1.2.0/graphddb_runtime/__init__.py

@@ -0,0 +1,58 @@
+"""GraphDDB Python runtime — the DynamoDB issuance a generated module binds.
+
+An operation is behavior: the consumer authors it as a ``@behavior`` method over
+graphddb's ``@leaf`` catalog, ``bc generate`` emits the module, and this package
+supplies what one physical request needs::
+
+    import my_behaviors as gen
+    from graphddb_runtime import GraphDDBRuntime, leaf_handlers
+
+    runtime = GraphDDBRuntime(boto3.client("dynamodb"), {"members": "AppTable"})
+    bound = gen.bind(leaf_handlers(runtime))
+    page = bound["listUserGroups"]({"userId": "alice"})
+
+Public surface:
+
+- :class:`GraphDDBRuntime` — the issuance context (client, table mapping, codec,
+  bounds, error mapping).
+- :func:`leaf_handlers` — graphddb's DynamoDB leaf transports, for ``bind``.
+- :class:`RuntimeLimits` — execution-time bounds.
+- the :class:`GraphDDBError` family.
+- the cursor codecs, for a paged read's opaque cursor.
+- the transport-middleware vocabulary (:class:`RequestCtx` / :class:`Outcome` /
+  :class:`Refuse` / :class:`Guard` / :class:`Respond`), for a host that wraps the
+  physical requests — see :mod:`graphddb_runtime.transport`.
+"""
+
+from __future__ import annotations
+
+from .cursor import decode_cursor, encode_cursor
+from .errors import GraphDDBError, OperationExecutionError
+from .limits import RuntimeLimits
+from .per_key_cursor import (
+    decode_per_key_cursor,
+    encode_per_key_cursor,
+    serialize_contract_key,
+)
+from .runtime import GraphDDBRuntime
+from .leaf_handlers import leaf_handlers
+from .transport import Guard, Outcome, Refuse, RequestCtx, Respond
+
+__all__ = [
+    "GraphDDBRuntime",
+    "leaf_handlers",
+    "RuntimeLimits",
+    # transport middleware — the host's seam around one physical request
+    "RequestCtx",
+    "Outcome",
+    "Refuse",
+    "Guard",
+    "Respond",
+    "GraphDDBError",
+    "OperationExecutionError",
+    "encode_cursor",
+    "decode_cursor",
+    "serialize_contract_key",
+    "encode_per_key_cursor",
+    "decode_per_key_cursor",
+]

{graphddb_runtime-1.1.0 → graphddb_runtime-1.2.0}/graphddb_runtime/batch.py

@@ -3,8 +3,9 @@
 Port of the TypeScript batch semantics (``src/operations/batch-retry.ts`` /
 ``src/executor/batch-executor.ts``):
 
-- keys are **deduped** before the request (``planBatchGetForQueryKeys`` /
-  ``dedupeDynamoKeys``);
+- keys arrive already **unique**: removing duplicates is the leaf transport's,
+  upstream of chunking (:func:`graphddb_runtime.leaf_handlers.leaf_handlers`
+  ``batch_get_items``);
 - split into chunks of at most :data:`BATCH_GET_MAX_KEYS` (100) keys;
 - each chunk retries ``UnprocessedKeys`` with exponential backoff
   (``50 * 2^(attempt-1)`` ms, capped at 1000ms) up to
@@ -17,7 +18,7 @@ real delays.
 from __future__ import annotations
 
 import time
-from typing import Any, Callable, Dict, List, Mapping, Optional
+from typing import Any, Callable, Dict, List, Optional
 
 # Mirrors src/operations/batch-retry.ts.
 BATCH_GET_MAX_KEYS = 100
@@ -34,19 +35,8 @@ def chunk(items: List[Any], size: int) -> List[List[Any]]:
     return [items[i : i + size] for i in range(0, len(items), size)]
 
 
-def serialize_key(key: Mapping[str, Any]) -> str:
-    """Stable string form of a (plain) key for dedup / parent matching.
-
-    Mirrors the TS ``dedupeDynamoKeys`` / ``serializeQueryKey`` ordering
-    (attributes sorted by name).
-    """
-    import json
-
-    return json.dumps(sorted(key.items()), separators=(",", ":"), default=str)
-
-
 class BatchGetExecutor:
-    """Executes a deduped, chunked, retrying BatchGetItem against a boto3 client.
+    """Executes a chunked, retrying BatchGetItem against a boto3 client.
 
     The client is the low-level ``boto3.client("dynamodb")`` (AttributeValue
     shapes). ``request_extra`` carries the optional ``ProjectionExpression`` /

graphddb_runtime-1.2.0/graphddb_runtime/errors.py

@@ -0,0 +1,24 @@
+"""Error hierarchy for the GraphDDB Python runtime.
+
+Every runtime-raised error derives from :class:`GraphDDBError` so callers can catch
+the whole family with a single ``except``. Only errors this runtime actually raises
+live here — a declared-but-never-raised class reads as a handled condition that is
+in fact unreachable.
+"""
+
+from __future__ import annotations
+
+
+class GraphDDBError(Exception):
+    """Base class for every error raised by the runtime."""
+
+
+class OperationExecutionError(GraphDDBError):
+    """Wraps a boto3 ``ClientError`` (or any boto3 failure) from a DynamoDB call.
+
+    The original exception is preserved as ``__cause__`` and on ``original``.
+    """
+
+    def __init__(self, message: str, original: BaseException | None = None) -> None:
+        super().__init__(message)
+        self.original = original