modmex-lambda 0.5.2__py3-none-any.whl → 0.5.3__py3-none-any.whl

modmex_lambda/persistence/__init__.py

@@ -0,0 +1,2 @@
+"""Persistence helpers for common modmex-lambda application patterns."""
+

modmex_lambda/persistence/dynamodb/__init__.py

@@ -0,0 +1,25 @@
+"""DynamoDB persistence helpers."""
+
+from modmex_lambda.persistence.dynamodb.keys import (
+    AggregateKeyStrategy,
+    KeyStrategy,
+    SingleEntityKeyStrategy,
+    TenantPartitionKeyStrategy,
+    TenantScopedSortKeyStrategy,
+)
+from modmex_lambda.persistence.dynamodb.stream_fields import (
+    DefaultStreamFieldsStrategy,
+    StreamFieldsStrategy,
+    stream_entity_fields,
+)
+
+__all__ = [
+    "AggregateKeyStrategy",
+    "KeyStrategy",
+    "SingleEntityKeyStrategy",
+    "DefaultStreamFieldsStrategy",
+    "StreamFieldsStrategy",
+    "TenantPartitionKeyStrategy",
+    "TenantScopedSortKeyStrategy",
+    "stream_entity_fields",
+]

modmex_lambda/persistence/dynamodb/keys.py

