alt-python-pynosqlc-dynamodb 1.0.4__tar.gz

alt_python_pynosqlc_dynamodb-1.0.4/.gitignore

@@ -0,0 +1,30 @@
+
+# ── GSD baseline (auto-generated) ──
+.gsd
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+*~
+.idea/
+.vscode/
+*.code-workspace
+.env
+.env.*
+!.env.example
+node_modules/
+.next/
+dist/
+build/
+__pycache__/
+*.pyc
+.venv/
+venv/
+target/
+vendor/
+*.log
+coverage/
+.cache/
+tmp/
+
+/.bg-shell/

alt_python_pynosqlc_dynamodb-1.0.4/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: alt-python-pynosqlc-dynamodb
+Version: 1.0.4
+Summary: DynamoDB driver for pynosqlc
+Project-URL: Homepage, https://github.com/alt-python/pynosqlc
+Project-URL: Repository, https://github.com/alt-python/pynosqlc
+Project-URL: Documentation, https://github.com/alt-python/pynosqlc#getting-started
+Project-URL: Bug Tracker, https://github.com/alt-python/pynosqlc/issues
+Author: Craig Parravicini, Claude (Anthropic)
+License: MIT
+Keywords: async,aws,database,driver,dynamodb,nosql
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: aioboto3>=2.7
+Requires-Dist: alt-python-pynosqlc-core
+Description-Content-Type: text/markdown
+
+# pynosqlc-dynamodb
+
+DynamoDB driver for [pynosqlc](https://github.com/alt-python/pynosqlc) — connects to Amazon DynamoDB (or DynamoDB Local) via aioboto3.
+
+## Install
+
+```
+pip install alt-python-pynosqlc-dynamodb
+```
+
+## Requirements
+
+- Python 3.12+
+- aioboto3 2.7+
+- AWS credentials configured (`~/.aws/credentials`, environment variables, or IAM role)
+- For local development: [DynamoDB Local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html)
+
+## Usage
+
+### AWS (production)
+
+```python
+import asyncio
+from pynosqlc.core import DriverManager, Filter
+import pynosqlc.dynamodb  # auto-registers DynamoDriver
+
+async def main():
+    async with await DriverManager.get_client('pynosqlc:dynamodb:us-east-1') as client:
+        col = client.get_collection('orders')
+        await col.store('o1', {'item': 'widget', 'qty': 5})
+        f = Filter.where('qty').gt(0).build()
+        async for doc in await col.find(f):
+            print(doc)
+
+asyncio.run(main())
+```
+
+### DynamoDB Local
+
+Pass `endpoint` in the properties dict to point at a local instance:
+
+```python
+async with await DriverManager.get_client(
+    'pynosqlc:dynamodb:us-east-1',
+    properties={'endpoint': 'http://localhost:8000'},
+) as client:
+    ...
+```
+
+## URL scheme
+
+```
+pynosqlc:dynamodb:<aws-region>
+```
+
+Example: `pynosqlc:dynamodb:us-east-1`
+
+Optional properties:
+
+| Key | Description |
+|---|---|
+| `endpoint` | Override endpoint URL (e.g. `http://localhost:8000` for DynamoDB Local) |
+| `aws_access_key_id` | AWS access key (falls back to environment / credential chain) |
+| `aws_secret_access_key` | AWS secret key (falls back to environment / credential chain) |

alt_python_pynosqlc_dynamodb-1.0.4/README.md

@@ -0,0 +1,64 @@
+# pynosqlc-dynamodb
+
+DynamoDB driver for [pynosqlc](https://github.com/alt-python/pynosqlc) — connects to Amazon DynamoDB (or DynamoDB Local) via aioboto3.
+
+## Install
+
+```
+pip install alt-python-pynosqlc-dynamodb
+```
+
+## Requirements
+
+- Python 3.12+
+- aioboto3 2.7+
+- AWS credentials configured (`~/.aws/credentials`, environment variables, or IAM role)
+- For local development: [DynamoDB Local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html)
+
+## Usage
+
+### AWS (production)
+
+```python
+import asyncio
+from pynosqlc.core import DriverManager, Filter
+import pynosqlc.dynamodb  # auto-registers DynamoDriver
+
+async def main():
+    async with await DriverManager.get_client('pynosqlc:dynamodb:us-east-1') as client:
+        col = client.get_collection('orders')
+        await col.store('o1', {'item': 'widget', 'qty': 5})
+        f = Filter.where('qty').gt(0).build()
+        async for doc in await col.find(f):
+            print(doc)
+
+asyncio.run(main())
+```
+
+### DynamoDB Local
+
+Pass `endpoint` in the properties dict to point at a local instance:
+
+```python
+async with await DriverManager.get_client(
+    'pynosqlc:dynamodb:us-east-1',
+    properties={'endpoint': 'http://localhost:8000'},
+) as client:
+    ...
+```
+
+## URL scheme
+
+```
+pynosqlc:dynamodb:<aws-region>
+```
+
+Example: `pynosqlc:dynamodb:us-east-1`
+
+Optional properties:
+
+| Key | Description |
+|---|---|
+| `endpoint` | Override endpoint URL (e.g. `http://localhost:8000` for DynamoDB Local) |
+| `aws_access_key_id` | AWS access key (falls back to environment / credential chain) |
+| `aws_secret_access_key` | AWS secret key (falls back to environment / credential chain) |

alt_python_pynosqlc_dynamodb-1.0.4/pynosqlc/dynamodb/__init__.py

@@ -0,0 +1,20 @@
+"""DynamoDB driver for pynosqlc.
+
+Importing this package auto-registers the DynamoDriver with DriverManager.
+"""
+
+from __future__ import annotations
+
+from pynosqlc.dynamodb.dynamo_filter_translator import DynamoFilterTranslator
+from pynosqlc.dynamodb.dynamo_client import DynamoClient
+from pynosqlc.dynamodb.dynamo_collection import DynamoCollection
+
+# Import last — triggers module-level DriverManager.register_driver() call.
+from pynosqlc.dynamodb.dynamo_driver import DynamoDriver  # noqa: F401  (side-effect import)
+
+__all__ = [
+    "DynamoDriver",
+    "DynamoClient",
+    "DynamoCollection",
+    "DynamoFilterTranslator",
+]

alt_python_pynosqlc_dynamodb-1.0.4/pynosqlc/dynamodb/dynamo_client.py

@@ -0,0 +1,111 @@
+"""
+dynamo_client.py — DynamoClient: a pynosqlc Client backed by aioboto3 DynamoDB resource.
+"""
+
+from __future__ import annotations
+
+import botocore.exceptions
+
+from pynosqlc.core.client import Client
+from pynosqlc.dynamodb.dynamo_collection import DynamoCollection
+
+
+class DynamoClient(Client):
+    """A pynosqlc Client backed by an aioboto3 DynamoDB resource.
+
+    Args:
+        url: the original ``pynosqlc:dynamodb:<region>`` URL.
+        session: an :class:`aioboto3.Session` instance.
+        region: the AWS region name.
+        endpoint: optional endpoint URL override (e.g. for DynamoDB Local).
+        properties: driver-specific properties dict.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        session,
+        region: str,
+        endpoint: str | None,
+        properties: dict | None = None,
+    ) -> None:
+        super().__init__({"url": url})
+        self._session = session
+        self._region = region
+        self._endpoint = endpoint
+        self._properties = properties or {}
+        self._resource = None
+        self._resource_ctx = None
+        self._table_cache: set[str] = set()
+
+    async def _open(self) -> None:
+        """Enter the aioboto3 DynamoDB resource context manager.
+
+        Must be called by the driver after constructing this client.
+        """
+        self._resource_ctx = self._session.resource(
+            "dynamodb",
+            region_name=self._region,
+            endpoint_url=self._endpoint,
+        )
+        self._resource = await self._resource_ctx.__aenter__()
+
+    def _get_collection(self, name: str) -> DynamoCollection:
+        """Create and return a :class:`DynamoCollection` for *name*."""
+        return DynamoCollection(self, name)
+
+    async def _close(self) -> None:
+        """Exit the aioboto3 DynamoDB resource context manager."""
+        if self._resource_ctx is not None:
+            await self._resource_ctx.__aexit__(None, None, None)
+            self._resource_ctx = None
+            self._resource = None
+
+    async def ensure_table(self, name: str) -> None:
+        """Ensure the DynamoDB table *name* exists, creating it if necessary.
+
+        Uses ``_pk`` (String) as the partition key and ``PAY_PER_REQUEST``
+        billing so no capacity planning is required.
+
+        Idempotent: if the table already exists (verified or from cache),
+        this is a no-op.
+
+        Args:
+            name: the DynamoDB table name.
+        """
+        if name in self._table_cache:
+            return
+
+        table = await self._resource.Table(name)
+
+        # Check whether the table exists.
+        try:
+            await table.load()
+            # Table exists — cache it and return.
+            self._table_cache.add(name)
+            return
+        except botocore.exceptions.ClientError as exc:
+            code = exc.response["Error"]["Code"]
+            if code not in ("ResourceNotFoundException",):
+                raise
+
+        # Table does not exist — create it.
+        try:
+            await self._resource.create_table(
+                TableName=name,
+                KeySchema=[{"AttributeName": "_pk", "KeyType": "HASH"}],
+                AttributeDefinitions=[
+                    {"AttributeName": "_pk", "AttributeType": "S"}
+                ],
+                BillingMode="PAY_PER_REQUEST",
+            )
+        except botocore.exceptions.ClientError as exc:
+            code = exc.response["Error"]["Code"]
+            if code not in ("ResourceInUseException", "TableAlreadyExistsException"):
+                raise
+            # Race: another coroutine already created the table — that's fine.
+
+        # Wait for the table to become ACTIVE.
+        waiter_table = await self._resource.Table(name)
+        await waiter_table.wait_until_exists()
+        self._table_cache.add(name)

alt_python_pynosqlc_dynamodb-1.0.4/pynosqlc/dynamodb/dynamo_collection.py

@@ -0,0 +1,133 @@
+"""
+dynamo_collection.py — DynamoCollection: a pynosqlc Collection backed by a DynamoDB table.
+
+The primary key attribute is ``_pk`` (String). All other document fields are
+stored as top-level DynamoDB item attributes.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from pynosqlc.core.collection import Collection
+from pynosqlc.core.cursor import Cursor
+from pynosqlc.dynamodb.dynamo_filter_translator import DynamoFilterTranslator
+
+
+class DynamoCollection(Collection):
+    """A pynosqlc Collection backed by a DynamoDB table.
+
+    The DynamoDB table is created on first access with ``_pk`` as the
+    partition key.  :meth:`DynamoClient.ensure_table` is called at the start
+    of every operation — it is a no-op after the first successful call.
+
+    Args:
+        client: the owning :class:`~pynosqlc.dynamodb.DynamoClient`.
+        name: the table / collection name.
+    """
+
+    def __init__(self, client, name: str) -> None:
+        super().__init__(client, name)
+
+    async def _get(self, key: str) -> dict | None:
+        """Retrieve a document by its ``_pk``."""
+        await self._client.ensure_table(self._name)
+        table = await self._client._resource.Table(self._name)
+
+        resp = await table.get_item(Key={"_pk": key})
+        item = resp.get("Item")
+        if item is None:
+            return None
+        return {k: v for k, v in item.items() if k != "_pk"}
+
+    async def _store(self, key: str, doc: dict) -> None:
+        """Upsert a document, setting ``_pk = key``."""
+        await self._client.ensure_table(self._name)
+        table = await self._client._resource.Table(self._name)
+
+        await table.put_item(Item={**doc, "_pk": key})
+
+    async def _delete(self, key: str) -> None:
+        """Delete the document at ``_pk = key``."""
+        await self._client.ensure_table(self._name)
+        table = await self._client._resource.Table(self._name)
+
+        await table.delete_item(Key={"_pk": key})
+
+    async def _insert(self, doc: dict) -> str:
+        """Insert a document with a generated UUID ``_pk``; return the id."""
+        await self._client.ensure_table(self._name)
+        table = await self._client._resource.Table(self._name)
+
+        id_ = str(uuid.uuid4())
+        await table.put_item(Item={**doc, "_pk": id_})
+        return id_
+
+    async def _update(self, key: str, patch: dict) -> None:
+        """Patch the document at ``_pk = key`` using a SET expression.
+
+        Only provided fields are updated; others are preserved.
+        ``_pk`` is never patched even if present in *patch*.
+        """
+        await self._client.ensure_table(self._name)
+        table = await self._client._resource.Table(self._name)
+
+        # Build SET expression: skip _pk to avoid overwriting the partition key.
+        fields = [(k, v) for k, v in patch.items() if k != "_pk"]
+        if not fields:
+            return
+
+        set_parts = []
+        expr_names: dict[str, str] = {}
+        expr_values: dict[str, object] = {}
+
+        for i, (field, value) in enumerate(fields):
+            name_alias = f"#attr{i}"
+            value_alias = f":val{i}"
+            set_parts.append(f"{name_alias} = {value_alias}")
+            expr_names[name_alias] = field
+            expr_values[value_alias] = value
+
+        update_expr = "SET " + ", ".join(set_parts)
+
+        await table.update_item(
+            Key={"_pk": key},
+            UpdateExpression=update_expr,
+            ExpressionAttributeNames=expr_names,
+            ExpressionAttributeValues=expr_values,
+        )
+
+    async def _find(self, ast: dict) -> Cursor:
+        """Find documents matching the filter AST.
+
+        Translates the AST to a DynamoDB FilterExpression, performs a full
+        table scan with automatic pagination, strips ``_pk`` from each item,
+        and wraps results in a :class:`~pynosqlc.core.Cursor`.
+        """
+        await self._client.ensure_table(self._name)
+        table = await self._client._resource.Table(self._name)
+
+        filter_expr, attr_names, attr_values = DynamoFilterTranslator.translate(ast)
+
+        scan_kwargs: dict = {}
+        if filter_expr is not None:
+            scan_kwargs["FilterExpression"] = filter_expr
+            scan_kwargs["ExpressionAttributeNames"] = attr_names
+            if attr_values:
+                scan_kwargs["ExpressionAttributeValues"] = attr_values
+
+        # Paginated scan.
+        items: list[dict] = []
+        resp = await table.scan(**scan_kwargs)
+        items.extend(resp.get("Items", []))
+
+        while "LastEvaluatedKey" in resp:
+            resp = await table.scan(
+                ExclusiveStartKey=resp["LastEvaluatedKey"],
+                **scan_kwargs,
+            )
+            items.extend(resp.get("Items", []))
+
+        # Strip the internal _pk field before returning to callers.
+        docs = [{k: v for k, v in item.items() if k != "_pk"} for item in items]
+        return Cursor(docs)

alt_python_pynosqlc_dynamodb-1.0.4/pynosqlc/dynamodb/dynamo_driver.py

@@ -0,0 +1,86 @@
+"""
+dynamo_driver.py — DynamoDriver: connects to DynamoDB via aioboto3.
+
+URL scheme: pynosqlc:dynamodb:<region>
+  e.g. pynosqlc:dynamodb:us-east-1
+
+Auto-registers with DriverManager on import.
+"""
+
+from __future__ import annotations
+
+import os
+
+import aioboto3
+
+from pynosqlc.core.driver import Driver
+from pynosqlc.core.driver_manager import DriverManager
+from pynosqlc.dynamodb.dynamo_client import DynamoClient
+
+
+class DynamoDriver(Driver):
+    """Driver that creates :class:`DynamoClient` instances.
+
+    URL prefix: ``pynosqlc:dynamodb:``
+    """
+
+    URL_PREFIX: str = "pynosqlc:dynamodb:"
+
+    def accepts_url(self, url: str) -> bool:
+        """Return ``True`` for ``'pynosqlc:dynamodb:'`` URLs."""
+        return isinstance(url, str) and url.startswith(self.URL_PREFIX)
+
+    async def connect(
+        self,
+        url: str,
+        properties: dict | None = None,
+    ) -> DynamoClient:
+        """Create and return an open :class:`DynamoClient`.
+
+        Args:
+            url: ``pynosqlc:dynamodb:<region>``
+            properties: optional dict; supports:
+                - ``endpoint``: override endpoint URL (e.g. for DynamoDB Local)
+                - ``aws_access_key_id``: AWS access key (optional)
+                - ``aws_secret_access_key``: AWS secret key (optional)
+
+        Returns:
+            An open :class:`DynamoClient`.
+        """
+        props = properties or {}
+
+        region = url[len(self.URL_PREFIX):]
+        if not region:
+            region = "us-east-1"
+
+        endpoint = props.get("endpoint") or os.environ.get("DYNAMODB_ENDPOINT")
+
+        session_kwargs: dict = {}
+        if endpoint:
+            # When using a local endpoint (DynamoDB Local / LocalStack) without
+            # real credentials, supply dummy values so boto3 does not raise a
+            # NoCredentialsError.
+            has_real_creds = (
+                os.environ.get("AWS_ACCESS_KEY_ID")
+                or os.environ.get("AWS_PROFILE")
+                or os.environ.get("AWS_CONTAINER_CREDENTIALS_RELATIVE_URI")
+                or os.environ.get("AWS_WEB_IDENTITY_TOKEN_FILE")
+            )
+            if not has_real_creds:
+                session_kwargs["aws_access_key_id"] = props.get(
+                    "aws_access_key_id", "dummy"
+                )
+                session_kwargs["aws_secret_access_key"] = props.get(
+                    "aws_secret_access_key", "dummy"
+                )
+
+        session = aioboto3.Session(**session_kwargs)
+
+        client = DynamoClient(url, session, region, endpoint, props)
+        await client._open()
+        return client
+
+
+# Auto-register on import — a single shared instance is sufficient.
+_driver = DynamoDriver()
+DriverManager.register_driver(_driver)

alt_python_pynosqlc_dynamodb-1.0.4/pynosqlc/dynamodb/dynamo_filter_translator.py

@@ -0,0 +1,210 @@
+"""
+dynamo_filter_translator.py — Translates a pynosqlc Filter AST to a DynamoDB
+FilterExpression triple.
+
+Returns
+-------
+tuple[str | None, dict, dict]
+    (filter_expression, expression_attribute_names, expression_attribute_values)
+
+When the AST is None or empty (no conditions), returns ``(None, {}, {})``.
+
+Design
+------
+A fresh ``_TranslatorState`` is created for each ``translate()`` call.  The
+state carries monotonically-increasing counters for field-name aliases
+(``#n0``, ``#n1``, …) and value aliases (``:v0``, ``:v1``, …) so that
+compound filters across multiple fields never produce collisions.
+
+All field references go through ``ExpressionAttributeNames`` to avoid
+DynamoDB reserved-word conflicts.
+
+Supported operators
+-------------------
+eq, ne, gt, gte, lt, lte, contains, in, nin, exists
+
+Composite node types
+--------------------
+and, or, not
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class DynamoFilterTranslator:
+    """Stateless translator from pynosqlc Filter AST to DynamoDB expression triple."""
+
+    @staticmethod
+    def translate(
+        ast: dict | None,
+    ) -> tuple[str | None, dict, dict]:
+        """Translate a Filter AST node to a DynamoDB expression triple.
+
+        Args:
+            ast: a Filter AST node, or ``None`` / empty dict (matches all).
+
+        Returns:
+            A tuple of ``(filter_expression, expression_attribute_names,
+            expression_attribute_values)``.  When the AST is falsy or has no
+            conditions, returns ``(None, {}, {})``.
+
+        Raises:
+            ValueError: if an unknown AST node type or operator is encountered.
+        """
+        if not ast:
+            return (None, {}, {})
+
+        # An 'and' node with an empty conditions list also means "match all"
+        if ast.get("type") in ("and", "or") and not ast.get("conditions"):
+            return (None, {}, {})
+
+        state = _TranslatorState()
+        expr = state._node(ast)
+        if expr is None:
+            return (None, {}, {})
+        return (expr, state.attr_names, state.attr_values)
+
+
+# ---------------------------------------------------------------------------
+# Internal stateful translator
+# ---------------------------------------------------------------------------
+
+class _TranslatorState:
+    """Carries mutable translation state for a single translate() call."""
+
+    def __init__(self) -> None:
+        self.name_idx: int = 0
+        self.value_idx: int = 0
+        self.attr_names: dict[str, str] = {}
+        self.attr_values: dict[str, Any] = {}
+
+    # ── Counter helpers ──────────────────────────────────────────────────────
+
+    def _field_alias(self, field: str) -> str:
+        """Allocate the next #nX alias for *field* and record the mapping."""
+        alias = f"#n{self.name_idx}"
+        self.attr_names[alias] = field
+        self.name_idx += 1
+        return alias
+
+    def _value_alias(self, value: Any) -> str:
+        """Allocate the next :vX alias for *value* and record the mapping."""
+        alias = f":v{self.value_idx}"
+        self.attr_values[alias] = value
+        self.value_idx += 1
+        return alias
+
+    # ── Node dispatcher ──────────────────────────────────────────────────────
+
+    def _node(self, ast: dict) -> str | None:
+        """Recursively translate an AST node to an expression string."""
+        node_type = ast.get("type")
+
+        if node_type == "and":
+            return self._and_node(ast)
+
+        if node_type == "or":
+            return self._or_node(ast)
+
+        if node_type == "not":
+            return self._not_node(ast)
+
+        if node_type == "condition":
+            return self._condition(ast)
+
+        raise ValueError(f"Unknown filter AST node type: {node_type!r}")
+
+    # ── Composite nodes ──────────────────────────────────────────────────────
+
+    def _and_node(self, ast: dict) -> str | None:
+        conditions = ast.get("conditions") or []
+        if not conditions:
+            return None
+        parts = [self._node(c) for c in conditions]
+        parts = [p for p in parts if p is not None]
+        if not parts:
+            return None
+        if len(parts) == 1:
+            return parts[0]
+        joined = " AND ".join(f"({p})" for p in parts)
+        return joined
+
+    def _or_node(self, ast: dict) -> str | None:
+        conditions = ast.get("conditions") or []
+        if not conditions:
+            return None
+        parts = [self._node(c) for c in conditions]
+        parts = [p for p in parts if p is not None]
+        if not parts:
+            return None
+        if len(parts) == 1:
+            return parts[0]
+        joined = " OR ".join(f"({p})" for p in parts)
+        return joined
+
+    def _not_node(self, ast: dict) -> str:
+        inner = self._node(ast["condition"])
+        return f"NOT ({inner})"
+
+    # ── Leaf condition ───────────────────────────────────────────────────────
+
+    def _condition(self, node: dict) -> str:
+        field: str = node["field"]
+        op: str = node["op"]
+        value: Any = node.get("value")
+
+        na = self._field_alias(field)
+
+        if op == "eq":
+            va = self._value_alias(value)
+            return f"{na} = {va}"
+
+        if op == "ne":
+            va = self._value_alias(value)
+            return f"{na} <> {va}"
+
+        if op == "gt":
+            va = self._value_alias(value)
+            return f"{na} > {va}"
+
+        if op == "gte":
+            va = self._value_alias(value)
+            return f"{na} >= {va}"
+
+        if op == "lt":
+            va = self._value_alias(value)
+            return f"{na} < {va}"
+
+        if op == "lte":
+            va = self._value_alias(value)
+            return f"{na} <= {va}"
+
+        if op == "contains":
+            va = self._value_alias(value)
+            return f"contains({na}, {va})"
+
+        if op == "exists":
+            if value:
+                return f"attribute_exists({na})"
+            else:
+                return f"attribute_not_exists({na})"
+
+        if op == "in":
+            # One OR clause per value; the field alias is shared
+            clauses = []
+            for v in value:
+                va = self._value_alias(v)
+                clauses.append(f"{na} = {va}")
+            return "(" + " OR ".join(clauses) + ")"
+
+        if op == "nin":
+            # One AND clause per value; the field alias is shared
+            clauses = []
+            for v in value:
+                va = self._value_alias(v)
+                clauses.append(f"{na} <> {va}")
+            return "(" + " AND ".join(clauses) + ")"
+
+        raise ValueError(f"Unknown filter operator: {op!r}")

alt_python_pynosqlc_dynamodb-1.0.4/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "alt-python-pynosqlc-dynamodb"
+version = "1.0.4"
+description = "DynamoDB driver for pynosqlc"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "alt-python-pynosqlc-core",
+    "aioboto3>=2.7",
+]
+authors = [
+    {name = "Craig Parravicini"},
+    {name = "Claude (Anthropic)"},
+]
+license = {text = "MIT"}
+keywords = ["nosql", "database", "async", "dynamodb", "aws", "driver"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/alt-python/pynosqlc"
+Repository = "https://github.com/alt-python/pynosqlc"
+Documentation = "https://github.com/alt-python/pynosqlc#getting-started"
+"Bug Tracker" = "https://github.com/alt-python/pynosqlc/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pynosqlc"]
+
+[tool.uv.sources]
+alt-python-pynosqlc-core = { workspace = true }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

alt_python_pynosqlc_dynamodb-1.0.4/tests/test_compliance.py

@@ -0,0 +1,62 @@
+"""
+test_compliance.py — DynamoDB driver compliance tests.
+
+Wires the shared pynosqlc.core compliance suite into the dynamodb package.
+Each test run gets a fresh DynamoClient connected to a real DynamoDB instance.
+
+Set DYNAMODB_ENDPOINT to override the default local endpoint (default: http://localhost:8000).
+Set DYNAMODB_REGION to override the default region (default: us-east-1).
+Tests are skipped automatically if DynamoDB Local is not reachable.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from pynosqlc.core import DriverManager
+from pynosqlc.core.testing import run_compliance
+import pynosqlc.dynamodb  # noqa: F401 — registers DynamoDriver on import
+from pynosqlc.dynamodb.dynamo_driver import _driver
+
+DYNAMODB_ENDPOINT = os.environ.get("DYNAMODB_ENDPOINT", "http://localhost:8000")
+DYNAMODB_REGION = os.environ.get("DYNAMODB_REGION", "us-east-1")
+DYNAMODB_URL = f"pynosqlc:dynamodb:{DYNAMODB_REGION}"
+
+
+async def _factory():
+    """Return a fresh, open DynamoClient for each test class fixture.
+
+    Clears and re-registers the driver, connects to DynamoDB, deletes any
+    leftover compliance tables so ensure_table recreates them cleanly, and
+    returns the client.
+
+    Skips the test if DynamoDB is not reachable.
+    """
+    DriverManager.clear()
+    DriverManager.register_driver(_driver)
+
+    try:
+        client = await DriverManager.get_client(
+            DYNAMODB_URL,
+            {"endpoint": DYNAMODB_ENDPOINT},
+        )
+    except Exception as e:
+        pytest.skip(f"DynamoDB not available: {e}")
+
+    # Delete compliance tables from any prior run so tests are isolated.
+    # Deleting the table and removing it from the cache forces ensure_table
+    # to recreate it fresh on first use — simpler than clearing items.
+    for table_name in ("compliance_kv", "compliance_doc", "compliance_find"):
+        try:
+            table = await client._resource.Table(table_name)
+            await table.delete()
+            client._table_cache.discard(table_name)
+        except Exception:
+            pass  # Table may not exist yet; that's fine.
+
+    return client
+
+
+run_compliance(_factory)

alt_python_pynosqlc_dynamodb-1.0.4/tests/test_dynamo_filter_translator.py

@@ -0,0 +1,310 @@
+"""
+Unit tests for DynamoFilterTranslator.
+
+Covers:
+- All 10 operators: eq, ne, gt, gte, lt, lte, contains, in, nin, exists
+- and-node with 1 condition unwraps (no wrapping parens)
+- and-node with 2 conditions → "(expr1) AND (expr2)"
+- or-node with 1 condition unwraps
+- or-node with 2 conditions → "(expr1) OR (expr2)"
+- not-node → "NOT (expr)"
+- None ast → (None, {}, {})
+- empty dict ast → (None, {}, {})
+- empty and/or conditions → (None, {}, {})
+- in_ multi-value expansion
+- nin multi-value expansion
+- exists(True) / exists(False) add no entry to attr_values
+- unknown op raises ValueError
+- unknown node type raises ValueError
+- compound filter uses distinct #nX and :vX aliases with no collisions
+"""
+
+import pytest
+
+from pynosqlc.dynamodb.dynamo_filter_translator import DynamoFilterTranslator
+
+translate = DynamoFilterTranslator.translate
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def cond(field, op, value=None):
+    """Convenience factory for condition AST nodes."""
+    node = {"type": "condition", "field": field, "op": op}
+    if value is not None:
+        node["value"] = value
+    return node
+
+
+# ---------------------------------------------------------------------------
+# None / empty input
+# ---------------------------------------------------------------------------
+
+class TestEmptyInput:
+    def test_none_returns_triple_none(self):
+        assert translate(None) == (None, {}, {})
+
+    def test_empty_dict_returns_triple_none(self):
+        assert translate({}) == (None, {}, {})
+
+    def test_empty_and_conditions_returns_triple_none(self):
+        assert translate({"type": "and", "conditions": []}) == (None, {}, {})
+
+    def test_empty_or_conditions_returns_triple_none(self):
+        assert translate({"type": "or", "conditions": []}) == (None, {}, {})
+
+
+# ---------------------------------------------------------------------------
+# All 10 operators on a regular field
+# ---------------------------------------------------------------------------
+
+class TestOperators:
+    def test_eq(self):
+        expr, names, values = translate(cond("name", "eq", "Alice"))
+        assert names == {"#n0": "name"}
+        assert values == {":v0": "Alice"}
+        assert expr == "#n0 = :v0"
+
+    def test_ne(self):
+        expr, names, values = translate(cond("status", "ne", "inactive"))
+        assert names == {"#n0": "status"}
+        assert values == {":v0": "inactive"}
+        assert expr == "#n0 <> :v0"
+
+    def test_gt(self):
+        expr, names, values = translate(cond("age", "gt", 18))
+        assert names == {"#n0": "age"}
+        assert values == {":v0": 18}
+        assert expr == "#n0 > :v0"
+
+    def test_gte(self):
+        expr, names, values = translate(cond("score", "gte", 90))
+        assert names == {"#n0": "score"}
+        assert values == {":v0": 90}
+        assert expr == "#n0 >= :v0"
+
+    def test_lt(self):
+        expr, names, values = translate(cond("price", "lt", 100))
+        assert names == {"#n0": "price"}
+        assert values == {":v0": 100}
+        assert expr == "#n0 < :v0"
+
+    def test_lte(self):
+        expr, names, values = translate(cond("rank", "lte", 5))
+        assert names == {"#n0": "rank"}
+        assert values == {":v0": 5}
+        assert expr == "#n0 <= :v0"
+
+    def test_contains(self):
+        expr, names, values = translate(cond("tags", "contains", "python"))
+        assert names == {"#n0": "tags"}
+        assert values == {":v0": "python"}
+        assert expr == "contains(#n0, :v0)"
+
+    def test_exists_true(self):
+        expr, names, values = translate(cond("email", "exists", True))
+        assert names == {"#n0": "email"}
+        assert values == {}
+        assert expr == "attribute_exists(#n0)"
+
+    def test_exists_false(self):
+        expr, names, values = translate(cond("deleted_at", "exists", False))
+        assert names == {"#n0": "deleted_at"}
+        assert values == {}
+        assert expr == "attribute_not_exists(#n0)"
+
+    def test_in(self):
+        expr, names, values = translate(cond("category", "in", ["a", "b", "c"]))
+        assert names == {"#n0": "category"}
+        assert values == {":v0": "a", ":v1": "b", ":v2": "c"}
+        assert expr == "(#n0 = :v0 OR #n0 = :v1 OR #n0 = :v2)"
+
+    def test_nin(self):
+        expr, names, values = translate(cond("role", "nin", ["admin", "root"]))
+        assert names == {"#n0": "role"}
+        assert values == {":v0": "admin", ":v1": "root"}
+        assert expr == "(#n0 <> :v0 AND #n0 <> :v1)"
+
+
+# ---------------------------------------------------------------------------
+# in / nin expansion
+# ---------------------------------------------------------------------------
+
+class TestInNinExpansion:
+    def test_in_single_value(self):
+        expr, names, values = translate(cond("x", "in", ["only"]))
+        assert expr == "(#n0 = :v0)"
+        assert values == {":v0": "only"}
+
+    def test_in_multi_value_aliases_present(self):
+        expr, names, values = translate(cond("x", "in", [1, 2, 3, 4]))
+        assert set(values.keys()) == {":v0", ":v1", ":v2", ":v3"}
+        assert list(values.values()) == [1, 2, 3, 4]
+        # All clauses reference the same field alias
+        assert "#n0 = :v0" in expr
+        assert "#n0 = :v3" in expr
+
+    def test_nin_produces_and_chain(self):
+        expr, names, values = translate(cond("status", "nin", ["a", "b"]))
+        assert "AND" in expr
+        assert "(#n0 <> :v0 AND #n0 <> :v1)" == expr
+
+    def test_nin_multi_value(self):
+        expr, names, values = translate(cond("x", "nin", [10, 20, 30]))
+        assert expr == "(#n0 <> :v0 AND #n0 <> :v1 AND #n0 <> :v2)"
+        assert values == {":v0": 10, ":v1": 20, ":v2": 30}
+
+
+# ---------------------------------------------------------------------------
+# exists does not add to attr_values
+# ---------------------------------------------------------------------------
+
+class TestExistsNoValue:
+    def test_exists_true_no_value_alias(self):
+        _, _, values = translate(cond("field", "exists", True))
+        assert values == {}
+
+    def test_exists_false_no_value_alias(self):
+        _, _, values = translate(cond("field", "exists", False))
+        assert values == {}
+
+
+# ---------------------------------------------------------------------------
+# and-node
+# ---------------------------------------------------------------------------
+
+class TestAndNode:
+    def test_single_condition_unwraps(self):
+        node = {"type": "and", "conditions": [cond("x", "eq", 1)]}
+        expr, names, values = translate(node)
+        assert expr == "#n0 = :v0"
+        assert names == {"#n0": "x"}
+        assert values == {":v0": 1}
+
+    def test_two_conditions_produces_and(self):
+        node = {
+            "type": "and",
+            "conditions": [cond("x", "eq", 1), cond("y", "gt", 0)],
+        }
+        expr, names, values = translate(node)
+        assert expr == "(#n0 = :v0) AND (#n1 > :v1)"
+        assert names == {"#n0": "x", "#n1": "y"}
+        assert values == {":v0": 1, ":v1": 0}
+
+    def test_empty_conditions_returns_none(self):
+        node = {"type": "and", "conditions": []}
+        assert translate(node) == (None, {}, {})
+
+
+# ---------------------------------------------------------------------------
+# or-node
+# ---------------------------------------------------------------------------
+
+class TestOrNode:
+    def test_single_condition_unwraps(self):
+        node = {"type": "or", "conditions": [cond("x", "eq", 1)]}
+        expr, names, values = translate(node)
+        assert expr == "#n0 = :v0"
+
+    def test_two_conditions_produces_or(self):
+        node = {
+            "type": "or",
+            "conditions": [cond("a", "lt", 5), cond("b", "gte", 10)],
+        }
+        expr, names, values = translate(node)
+        assert expr == "(#n0 < :v0) OR (#n1 >= :v1)"
+        assert names == {"#n0": "a", "#n1": "b"}
+        assert values == {":v0": 5, ":v1": 10}
+
+    def test_empty_conditions_returns_none(self):
+        node = {"type": "or", "conditions": []}
+        assert translate(node) == (None, {}, {})
+
+
+# ---------------------------------------------------------------------------
+# not-node
+# ---------------------------------------------------------------------------
+
+class TestNotNode:
+    def test_not_wraps_with_not(self):
+        node = {"type": "not", "condition": cond("active", "eq", True)}
+        expr, names, values = translate(node)
+        assert expr == "NOT (#n0 = :v0)"
+        assert names == {"#n0": "active"}
+        assert values == {":v0": True}
+
+    def test_not_with_and_inner(self):
+        inner = {
+            "type": "and",
+            "conditions": [cond("x", "gt", 0), cond("y", "lt", 10)],
+        }
+        node = {"type": "not", "condition": inner}
+        expr, _, _ = translate(node)
+        assert expr == "NOT ((#n0 > :v0) AND (#n1 < :v1))"
+
+
+# ---------------------------------------------------------------------------
+# Error cases
+# ---------------------------------------------------------------------------
+
+class TestErrors:
+    def test_unknown_op_raises_value_error(self):
+        with pytest.raises(ValueError, match="Unknown filter operator"):
+            translate(cond("x", "regex", ".*"))
+
+    def test_unknown_node_type_raises_value_error(self):
+        with pytest.raises(ValueError, match="Unknown filter AST node type"):
+            translate({"type": "xor", "conditions": []})
+
+
+# ---------------------------------------------------------------------------
+# Global counter: no alias collisions in compound filters
+# ---------------------------------------------------------------------------
+
+class TestGlobalCounters:
+    def test_distinct_field_and_value_aliases(self):
+        """A compound filter over three distinct fields must use #n0/#n1/#n2
+        and :v0/:v1/:v2 with no collisions."""
+        node = {
+            "type": "and",
+            "conditions": [
+                cond("alpha", "eq", 1),
+                cond("beta", "gt", 2),
+                cond("gamma", "lte", 3),
+            ],
+        }
+        expr, names, values = translate(node)
+        # Three distinct field aliases
+        assert set(names.keys()) == {"#n0", "#n1", "#n2"}
+        assert names["#n0"] == "alpha"
+        assert names["#n1"] == "beta"
+        assert names["#n2"] == "gamma"
+        # Three distinct value aliases
+        assert set(values.keys()) == {":v0", ":v1", ":v2"}
+        assert values[":v0"] == 1
+        assert values[":v1"] == 2
+        assert values[":v2"] == 3
+        assert expr == "(#n0 = :v0) AND (#n1 > :v1) AND (#n2 <= :v2)"
+
+    def test_in_then_eq_no_collision(self):
+        """in_ expands multiple :vX aliases; a subsequent field must continue
+        from the correct counter, not restart at :v0."""
+        node = {
+            "type": "and",
+            "conditions": [
+                cond("status", "in", ["a", "b"]),
+                cond("age", "gt", 18),
+            ],
+        }
+        expr, names, values = translate(node)
+        # status → #n0, age → #n1
+        assert names["#n0"] == "status"
+        assert names["#n1"] == "age"
+        # :v0 and :v1 consumed by in_, :v2 used for age
+        assert values[":v0"] == "a"
+        assert values[":v1"] == "b"
+        assert values[":v2"] == 18
+        assert "(#n0 = :v0 OR #n0 = :v1)" in expr
+        assert "#n1 > :v2" in expr