finalsa-common-models 2.0.3__py3-none-any.whl → 2.1.0__py3-none-any.whl

finalsa/common/models/__init__.py

@@ -3,12 +3,18 @@ from finalsa.common.models.models import (
     AsyncMeta,
     Authorization,
     HttpMeta,
+    PaginationMeta,
+    PaginationRequest,
+    PaginationResponse,
     SqsReponse,
     parse_sns_message_attributes,
     parse_sqs_message_attributes,
     to_sqs_message_attributes,
     to_sns_message_attributes,
 )
+from finalsa.common.models.exceptions import (
+    BaseDomainException,
+)
 
 
 __all__ = [
@@ -16,9 +22,13 @@ __all__ = [
     "AsyncMeta",
     "Authorization",
     "HttpMeta",
+    "PaginationMeta",
+    "PaginationRequest",
+    "PaginationResponse",
     "SqsReponse",
     "parse_sns_message_attributes",
     "parse_sqs_message_attributes",
     "to_sqs_message_attributes",
     "to_sns_message_attributes",
+    "BaseDomainException",
 ]

finalsa/common/models/exceptions/__init__.py

@@ -0,0 +1,5 @@
+from .base_domain_exception import BaseDomainException
+
+__all__ = [
+    "BaseDomainException",
+]

finalsa/common/models/exceptions/base_domain_exception.py

@@ -0,0 +1,43 @@
+from typing import Optional
+import functools
+
+
+def from_camel_case_to_snake_case(name: str) -> str:
+    """
+    Convert a camelCase string to snake_case.
+    """
+    if not name:
+        return name
+    result = []
+    for char in name:
+        if char.isupper():
+            if result:
+                result.append('_')
+            result.append(char.lower())
+        else:
+            result.append(char)
+    return ''.join(result)
+
+
+class BaseDomainException(Exception):
+    response_code = 500
+
+    @classmethod
+    @property
+    @functools.lru_cache(maxsize=None)
+    def __class_name__(cls):
+        return from_camel_case_to_snake_case(cls.__name__)
+
+    def __init__(
+        self,
+        message: str,
+        response_code: Optional[int] = 500,
+        name: Optional[str] = None
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.response_code = response_code
+        if name is None:
+            self.name = self.__class_name__
+        else:
+            self.name = name

finalsa/common/models/models/__init__.py

@@ -1,12 +1,16 @@
 from .functions import parse_sns_message_attributes, parse_sqs_message_attributes, to_sqs_message_attributes, to_sns_message_attributes
 from .sqs_response import SqsReponse
 from .meta import Meta, AsyncMeta, Authorization, HttpMeta
+from .pagination import PaginationMeta, PaginationRequest, PaginationResponse
 
 __all__ = [
     "Meta",
     "AsyncMeta",
     "Authorization",
     "HttpMeta",
+    "PaginationMeta",
+    "PaginationRequest",
+    "PaginationResponse",
     "SqsReponse",
     "parse_sns_message_attributes",
     "parse_sqs_message_attributes",

finalsa/common/models/models/pagination.py

@@ -0,0 +1,99 @@
+from typing import Any, Dict, Generic, Optional, Sequence, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+ItemT = TypeVar("ItemT")
+
+
+class PaginationRequest(BaseModel):
+    """Represents the pagination related query params for HTTP GET requests."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    limit: Optional[int] = Field(
+        default=None,
+        gt=0,
+        description="Maximum number of elements to evaluate in a single page.",
+    )
+    exclusive_start_key: Optional[Dict[str, Any]] = Field(
+        default=None,
+        alias="from",
+        description="DynamoDB ExclusiveStartKey encoded in the request.",
+    )
+
+
+class PaginationMeta(BaseModel):
+    """Generic metadata that can be attached to a paginated response."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    total: int
+    approx_pages: int
+    limit: Optional[int] = None
+    from_: Optional[int] = Field(default=None, alias="from")
+    to: Optional[int] = None
+
+
+class PaginationResponse(BaseModel, Generic[ItemT]):
+    """
+    Generic response wrapper for paginated HTTP GET endpoints.
+
+    The model keeps track of the DynamoDB ExclusiveStartKey used to fetch
+    the current page and the LastEvaluatedKey required to fetch the next one.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    items: Sequence[ItemT]
+    count: int = Field(
+        description="Number of elements returned in the current page.",
+    )
+    limit: Optional[int] = Field(
+        default=None, description="Limit applied when retrieving this page."
+    )
+    exclusive_start_key: Optional[Dict[str, Any]] = Field(
+        default=None,
+        alias="from",
+        description="ExclusiveStartKey used to produce the current page.",
+    )
+    last_evaluated_key: Optional[Dict[str, Any]] = Field(
+        default=None,
+        alias="end",
+        description="DynamoDB LastEvaluatedKey to request the next page.",
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def ensure_count(cls, data: Any) -> Any:
+        """
+        Automatically populate count when only items are provided.
+
+        This makes it easier to build the response from raw query results.
+        """
+        if isinstance(data, dict) and "count" not in data and "items" in data:
+            try:
+                data["count"] = len(data["items"])
+            except TypeError:
+                # When items is not sized we let validation handle the error later.
+                pass
+        return data
+
+    @classmethod
+    def from_items(
+        cls,
+        items: Sequence[ItemT],
+        *,
+        limit: Optional[int] = None,
+        exclusive_start_key: Optional[Dict[str, Any]] = None,
+        last_evaluated_key: Optional[Dict[str, Any]] = None,
+    ) -> "PaginationResponse[ItemT]":
+        """
+        Helper constructor that infers the count from the provided collection.
+        """
+        return cls(
+            items=items,
+            limit=limit,
+            exclusive_start_key=exclusive_start_key,
+            last_evaluated_key=last_evaluated_key,
+        )

{finalsa_common_models-2.0.3.dist-info → finalsa_common_models-2.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finalsa-common-models
-Version: 2.0.3
+Version: 2.1.0
 Summary: Common models for Finalsa
 Project-URL: Homepage, https://github.com/finalsa/finalsa-common-models
 Author-email: Luis Jimenez <luis@finalsa.com>
@@ -28,8 +28,8 @@ License: MIT License
 License-File: LICENSE.md
 Keywords: common,finalsa,models
 Requires-Python: >=3.10
-Requires-Dist: orjson>=3.10.16
-Requires-Dist: pydantic>=2.11.1
+Requires-Dist: orjson>=3.11.2
+Requires-Dist: pydantic>=2.11.7
 Requires-Dist: python-dateutil>=2.9.0.post0
 Description-Content-Type: text/markdown
 

finalsa_common_models-2.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+finalsa/common/models/__init__.py,sha256=SaAY7c6ysgKh5ycS-3avCVty6croZXQS4BHLORDGq6A,728
+finalsa/common/models/exceptions/__init__.py,sha256=Gu9bclVmdSnNTXhcRrVICkCzQK9HT0xRCr0zRvrXJE8,96
+finalsa/common/models/exceptions/base_domain_exception.py,sha256=SWp6B41nfAxQyOF2X9SlwRMB7z4z_NS4lvSdO7PPkaA,1027
+finalsa/common/models/models/__init__.py,sha256=kiHCRA5pZwIDXfAryWO7ir1SGHUlwNtDclD6B26KIpo,619
+finalsa/common/models/models/functions.py,sha256=vKUrhl3AVfnYBqqKYpZbZevrBpUx7ywqhtU3KKPqWUE,2983
+finalsa/common/models/models/meta.py,sha256=VKBmzkBs1W6so9bmTXO5kIIQ2f3MzrTdZhz4bHG1FsQ,711
+finalsa/common/models/models/pagination.py,sha256=EFTcHbhR62wl9Kf9pfZWhV2sO1ZhIQorxZhcZTsC0n0,3097
+finalsa/common/models/models/sqs_response.py,sha256=GKkDyWYeYEUCRHp2H8MjxvzFuwWL1ngzpf5zILhVUNg,2258
+finalsa_common_models-2.1.0.dist-info/METADATA,sha256=o745pBBx6OQ5vJdP2TURTcYfTQsLV-H9rpEm0Msr5m4,3053
+finalsa_common_models-2.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+finalsa_common_models-2.1.0.dist-info/licenses/LICENSE.md,sha256=yqzhfnTBr2S4lUBx-yibVPOIXRUDPrSUN9-_7AsC6OU,1084
+finalsa_common_models-2.1.0.dist-info/RECORD,,

{finalsa_common_models-2.0.3.dist-info → finalsa_common_models-2.1.0.dist-info}/WHEEL

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

finalsa_common_models-2.0.3.dist-info/RECORD

@@ -1,9 +0,0 @@
-finalsa/common/models/__init__.py,sha256=cJQBAlbwE0zC6yaqPPD4XsQjxBbg5uR--WpNIPro0Tw,487
-finalsa/common/models/models/__init__.py,sha256=idkn9Md7ApwVAelmOh7sd1V5Qa2V9AqwqpkMbXhY2_A,468
-finalsa/common/models/models/functions.py,sha256=vKUrhl3AVfnYBqqKYpZbZevrBpUx7ywqhtU3KKPqWUE,2983
-finalsa/common/models/models/meta.py,sha256=VKBmzkBs1W6so9bmTXO5kIIQ2f3MzrTdZhz4bHG1FsQ,711
-finalsa/common/models/models/sqs_response.py,sha256=GKkDyWYeYEUCRHp2H8MjxvzFuwWL1ngzpf5zILhVUNg,2258
-finalsa_common_models-2.0.3.dist-info/METADATA,sha256=SO0_gLyS-7nRStPN3y-DGsKmYXnFwJc3YRMjXhszAhI,3054
-finalsa_common_models-2.0.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-finalsa_common_models-2.0.3.dist-info/licenses/LICENSE.md,sha256=yqzhfnTBr2S4lUBx-yibVPOIXRUDPrSUN9-_7AsC6OU,1084
-finalsa_common_models-2.0.3.dist-info/RECORD,,