modmex-lambda 0.5.2__tar.gz → 0.5.3__tar.gz

{modmex_lambda-0.5.2 → modmex_lambda-0.5.3}/PKG-INFO

@@ -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.3/modmex_lambda/persistence/__init__.py

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

modmex_lambda-0.5.3/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-0.5.3/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-0.5.3/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 → modmex_lambda-0.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modmex-lambda"
-version = "0.5.2"
+version = "0.5.3"
 description = "Ultra-lightweight AWS Lambda utilities for API Gateway routing and event handling."
 readme = "README.md"
 requires-python = ">=3.10,<4.0"

modmex_lambda-0.5.3/tests/persistence/__init__.py

@@ -0,0 +1 @@
+

modmex_lambda-0.5.3/tests/persistence/test_dynamodb_keys.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pytest
+
+from modmex_lambda.persistence.dynamodb import (
+    AggregateKeyStrategy,
+    KeyStrategy,
+    SingleEntityKeyStrategy,
+    TenantPartitionKeyStrategy,
+    TenantScopedSortKeyStrategy,
+)
+
+
+@dataclass
+class Thing:
+    id: str
+    tenant_id: str | None = None
+    aggregate_id: str | None = None
+    account_id: str | None = None
+    order_id: str | None = None
+
+
+def test_key_strategy_is_abstract() -> None:
+    with pytest.raises(TypeError):
+        KeyStrategy()
+
+
+def test_single_entity_key_strategy_uses_id_as_pk_and_discriminator_as_sk() -> None:
+    strategy = SingleEntityKeyStrategy("thing")
+
+    assert strategy.key_for_id("thing-1") == {"pk": "thing-1", "sk": "thing"}
+    assert strategy.key_for_entity(Thing(id="thing-2")) == {"pk": "thing-2", "sk": "thing"}
+    assert strategy.key_for_entity({"id": "thing-3"}) == {"pk": "thing-3", "sk": "thing"}
+
+
+def test_tenant_scoped_sort_key_strategy_uses_entity_id_and_tenant_scoped_sk() -> None:
+    strategy = TenantScopedSortKeyStrategy("thing")
+
+    assert strategy.key_for_id("thing-1", tenant_id="acme") == {
+        "pk": "thing-1",
+        "sk": "thing#acme",
+    }
+    assert strategy.key_for_entity(Thing(id="thing-2", tenant_id="modmex")) == {
+        "pk": "thing-2",
+        "sk": "thing#modmex",
+    }
+    assert strategy.key_for_entity(Thing(id="thing-3", tenant_id="ignored"), tenant_id="acme") == {
+        "pk": "thing-3",
+        "sk": "thing#acme",
+    }
+
+
+def test_tenant_scoped_sort_key_strategy_supports_custom_field_and_separator() -> None:
+    strategy = TenantScopedSortKeyStrategy("thing", separator=":", tenant_field="account_id")
+
+    assert strategy.key_for_entity(Thing(id="thing-1", account_id="acct-1")) == {
+        "pk": "thing-1",
+        "sk": "thing:acct-1",
+    }
+
+
+def test_tenant_partition_key_strategy_uses_tenant_as_pk_and_entity_scoped_sk() -> None:
+    strategy = TenantPartitionKeyStrategy("thing")
+
+    assert strategy.key_for_id("thing-1", tenant_id="acme") == {
+        "pk": "acme",
+        "sk": "thing#thing-1",
+    }
+    assert strategy.key_for_entity(Thing(id="thing-2", tenant_id="modmex")) == {
+        "pk": "modmex",
+        "sk": "thing#thing-2",
+    }
+
+
+def test_tenant_partition_key_strategy_supports_custom_field_and_separator() -> None:
+    strategy = TenantPartitionKeyStrategy("thing", separator=":", tenant_field="account_id")
+
+    assert strategy.key_for_entity(Thing(id="thing-1", account_id="acct-1")) == {
+        "pk": "acct-1",
+        "sk": "thing:thing-1",
+    }
+
+
+def test_aggregate_key_strategy_uses_aggregate_pk_and_entity_sk() -> None:
+    strategy = AggregateKeyStrategy("order", "item")
+
+    assert strategy.key_for_id("item-1", aggregate_id="order-1") == {
+        "pk": "order#order-1",
+        "sk": "item#item-1",
+    }
+    assert strategy.key_for_entity(Thing(id="item-2", aggregate_id="order-2")) == {
+        "pk": "order#order-2",
+        "sk": "item#item-2",
+    }
+
+
+def test_aggregate_key_strategy_supports_custom_field_and_separator() -> None:
+    strategy = AggregateKeyStrategy("order", "item", separator=":", aggregate_field="order_id")
+
+    assert strategy.key_for_entity(Thing(id="item-1", order_id="order-1")) == {
+        "pk": "order:order-1",
+        "sk": "item:item-1",
+    }
+
+
+def test_required_context_errors_are_explicit() -> None:
+    strategy = TenantPartitionKeyStrategy("thing")
+
+    with pytest.raises(KeyError, match="tenant_id"):
+        strategy.key_for_id("thing-1")
+
+    with pytest.raises(AttributeError, match="tenant_id"):
+        strategy.key_for_entity(Thing(id="thing-1"))

