mirror of
https://github.com/d3vyce/fastapi-toolsets.git
synced 2026-03-01 17:00:48 +01:00
117 lines
2.6 KiB
Python
117 lines
2.6 KiB
Python
"""Base Pydantic schemas for API responses."""
|
|
|
|
from enum import Enum
|
|
from typing import ClassVar, Generic, TypeVar
|
|
|
|
from pydantic import BaseModel, ConfigDict
|
|
|
|
__all__ = [
|
|
"ApiError",
|
|
"ErrorResponse",
|
|
"Pagination",
|
|
"PaginatedResponse",
|
|
"Response",
|
|
"ResponseStatus",
|
|
]
|
|
|
|
DataT = TypeVar("DataT")
|
|
|
|
|
|
class PydanticBase(BaseModel):
|
|
"""Base class for all Pydantic models with common configuration."""
|
|
|
|
model_config: ClassVar[ConfigDict] = ConfigDict(
|
|
from_attributes=True,
|
|
validate_assignment=True,
|
|
)
|
|
|
|
|
|
class ResponseStatus(str, Enum):
|
|
"""Standard API response status."""
|
|
|
|
SUCCESS = "SUCCESS"
|
|
FAIL = "FAIL"
|
|
|
|
|
|
class ApiError(PydanticBase):
|
|
"""Structured API error definition.
|
|
|
|
Used to define standard error responses with consistent format.
|
|
|
|
Attributes:
|
|
code: HTTP status code
|
|
msg: Short error message
|
|
desc: Detailed error description
|
|
err_code: Application-specific error code (e.g., "AUTH-401")
|
|
"""
|
|
|
|
code: int
|
|
msg: str
|
|
desc: str
|
|
err_code: str
|
|
|
|
|
|
class BaseResponse(PydanticBase):
|
|
"""Base response structure for all API responses.
|
|
|
|
Attributes:
|
|
status: SUCCESS or FAIL
|
|
message: Human-readable message
|
|
error_code: Error code if status is FAIL, None otherwise
|
|
"""
|
|
|
|
status: ResponseStatus = ResponseStatus.SUCCESS
|
|
message: str = "Success"
|
|
error_code: str | None = None
|
|
|
|
|
|
class Response(BaseResponse, Generic[DataT]):
|
|
"""Generic API response with data payload.
|
|
|
|
Example:
|
|
Response[UserRead](data=user, message="User retrieved")
|
|
"""
|
|
|
|
data: DataT | None = None
|
|
|
|
|
|
class ErrorResponse(BaseResponse):
|
|
"""Error response with additional description field.
|
|
|
|
Used for error responses that need more context.
|
|
"""
|
|
|
|
status: ResponseStatus = ResponseStatus.FAIL
|
|
description: str | None = None
|
|
data: None = None
|
|
|
|
|
|
class Pagination(PydanticBase):
|
|
"""Pagination metadata for list responses.
|
|
|
|
Attributes:
|
|
total_count: Total number of items across all pages
|
|
items_per_page: Number of items per page
|
|
page: Current page number (1-indexed)
|
|
has_more: Whether there are more pages
|
|
"""
|
|
|
|
total_count: int
|
|
items_per_page: int
|
|
page: int
|
|
has_more: bool
|
|
|
|
|
|
class PaginatedResponse(BaseResponse, Generic[DataT]):
|
|
"""Paginated API response for list endpoints.
|
|
|
|
Example:
|
|
PaginatedResponse[UserRead](
|
|
data=users,
|
|
pagination=Pagination(total_count=100, items_per_page=10, page=1, has_more=True)
|
|
)
|
|
"""
|
|
|
|
data: list[DataT]
|
|
pagination: Pagination
|