finalsa-common-models 2.0.4__py3-none-any.whl → 2.1.1__py3-none-any.whl

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/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.4.dist-info → finalsa_common_models-2.1.1.dist-info}/METADATA

@@ -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.1.1.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.1.dist-info/METADATA,sha256=1MhEq4VjDDvvL1r7yc3_52cC_9izjXMKOGJhrU86Wfc,3053
+finalsa_common_models-2.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+finalsa_common_models-2.1.1.dist-info/licenses/LICENSE.md,sha256=yqzhfnTBr2S4lUBx-yibVPOIXRUDPrSUN9-_7AsC6OU,1084
+finalsa_common_models-2.1.1.dist-info/RECORD,,

{finalsa_common_models-2.0.4.dist-info → finalsa_common_models-2.1.1.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.4.dist-info/RECORD

@@ -1,11 +0,0 @@
-finalsa/common/models/__init__.py,sha256=bhw87n6l-6a4tfGGwg1mZXfjoS1sbf94akZpuVaCZ8I,588
-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=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.4.dist-info/METADATA,sha256=nG4rqT1mwp_OCq-J-8TRtCv_1Jmj1bIxL--hov2gonM,3053
-finalsa_common_models-2.0.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-finalsa_common_models-2.0.4.dist-info/licenses/LICENSE.md,sha256=yqzhfnTBr2S4lUBx-yibVPOIXRUDPrSUN9-_7AsC6OU,1084
-finalsa_common_models-2.0.4.dist-info/RECORD,,