modmex_lambda-0.5.3/tests/persistence/test_dynamodb_stream_fields.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import pytest
+
+from modmex_lambda.persistence.dynamodb import (
+    DefaultStreamFieldsStrategy,
+    StreamFieldsStrategy,
+    stream_entity_fields,
+)
+
+
+def test_stream_entity_fields_builds_standard_stream_contract_fields(monkeypatch) -> None:
+    monkeypatch.setenv("REGION", "us-west-2")
+
+    fields = stream_entity_fields(
+        "thing",
+        timestamp=1548967022000,
+        deleted=True,
+        latched=False,
+        ttl=1549053422,
+    )
+
+    assert fields == {
+        "discriminator": "thing",
+        "deleted": True,
+        "latched": False,
+        "ttl": 1549053422,
+        "awsregion": "us-west-2",
+        "timestamp": 1548967022000,
+    }
+
+
+def test_stream_entity_fields_allows_explicit_region(monkeypatch) -> None:
+    monkeypatch.setenv("REGION", "us-west-2")
+
+    fields = stream_entity_fields(
+        "thing",
+        timestamp=1548967022000,
+        awsregion="us-east-1",
+    )
+
+    assert fields == {
+        "discriminator": "thing",
+        "deleted": None,
+        "latched": False,
+        "ttl": None,
+        "awsregion": "us-east-1",
+        "timestamp": 1548967022000,
+    }
+
+
+def test_stream_fields_strategy_is_abstract() -> None:
+    with pytest.raises(TypeError):
+        StreamFieldsStrategy()
+
+
+def test_default_stream_fields_strategy_builds_save_fields(monkeypatch) -> None:
+    monkeypatch.setenv("REGION", "us-west-2")
+    strategy = DefaultStreamFieldsStrategy("thing")
+
+    fields = strategy.fields_for_save(
+        {
+            "pk": "thing-1",
+            "sk": "thing",
+            "name": "Desk",
+            "discriminator": "wrong",
+            "timestamp": 1,
+        },
+        timestamp=1548967022000,
+        ttl=1549053422,
+    )
+
+    assert fields == {
+        "name": "Desk",
+        "discriminator": "thing",
+        "deleted": None,
+        "latched": False,
+        "ttl": 1549053422,
+        "awsregion": "us-west-2",
+        "timestamp": 1548967022000,
+    }
+
+
+def test_default_stream_fields_strategy_builds_delete_fields(monkeypatch) -> None:
+    monkeypatch.setenv("REGION", "us-west-2")
+    strategy = DefaultStreamFieldsStrategy("thing")
+
+    fields = strategy.fields_for_delete(
+        {
+            "pk": "thing-1",
+            "sk": "thing",
+            "name": "Desk",
+            "deleted": None,
+        },
+        timestamp=1548967022000,
+    )
+
+    assert fields == {
+        "name": "Desk",
+        "discriminator": "thing",
+        "deleted": True,
+        "latched": False,
+        "ttl": None,
+        "awsregion": "us-west-2",
+        "timestamp": 1548967022000,
+    }
+
+
+def test_default_stream_fields_strategy_can_calculate_timestamp(monkeypatch) -> None:
+    monkeypatch.setattr("modmex_lambda.persistence.dynamodb.stream_fields.now", lambda: 1548967022000)
+    monkeypatch.setenv("REGION", "us-west-2")
+    strategy = DefaultStreamFieldsStrategy("thing")
+
+    fields = strategy.fields_for_save({"name": "Desk"})
+
+    assert fields["timestamp"] == 1548967022000
+    assert fields["ttl"] is None
+
+
+def test_default_stream_fields_strategy_can_calculate_ttl_from_configuration(monkeypatch) -> None:
+    monkeypatch.setattr("modmex_lambda.persistence.dynamodb.stream_fields.now", lambda: 1000)
+    strategy = DefaultStreamFieldsStrategy("thing", use_ttl=True, days_ttl=2)
+
+    fields = strategy.fields_for_save({"name": "Desk"})
+
+    assert fields["timestamp"] == 1000
+    assert fields["ttl"] == 172801