pypaginate.domain.pages

Pagination result pages.

OffsetPage and CursorPage are separate types with clean schemas. No null leakage — each page has only the fields for its mode.

When msgspec is installed (pypaginate[fast]), page construction uses msgspec.Struct for near-zero overhead. The returned object duck-types as a Pydantic model with .model_dump() support.

Classes

`BasePage`	Shared result fields for all pagination modes.
`CursorPage`	Cursor pagination result.
`OffsetPage`	Offset pagination result.

Module Contents

class pypaginate.domain.pages.BasePage(/, **data: Any)

Bases: pydantic.BaseModel, Generic[ItemT]

Shared result fields for all pagination modes.

model_config: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pypaginate.domain.pages.CursorPage

Bases: BasePage[ItemT]

Cursor pagination result.

No total, no page — those are offset-only concepts.

classmethod create(items: list[ItemT], params: pypaginate.domain.params.CursorParams, *, next_cursor: str | None = None, previous_cursor: str | None = None) → Any

Build from cursor pagination results.

Parameters:

items – Items for this page.
params – Cursor parameters used.
next_cursor – Cursor for the next page.
previous_cursor – Cursor for the previous page.

Returns:

CursorPage or FastCursorPage (if msgspec installed).

class pypaginate.domain.pages.OffsetPage

Bases: BasePage[ItemT]

Offset pagination result.

All fields are non-optional — clean serialization.

classmethod create(items: list[ItemT], total: int, params: pypaginate.domain.params.OffsetParams) → Any

Build from offset pagination results.

Parameters:

items – Items for this page.
total – Total item count across all pages.
params – Offset parameters used.

Returns:

OffsetPage or FastOffsetPage (if msgspec installed).