finalsa-common-models 2.0.4__tar.gz → 2.1.1__tar.gz

{finalsa_common_models-2.0.4 → finalsa_common_models-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: finalsa-common-models
-Version: 2.0.4
+Version: 2.1.1
 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.11.2
-Requires-Dist: pydantic>=2.11.7
+Requires-Dist: orjson>=3.11.6
+Requires-Dist: pydantic>=2.12.5
 Requires-Dist: python-dateutil>=2.9.0.post0
 Description-Content-Type: text/markdown
 

{finalsa_common_models-2.0.4 → finalsa_common_models-2.1.1}/finalsa/common/models/__init__.py

@@ -3,6 +3,9 @@ from finalsa.common.models.models import (
     AsyncMeta,
     Authorization,
     HttpMeta,
+    PaginationMeta,
+    PaginationRequest,
+    PaginationResponse,
     SqsReponse,
     parse_sns_message_attributes,
     parse_sqs_message_attributes,
@@ -19,6 +22,9 @@ __all__ = [
     "AsyncMeta",
     "Authorization",
     "HttpMeta",
+    "PaginationMeta",
+    "PaginationRequest",
+    "PaginationResponse",
     "SqsReponse",
     "parse_sns_message_attributes",
     "parse_sqs_message_attributes",

{finalsa_common_models-2.0.4 → finalsa_common_models-2.1.1}/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.1/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.4 → finalsa_common_models-2.1.1}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "finalsa-common-models"
-version = "2.0.4"
+version = "2.1.1"
 description = "Common models for Finalsa"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
-    "orjson>=3.11.2",
-    "pydantic>=2.11.7",
+    "orjson>=3.11.6",
+    "pydantic>=2.12.5",
     "python-dateutil>=2.9.0.post0",
 ]
 authors = [