@@ -0,0 +1,133 @@
+"""Reusable DynamoDB key strategies.
+
+These helpers keep key-shaping decisions explicit while letting repositories
+stay focused on persistence behavior.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+
+class KeyStrategy(ABC):
+    """Build DynamoDB primary keys for ids and entities."""
+
+    @abstractmethod
+    def key_for_id(self, entity_id: Any, **context: Any) -> dict[str, str]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def key_for_entity(self, entity: Any, **context: Any) -> dict[str, str]:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True)
+class SingleEntityKeyStrategy(KeyStrategy):
+    """Use the entity id as pk and a fixed discriminator as sk."""
+
+    discriminator: str
+
+    def key_for_id(self, entity_id: Any, **context: Any) -> dict[str, str]:
+        return {
+            "pk": str(entity_id),
+            "sk": self.discriminator,
+        }
+
+    def key_for_entity(self, entity: Any, **context: Any) -> dict[str, str]:
+        return self.key_for_id(_entity_attr(entity, "id"), **context)
+
+
+@dataclass(frozen=True)
+class TenantScopedSortKeyStrategy(KeyStrategy):
+    """Use entity id as pk and discriminator plus tenant id as sk."""
+
+    discriminator: str
+    separator: str = "#"
+    tenant_field: str = "tenant_id"
+
+    def key_for_id(self, entity_id: Any, **context: Any) -> dict[str, str]:
+        tenant_id = _context_value(context, self.tenant_field)
+        return {
+            "pk": str(entity_id),
+            "sk": self._sort_key(tenant_id),
+        }
+
+    def key_for_entity(self, entity: Any, **context: Any) -> dict[str, str]:
+        tenant_id = _context_or_entity_value(context, entity, self.tenant_field)
+        return self.key_for_id(_entity_attr(entity, "id"), **{self.tenant_field: tenant_id})
+
+    def _sort_key(self, tenant_id: Any) -> str:
+        return f"{self.discriminator}{self.separator}{tenant_id}"
+
+
+@dataclass(frozen=True)
+class TenantPartitionKeyStrategy(KeyStrategy):
+    """Use tenant id as pk and discriminator plus entity id as sk."""
+
+    discriminator: str
+    separator: str = "#"
+    tenant_field: str = "tenant_id"
+
+    def key_for_id(self, entity_id: Any, **context: Any) -> dict[str, str]:
+        tenant_id = _context_value(context, self.tenant_field)
+        return {
+            "pk": str(tenant_id),
+            "sk": self._sort_key(entity_id),
+        }
+
+    def key_for_entity(self, entity: Any, **context: Any) -> dict[str, str]:
+        tenant_id = _context_or_entity_value(context, entity, self.tenant_field)
+        return self.key_for_id(_entity_attr(entity, "id"), **{self.tenant_field: tenant_id})
+
+    def _sort_key(self, entity_id: Any) -> str:
+        return f"{self.discriminator}{self.separator}{entity_id}"
+
+
+@dataclass(frozen=True)
+class AggregateKeyStrategy(KeyStrategy):
+    """Use aggregate id as pk and entity name plus entity id as sk."""
+
+    aggregate_name: str
+    entity_name: str
+    separator: str = "#"
+    aggregate_field: str = "aggregate_id"
+
+    def key_for_id(self, entity_id: Any, **context: Any) -> dict[str, str]:
+        aggregate_id = _context_value(context, self.aggregate_field)
+        return {
+            "pk": f"{self.aggregate_name}{self.separator}{aggregate_id}",
+            "sk": f"{self.entity_name}{self.separator}{entity_id}",
+        }
+
+    def key_for_entity(self, entity: Any, **context: Any) -> dict[str, str]:
+        aggregate_id = _context_or_entity_value(context, entity, self.aggregate_field)
+        return self.key_for_id(_entity_attr(entity, "id"), **{self.aggregate_field: aggregate_id})
+
+
+def _context_value(context: dict[str, Any], field_name: str) -> Any:
+    if field_name in context and context[field_name] is not None:
+        return context[field_name]
+    raise KeyError(f"Missing required key context: {field_name}")
+
+
+def _context_or_entity_value(context: dict[str, Any], entity: Any, field_name: str) -> Any:
+    if field_name in context and context[field_name] is not None:
+        return context[field_name]
+    value = _entity_attr(entity, field_name)
+    if value is not None:
+        return value
+    raise AttributeError(f"Entity is missing required field: {field_name}")
+
+
+def _entity_attr(entity: Any, field_name: str) -> Any:
+    if isinstance(entity, dict):
+        try:
+            return entity[field_name]
+        except KeyError as exc:
+            raise AttributeError(f"Entity is missing required field: {field_name}") from exc
+    try:
+        return getattr(entity, field_name)
+    except AttributeError as exc:
+        raise AttributeError(f"Entity is missing required field: {field_name}") from exc

modmex_lambda/persistence/dynamodb/stream_fields.py

@@ -0,0 +1,121 @@
+"""Fields used by modmex-lambda stream-compatible DynamoDB items."""
+
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+from modmex_lambda.stream.utils.time import now, ttl as stream_ttl
+
+
+def stream_entity_fields(
+    discriminator: str,
+    *,
+    timestamp: int,
+    deleted: bool | None = None,
+    latched: bool = False,
+    ttl: int | None = None,
+    awsregion: str | None = None,
+) -> dict[str, Any]:
+    """Build standard fields consumed by modmex-lambda stream processors."""
+
+    fields = {
+        "discriminator": discriminator,
+        "deleted": deleted,
+        "latched": latched,
+        "ttl": ttl,
+        "awsregion": awsregion if awsregion is not None else os.getenv("REGION"),
+        "timestamp": timestamp,
+    }
+    return fields
+
+
+class StreamFieldsStrategy(ABC):
+    """Build stream-compatible item fields for DynamoDB writes."""
+
+    @abstractmethod
+    def fields_for_save(
+        self,
+        data: dict[str, Any],
+        *,
+        timestamp: int | None = None,
+        ttl: int | None = None,
+    ) -> dict[str, Any]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def fields_for_delete(
+        self,
+        data: dict[str, Any],
+        *,
+        timestamp: int | None = None,
+        ttl: int | None = None,
+    ) -> dict[str, Any]:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True)
+class DefaultStreamFieldsStrategy(StreamFieldsStrategy):
+    """Default stream field contract used by modmex-lambda stream processors."""
+
+    discriminator: str
+    key_fields: tuple[str, ...] = field(default=("pk", "sk"))
+    use_ttl: bool = False
+    days_ttl: int = 30
+
+    def fields_for_save(
+        self,
+        data: dict[str, Any],
+        *,
+        timestamp: int | None = None,
+        ttl: int | None = None,
+    ) -> dict[str, Any]:
+        timestamp = self._timestamp(timestamp)
+        return {
+            **self._without_key_fields(data),
+            **stream_entity_fields(
+                self.discriminator,
+                timestamp=timestamp,
+                deleted=None,
+                latched=False,
+                ttl=self._ttl(timestamp, ttl),
+            ),
+        }
+
+    def fields_for_delete(
+        self,
+        data: dict[str, Any],
+        *,
+        timestamp: int | None = None,
+        ttl: int | None = None,
+    ) -> dict[str, Any]:
+        timestamp = self._timestamp(timestamp)
+        return {
+            **self._without_key_fields(data),
+            **stream_entity_fields(
+                self.discriminator,
+                timestamp=timestamp,
+                deleted=True,
+                latched=False,
+                ttl=self._ttl(timestamp, ttl),
+            ),
+        }
+
+    def _without_key_fields(self, data: dict[str, Any]) -> dict[str, Any]:
+        return {
+            key: value
+            for key, value in data.items()
+            if key not in self.key_fields
+        }
+
+    def _timestamp(self, timestamp: int | None) -> int:
+        return timestamp if timestamp is not None else now()
+
+    def _ttl(self, timestamp: int, ttl: int | None) -> int | None:
+        if ttl is not None:
+            return ttl
+        if self.use_ttl:
+            return stream_ttl(timestamp, self.days_ttl)
+        return None

{modmex_lambda-0.5.2.dist-info → modmex_lambda-0.5.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modmex-lambda
-Version: 0.5.2
+Version: 0.5.3
 Summary: Ultra-lightweight AWS Lambda utilities for API Gateway routing and event handling.
 Author: Modmex
 License: MIT

{modmex_lambda-0.5.2.dist-info → modmex_lambda-0.5.3.dist-info}/RECORD

@@ -55,6 +55,10 @@ modmex_lambda/event_handler/dependencies/dependency_middleware.py,sha256=c_N7Ugt
 modmex_lambda/event_handler/dependencies/depends.py,sha256=pJ1rcMoA99vSaQTPxJ0zkYppPDKU0-lm9URc9Gifmdw,7110
 modmex_lambda/event_handler/dependencies/params.py,sha256=bc208GHiXCfm1V-GLeIMm8-ypZ8P8Q9qUKQkK2Vh1Fg,10085
 modmex_lambda/event_handler/dependencies/types.py,sha256=5VA8zl-EjQDNKXOrNT7sRv_vNs40Lz8aMP-sf-lf8sk,376
+modmex_lambda/persistence/__init__.py,sha256=oa4FHCvitEkoagJ059jGATj6GSm-maazzf_QNi4WdQs,74
+modmex_lambda/persistence/dynamodb/__init__.py,sha256=3zryiwKKSb-eLO82Mh3bFJAgBXco4hjgSFx32Vbm0F0,633
+modmex_lambda/persistence/dynamodb/keys.py,sha256=_vjpHYzRmi1OmCzHaJNpq8vefjH7kq8yxE1t7RhmmQg,4676
+modmex_lambda/persistence/dynamodb/stream_fields.py,sha256=b6wRRq6Ag9W59GCI8616IlBQXeBIwj5RKEQE0lfD4YE,3323
 modmex_lambda/shared/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 modmex_lambda/shared/cookies.py,sha256=E2hTuht5_Xljw9zOQLW6vjsOWEpQSIqD2D3Tl1Co_s0,2076
 modmex_lambda/shared/headers_serializer.py,sha256=Ao-wpx0cmy9E2ACrh7R7RIDUF0h24gax1AMtY_MjIWQ,2505
@@ -132,7 +136,7 @@ modmex_lambda/stream/utils/time.py,sha256=dnsL2xeWpa1FXm2p8y9rWXtICMBlCBkgLaJ_en
 modmex_lambda/stream/utils/uow.py,sha256=8WSPVE7AiHInkFDfBEeKOvdirY6GAgBoS7qkF1f1JVM,3207
 modmex_lambda/stream/utils/data_classes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 modmex_lambda/stream/utils/data_classes/dynamodb.py,sha256=h_7MtUyRkvvV1r2QECrRDu7RR4Hh94SwSjc_8K2_XGM,363
-modmex_lambda-0.5.2.dist-info/METADATA,sha256=s5iPsfZFyFDYMZLUn7LpP5py9ePfax9KcHevPN5AyFw,31809
-modmex_lambda-0.5.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-modmex_lambda-0.5.2.dist-info/licenses/LICENSE,sha256=_C2TDTOsYeJvE4vn9VB51laKvleBKbdNnn96wJVtXhQ,1063
-modmex_lambda-0.5.2.dist-info/RECORD,,
+modmex_lambda-0.5.3.dist-info/METADATA,sha256=WEuUKYajpwTKaggo3RPcyEoT6qIjPBd0fnkvzsPJ1SU,31809
+modmex_lambda-0.5.3.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+modmex_lambda-0.5.3.dist-info/licenses/LICENSE,sha256=_C2TDTOsYeJvE4vn9VB51laKvleBKbdNnn96wJVtXhQ,1063
+modmex_lambda-0.5.3.dist-info/RECORD,,