schemas.common_schemas

src.schemas.common_schemas

Common schemas used across multiple API endpoints.

Provides reusable schema components for pagination, date ranges, and standard response wrappers.

Reference

• docs/architecture/api-design-patterns.md

Classes

PaginationParams

Bases: BaseModel

Pagination query parameters.

Attributes:

Name	Type	Description
page	int	Page number (1-indexed).
page_size	int	Number of items per page.

Source code in src/schemas/common_schemas.py

class PaginationParams(BaseModel):
    """Pagination query parameters.

    Attributes:
        page: Page number (1-indexed).
        page_size: Number of items per page.
    """

    page: int = Field(1, ge=1, description="Page number (1-indexed)")
    page_size: int = Field(20, ge=1, le=100, description="Items per page")

    @property
    def offset(self) -> int:
        """Calculate SQL offset from page number.

        Returns:
            Offset for database query.
        """
        return (self.page - 1) * self.page_size

    @property
    def limit(self) -> int:
        """Return page size as limit.

        Returns:
            Limit for database query.
        """
        return self.page_size

Attributes

offset property

offset: int

Calculate SQL offset from page number.

Returns:

Type	Description
int	Offset for database query.

limit property

limit: int

Return page size as limit.

Returns:

Type	Description
int	Limit for database query.

PaginatedMeta

Bases: BaseModel

Pagination metadata for list responses.

Attributes:

Name	Type	Description
page	int	Current page number.
page_size	int	Items per page.
total_count	int	Total items available.
total_pages	int	Total number of pages.

Source code in src/schemas/common_schemas.py

class PaginatedMeta(BaseModel):
    """Pagination metadata for list responses.

    Attributes:
        page: Current page number.
        page_size: Items per page.
        total_count: Total items available.
        total_pages: Total number of pages.
    """

    page: int = Field(..., description="Current page number")
    page_size: int = Field(..., description="Items per page")
    total_count: int = Field(..., description="Total items available")
    total_pages: int = Field(..., description="Total number of pages")

    @classmethod
    def from_pagination(
        cls, page: int, page_size: int, total_count: int
    ) -> "PaginatedMeta":
        """Create pagination metadata from parameters.

        Args:
            page: Current page number.
            page_size: Items per page.
            total_count: Total items available.

        Returns:
            PaginatedMeta instance.
        """
        total_pages = (total_count + page_size - 1) // page_size if page_size > 0 else 0
        return cls(
            page=page,
            page_size=page_size,
            total_count=total_count,
            total_pages=total_pages,
        )

Functions

from_pagination classmethod

from_pagination(
    page: int, page_size: int, total_count: int
) -> PaginatedMeta

Create pagination metadata from parameters.

Parameters:

Name	Type	Description	Default
page	int	Current page number.	required
page_size	int	Items per page.	required
total_count	int	Total items available.	required

Returns:

Type	Description
PaginatedMeta	PaginatedMeta instance.

Source code in src/schemas/common_schemas.py

@classmethod
def from_pagination(
    cls, page: int, page_size: int, total_count: int
) -> "PaginatedMeta":
    """Create pagination metadata from parameters.

    Args:
        page: Current page number.
        page_size: Items per page.
        total_count: Total items available.

    Returns:
        PaginatedMeta instance.
    """
    total_pages = (total_count + page_size - 1) // page_size if page_size > 0 else 0
    return cls(
        page=page,
        page_size=page_size,
        total_count=total_count,
        total_pages=total_pages,
    )

DateRangeParams

Bases: BaseModel

Date range query parameters.

Attributes:

Name	Type	Description
start_date	date | None	Start of date range (inclusive).
end_date	date | None	End of date range (inclusive).

Source code in src/schemas/common_schemas.py

class DateRangeParams(BaseModel):
    """Date range query parameters.

    Attributes:
        start_date: Start of date range (inclusive).
        end_date: End of date range (inclusive).
    """

    start_date: date | None = Field(None, description="Start date (inclusive)")
    end_date: date | None = Field(None, description="End date (inclusive)")

SyncResponse

Bases: BaseModel

Response for sync operations.

Attributes:

Name	Type	Description
created	int	Number of new records created.
updated	int	Number of existing records updated.
unchanged	int	Number of records unchanged.
errors	int	Number of records that failed to sync.
message	str	Human-readable summary.

Source code in src/schemas/common_schemas.py

class SyncResponse(BaseModel):
    """Response for sync operations.

    Attributes:
        created: Number of new records created.
        updated: Number of existing records updated.
        unchanged: Number of records unchanged.
        errors: Number of records that failed to sync.
        message: Human-readable summary.
    """

    created: int = Field(..., description="Records created")
    updated: int = Field(..., description="Records updated")
    unchanged: int = Field(..., description="Records unchanged")
    errors: int = Field(0, description="Records with sync errors")
    message: str = Field(..., description="Summary message")