refactor(BA-5010): Extract shared PaginationInfo DTO class (#9869)

seedspirit · claude · web-flow · commit 9c7c95a7b71d · 2026-03-11T11:53:51.000+09:00
Co-authored-by: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/changes/9869.enhance.md b/changes/9869.enhance.md
@@ -0,0 +1 @@
+Extract shared PaginationInfo DTO class and replace per-module duplicates with unified import.
diff --git a/src/ai/backend/common/dto/manager/agent/response.py b/src/ai/backend/common/dto/manager/agent/response.py
@@ -8,6 +8,7 @@
 from pydantic import BaseModel, Field
 
 from ai.backend.common.api_handlers import BaseResponseModel
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 
 __all__ = (
     "AgentDTO",
@@ -33,14 +34,6 @@ class AgentDTO(BaseModel):
     version: str = Field(description="Agent version string")
 
 
-class PaginationInfo(BaseModel):
-    """Pagination information."""
-
-    total: int = Field(description="Total number of items")
-    offset: int = Field(description="Number of items skipped")
-    limit: int | None = Field(default=None, description="Maximum items returned")
-
-
 class GetAgentDetailResponse(BaseResponseModel):
     """Response for getting a single agent detail."""
 
diff --git a/src/ai/backend/common/dto/manager/auto_scaling_rule/response.py b/src/ai/backend/common/dto/manager/auto_scaling_rule/response.py
@@ -12,6 +12,7 @@
 from pydantic import BaseModel, Field
 
 from ai.backend.common.api_handlers import BaseResponseModel
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 from ai.backend.common.types import AutoScalingMetricSource
 
 __all__ = (
@@ -54,14 +55,6 @@ class GetAutoScalingRuleResponse(BaseResponseModel):
     auto_scaling_rule: AutoScalingRuleDTO = Field(description="Auto-scaling rule data")
 
 
-class PaginationInfo(BaseModel):
-    """Pagination information."""
-
-    total: int = Field(description="Total number of items")
-    offset: int = Field(description="Number of items skipped")
-    limit: int | None = Field(default=None, description="Maximum items returned")
-
-
 class SearchAutoScalingRulesResponse(BaseResponseModel):
     """Response for searching auto-scaling rules."""
 
diff --git a/src/ai/backend/common/dto/manager/compute_session/response.py b/src/ai/backend/common/dto/manager/compute_session/response.py
@@ -4,9 +4,10 @@
 from typing import Any
 from uuid import UUID
 
-from pydantic import BaseModel, Field
+from pydantic import Field
 
 from ai.backend.common.api_handlers import BaseResponseModel
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 
 __all__ = (
     "PaginationInfo",
@@ -17,14 +18,6 @@
 )
 
 
-class PaginationInfo(BaseModel):
-    """Pagination information."""
-
-    total: int = Field(description="Total number of items")
-    offset: int = Field(description="Number of items skipped")
-    limit: int | None = Field(default=None, description="Maximum items returned")
-
-
 class ContainerDTO(BaseResponseModel):
     """Container (kernel) DTO."""
 
diff --git a/src/ai/backend/common/dto/manager/deployment/response.py b/src/ai/backend/common/dto/manager/deployment/response.py
@@ -18,6 +18,7 @@
     RouteStatus,
     RouteTrafficStatus,
 )
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 from ai.backend.common.types import ClusterMode, RuntimeVariant
 
 __all__ = (
@@ -54,14 +55,6 @@
 )
 
 
-class PaginationInfo(BaseModel):
-    """Pagination information."""
-
-    total: int = Field(description="Total number of items")
-    offset: int = Field(description="Number of items skipped")
-    limit: int | None = Field(default=None, description="Maximum items returned")
-
-
 class NetworkConfigDTO(BaseModel):
     """Network configuration for deployment."""
 
diff --git a/src/ai/backend/common/dto/manager/domain/response.py b/src/ai/backend/common/dto/manager/domain/response.py
@@ -11,6 +11,7 @@
 from pydantic import BaseModel, Field
 
 from ai.backend.common.api_handlers import BaseResponseModel
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 
 __all__ = (
     "CreateDomainResponse",
@@ -40,14 +41,6 @@ class DomainDTO(BaseModel):
     integration_id: str | None = Field(default=None, description="External integration ID")
 
 
-class PaginationInfo(BaseModel):
-    """Pagination information."""
-
-    total: int = Field(description="Total number of items")
-    offset: int = Field(description="Number of items skipped")
-    limit: int | None = Field(default=None, description="Maximum items returned")
-
-
 class CreateDomainResponse(BaseResponseModel):
     """Response for creating a domain."""
 
diff --git a/src/ai/backend/common/dto/manager/fair_share/response.py b/src/ai/backend/common/dto/manager/fair_share/response.py
@@ -9,6 +9,7 @@
 from pydantic import BaseModel, Field
 
 from ai.backend.common.api_handlers import BaseResponseModel
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 
 __all__ = (
     # Common
@@ -51,14 +52,6 @@
 )
 
 
-class PaginationInfo(BaseModel):
-    """Pagination information."""
-
-    total: int = Field(description="Total number of items")
-    offset: int = Field(description="Number of items skipped")
-    limit: int | None = Field(default=None, description="Maximum items returned")
-
-
 class ResourceSlotEntryDTO(BaseModel):
     """A single resource slot entry with resource type and quantity."""
 
diff --git a/src/ai/backend/common/dto/manager/group/response.py b/src/ai/backend/common/dto/manager/group/response.py
@@ -12,7 +12,7 @@
 from pydantic import BaseModel, Field
 
 from ai.backend.common.api_handlers import BaseResponseModel
-from ai.backend.common.dto.manager.deployment.response import PaginationInfo
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 
 __all__ = (
     # DTOs
diff --git a/src/ai/backend/common/dto/manager/image/response.py b/src/ai/backend/common/dto/manager/image/response.py
@@ -12,6 +12,7 @@
 from pydantic import BaseModel, Field
 
 from ai.backend.common.api_handlers import BaseResponseModel
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 
 __all__ = (
     "AliasImageResponse",
@@ -71,14 +72,6 @@ class ImageDTO(BaseModel):
     created_at: datetime | None = Field(default=None, description="Creation timestamp")
 
 
-class PaginationInfo(BaseModel):
-    """Pagination information."""
-
-    total: int = Field(description="Total number of items")
-    offset: int = Field(description="Number of items skipped")
-    limit: int | None = Field(default=None, description="Maximum items returned")
-
-
 class SearchImagesResponse(BaseResponseModel):
     """Response for searching images."""
 
diff --git a/src/ai/backend/common/dto/manager/notification/response.py b/src/ai/backend/common/dto/manager/notification/response.py
@@ -19,6 +19,7 @@
     SMTPAuth,
     SMTPConnection,
 )
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 
 __all__ = (
     "CreateNotificationChannelResponse",
@@ -109,14 +110,6 @@ class GetNotificationChannelResponse(BaseResponseModel):
     channel: NotificationChannelDTO = Field(description="Channel data")
 
 
-class PaginationInfo(BaseModel):
-    """Pagination information."""
-
-    total: int = Field(description="Total number of items")
-    offset: int = Field(description="Number of items skipped")
-    limit: int | None = Field(default=None, description="Maximum items returned")
-
-
 class ListNotificationChannelsResponse(BaseResponseModel):
     """Response for listing notification channels."""
 
diff --git a/src/ai/backend/common/dto/manager/pagination.py b/src/ai/backend/common/dto/manager/pagination.py
@@ -0,0 +1,21 @@
+"""
+Shared pagination DTOs for manager API responses.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+__all__ = ("PaginationInfo",)
+
+
+class PaginationInfo(BaseModel):
+    """Pagination information for list responses."""
+
+    total: int = Field(description="Total number of items", ge=0)
+    offset: int = Field(description="Number of items skipped", ge=0)
+    limit: int | None = Field(
+        default=None,
+        description="Maximum items returned; optional to accommodate cursor-based pagination where an explicit limit may not apply",
+        ge=1,  # ge constraint only applies when the value is not None
+    )
diff --git a/src/ai/backend/common/dto/manager/prometheus_query_preset/response.py b/src/ai/backend/common/dto/manager/prometheus_query_preset/response.py
@@ -11,6 +11,7 @@
 from pydantic import BaseModel, Field
 
 from ai.backend.common.api_handlers import BaseResponseModel
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 
 __all__ = (
     "CreateQueryDefinitionResponse",
@@ -49,14 +50,6 @@ class QueryDefinitionDTO(BaseModel):
     updated_at: datetime = Field(description="Last update timestamp")
 
 
-class PaginationInfo(BaseModel):
-    """Pagination information."""
-
-    total: int = Field(description="Total count of items")
-    offset: int = Field(description="Current offset")
-    limit: int = Field(description="Current limit")
-
-
 class CreateQueryDefinitionResponse(BaseResponseModel):
     """Response for creating a query definition."""
 
diff --git a/src/ai/backend/common/dto/manager/quota_scope/response.py b/src/ai/backend/common/dto/manager/quota_scope/response.py
@@ -3,6 +3,7 @@
 from pydantic import BaseModel, Field
 
 from ai.backend.common.api_handlers import BaseResponseModel
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 
 __all__ = (
     "GetQuotaScopeResponse",
@@ -22,12 +23,6 @@ class QuotaScopeDTO(BaseModel):
     hard_limit_bytes: int | None = Field(default=None, description="Hard limit in bytes")
 
 
-class PaginationInfo(BaseModel):
-    total: int = Field(description="Total number of items")
-    offset: int = Field(description="Number of items skipped")
-    limit: int | None = Field(default=None, description="Maximum items returned")
-
-
 class GetQuotaScopeResponse(BaseResponseModel):
     quota_scope: QuotaScopeDTO = Field(description="Quota scope data")
 
diff --git a/src/ai/backend/common/dto/manager/rbac/response.py b/src/ai/backend/common/dto/manager/rbac/response.py
@@ -12,6 +12,7 @@
 
 from ai.backend.common.api_handlers import BaseResponseModel
 from ai.backend.common.data.permission.types import ScopeType
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 
 from .types import EntityType, OperationType, RoleSource, RoleStatus
 
@@ -63,14 +64,6 @@ class AssignedUserDTO(BaseModel):
     granted_at: datetime = Field(description="Timestamp when the role was granted")
 
 
-class PaginationInfo(BaseModel):
-    """Pagination information."""
-
-    total: int = Field(description="Total number of items")
-    offset: int = Field(description="Number of items skipped")
-    limit: int | None = Field(default=None, description="Maximum items returned")
-
-
 class CreateRoleResponse(BaseResponseModel):
     """Response for creating a role."""
 
diff --git a/src/ai/backend/common/dto/manager/resource_policy/response.py b/src/ai/backend/common/dto/manager/resource_policy/response.py
@@ -11,6 +11,7 @@
 from pydantic import BaseModel, Field
 
 from ai.backend.common.api_handlers import BaseResponseModel
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 from ai.backend.common.types import DefaultForUnspecified
 
 __all__ = (
@@ -40,14 +41,6 @@
 )
 
 
-class PaginationInfo(BaseModel):
-    """Pagination information."""
-
-    total: int = Field(description="Total number of items")
-    offset: int = Field(description="Number of items skipped")
-    limit: int | None = Field(default=None, description="Maximum items returned")
-
-
 # ---- Keypair Resource Policy ----
 
 
diff --git a/src/ai/backend/common/dto/manager/resource_slot/response.py b/src/ai/backend/common/dto/manager/resource_slot/response.py
@@ -8,6 +8,7 @@
 from pydantic import BaseModel, Field
 
 from ai.backend.common.api_handlers import BaseResponseModel
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 
 __all__ = (
     "NumberFormatDTO",
@@ -38,14 +39,6 @@ class ResourceSlotTypeDTO(BaseModel):
     rank: int = Field(description="Display rank/order")
 
 
-class PaginationInfo(BaseModel):
-    """Pagination information."""
-
-    total: int = Field(description="Total number of items")
-    offset: int = Field(description="Number of items skipped")
-    limit: int | None = Field(default=None, description="Maximum items returned")
-
-
 class SearchResourceSlotTypesResponse(BaseResponseModel):
     """Response for searching resource slot types."""
 
diff --git a/src/ai/backend/common/dto/manager/scheduling_history/response.py b/src/ai/backend/common/dto/manager/scheduling_history/response.py
@@ -3,9 +3,10 @@
 from datetime import datetime
 from uuid import UUID
 
-from pydantic import BaseModel, Field
+from pydantic import Field
 
 from ai.backend.common.api_handlers import BaseResponseModel
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 
 __all__ = (
     "PaginationInfo",
@@ -19,14 +20,6 @@
 )
 
 
-class PaginationInfo(BaseModel):
-    """Pagination information."""
-
-    total: int = Field(description="Total number of items")
-    offset: int = Field(description="Number of items skipped")
-    limit: int | None = Field(default=None, description="Maximum items returned")
-
-
 class SubStepResultDTO(BaseResponseModel):
     """Sub-step result DTO."""
 
diff --git a/src/ai/backend/common/dto/manager/user/response.py b/src/ai/backend/common/dto/manager/user/response.py
@@ -11,6 +11,7 @@
 from pydantic import BaseModel, Field
 
 from ai.backend.common.api_handlers import BaseResponseModel
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 
 from .types import UserRole, UserStatus
 
@@ -55,14 +56,6 @@ class UserDTO(BaseModel):
     container_gids: list[int] | None = Field(default=None, description="Container additional GIDs")
 
 
-class PaginationInfo(BaseModel):
-    """Pagination information for search results."""
-
-    total: int = Field(description="Total number of items")
-    offset: int = Field(description="Number of items skipped")
-    limit: int = Field(description="Maximum items returned")
-
-
 class CreateUserResponse(BaseResponseModel):
     """Response for creating a user."""
 
diff --git a/src/ai/backend/manager/api/rest/agent/handler.py b/src/ai/backend/manager/api/rest/agent/handler.py
@@ -8,7 +8,8 @@
 
 from ai.backend.common.api_handlers import APIResponse, BodyParam
 from ai.backend.common.dto.manager.agent.request import SearchAgentsRequest
-from ai.backend.common.dto.manager.agent.response import PaginationInfo, SearchAgentsResponse
+from ai.backend.common.dto.manager.agent.response import SearchAgentsResponse
+from ai.backend.common.dto.manager.pagination import PaginationInfo
 from ai.backend.logging import BraceStyleAdapter
 from ai.backend.manager.dto.context import UserContext
 from ai.backend.manager.services.agent.actions.search_agents import SearchAgentsAction
diff --git a/tests/unit/common/dto/manager/image/test_response.py b/tests/unit/common/dto/manager/image/test_response.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Extract shared PaginationInfo DTO class and replace per-module duplicates with unified import.`