alt-python-pynosqlc-dynamodb 1.0.4__py3-none-any.whl

alt_python_pynosqlc_dynamodb-1.0.4.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+pynosqlc/dynamodb/__init__.py,sha256=g8b_pg2wDOiydXSGfakMTbekgIKi701pydhA0UdsxT0,631
+pynosqlc/dynamodb/dynamo_client.py,sha256=DiSa53aEryKR58jVrqZvx3J8k0x0R7SSVn3j0xLOjlE,3803
+pynosqlc/dynamodb/dynamo_collection.py,sha256=FdDZn3SvasvMQKFSurzgEi5EywJCITOKiqMardLP_KM,4901
+pynosqlc/dynamodb/dynamo_driver.py,sha256=mlIKsiKg_TWUp3_Dc65js7YNr_bU4w-QQN25f7wlsMw,2731
+pynosqlc/dynamodb/dynamo_filter_translator.py,sha256=n4pDOPnhDnIFYhJx--fPdRJnsAHkm_kzf6IDkl2GRH0,7043
+alt_python_pynosqlc_dynamodb-1.0.4.dist-info/METADATA,sha256=FjZ0z-4ybcg_BYdh9COEXcqOoTpu9BexKuvKN5OAutE,2695
+alt_python_pynosqlc_dynamodb-1.0.4.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+alt_python_pynosqlc_dynamodb-1.0.4.dist-info/RECORD,,

alt_python_pynosqlc_dynamodb-1.0.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

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",
+]

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)

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)

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)

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}")