finalsa-common-models 2.0.3__tar.gz → 2.1.0__tar.gz

{finalsa_common_models-2.0.3 → finalsa_common_models-2.1.0}/PKG-INFO

@@ -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.0.3 → finalsa_common_models-2.1.0}/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-2.1.0/finalsa/common/models/exceptions/__init__.py

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

finalsa_common_models-2.1.0/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-2.0.3 → finalsa_common_models-2.1.0}/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-2.1.0/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 → finalsa_common_models-2.1.0}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "finalsa-common-models"
-version = "2.0.3"
+version = "2.1.0"
 description = "Common models for Finalsa"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
-    "orjson>=3.10.16",
-    "pydantic>=2.11.1",
+    "orjson>=3.11.2",
+    "pydantic>=2.11.7",
     "python-dateutil>=2.9.0.post0",
 ]
 authors = [
@@ -28,12 +28,14 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.sdist]
 include = [
+  "finalsa/common/models/exceptions/*.py",
   "finalsa/common/models/*.py",
   "finalsa/common/models/models/*.py"
 ]
 
 [tool.hatch.build.targets.wheel]
 include = [
+  "finalsa/common/models/exceptions/*.py",
   "finalsa/common/models/*.py",
   "finalsa/common/models/models/*.py"
 ]