Module

data.pagination

Pagination primitives for chirp.data.

Offset-based pagination that composes withQuery. One method call replaces the manual count-query + offset-math + total-pages-calc pattern.

Usage::

from chirp.data import Query, PageResult

result: PageResult[Todo] = await (
    Query(Todo, "todos")
    .where("done = ?", False)
    .order_by("id DESC")
    .paginate(db, page=2, per_page=20)
)

result.items        # list[Todo] — rows for this page
result.total_pages  # 5
result.has_next     # True
result.page_range() # [1, 2, 3, 4]

Free-threading safety:

  • Frozen dataclass — immutable after creation
  • No shared mutable state
1Class

Classes

PageResult 11 ▼
A page of results with pagination metadata. Constructed by ``Query.paginate()`` — not typically cr…

A page of results with pagination metadata.

Constructed byQuery.paginate()— not typically created directly.

Attributes

Name Type Description
items list[T] —
page int —
per_page int —
total int —

Methods

total_pages 0 int ▼
Total number of pages. Always >= 1.
property
def total_pages(self) -> int
Returns
int
has_prev 0 bool ▼
Whether a previous page exists.
property
def has_prev(self) -> bool
Returns
bool
has_next 0 bool ▼
Whether a next page exists.
property
def has_next(self) -> bool
Returns
bool
prev_page 0 int ▼
Previous page number, clamped to 1.
property
def prev_page(self) -> int
Returns
int
next_page 0 int ▼
Next page number, clamped to total_pages.
property
def next_page(self) -> int
Returns
int
offset 0 int ▼
The SQL OFFSET for this page.
property
def offset(self) -> int
Returns
int
page_range 1 list[int] ▼
Page numbers around the current page for navigation. Returns up to ``2 * windo…
def page_range(self, window: int = 2) -> list[int]

Page numbers around the current page for navigation.

Returns up to2 * window + 1page numbers centered on the current page, clamped to [1, total_pages].

::

PageResult(items=[], page=5, per_page=10, total=100).page_range(2)
# [3, 4, 5, 6, 7]

PageResult(items=[], page=1, per_page=10, total=100).page_range(2)
# [1, 2, 3]
Parameters
Name Type Description
window — Default:2
Returns
list[int]