feat: add pages computed field to OffsetPagination schema (#159)

src/fastapi_toolsets/schemas.py

@@ -1,9 +1,10 @@
 """Base Pydantic schemas for API responses."""
 
+import math
 from enum import Enum
 from typing import Annotated, Any, ClassVar, Generic, Literal, TypeVar, Union
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, computed_field
 
 from .types import DataT
 
@@ -103,6 +104,7 @@ class OffsetPagination(PydanticBase):
         items_per_page: Number of items per page
         page: Current page number (1-indexed)
         has_more: Whether there are more pages
+        pages: Total number of pages
     """
 
     total_count: int | None
@@ -110,6 +112,16 @@ class OffsetPagination(PydanticBase):
     page: int
     has_more: bool
 
+    @computed_field
+    @property
+    def pages(self) -> int | None:
+        """Total number of pages, or ``None`` when ``total_count`` is unknown."""
+        if self.total_count is None:
+            return None
+        if self.items_per_page == 0:
+            return 0
+        return math.ceil(self.total_count / self.items_per_page)
+
 
 class CursorPagination(PydanticBase):
     """Pagination metadata for cursor-based list responses.