Concepts

This section explains the core concepts behind pypaginate v0.2, helping you understand how the library works and make informed decisions about which features to use.

Why Read This?

While you can use pypaginate by following the guides, understanding the concepts helps you:

• Choose the right pagination strategy for your use case

• Design efficient filter and search queries that scale

• Debug issues when things don’t work as expected

• Extend the library with custom backends

Topics

Architecture

Hexagonal architecture, domain/engine/adapter layers, and protocol-based backends.

Architecture

Pagination Strategies

Offset vs cursor pagination, their trade-offs, and when to use each.

Pagination Strategies

Cursor Encoding

How cursor values work with the built-in cursor codec for keyset pagination.

Cursor Encoding

Filter Expressions

FilterSpec, And/Or groups, nested FilterGroup trees, and 20 operators.

Filter Expressions

Search & Relevance

Scoring, weights, fuzzy modes, threshold, and Unicode normalization.

Search & Relevance

How pypaginate Works

        graph TB
    subgraph "User Input"
        P["OffsetParams / CursorParams"]
        F["FilterSpec / FilterGroup"]
        S["SortSpec"]
        Q["SearchSpec"]
    end

    subgraph "Engine Layer"
        D["paginate() dispatch"]
        PL["Pipeline (filter→sort→search→paginate)"]
        PAG["Paginator (count→clamp→fetch→Page)"]
    end

    subgraph "Adapter Layer"
        MEM["Memory backends"]
        SA["SQLAlchemy backends"]
        FA["FastAPI dependencies"]
    end

    subgraph "Output"
        OP["OffsetPage[T]"]
        CP["CursorPage[T]"]
    end

    P --> D
    F --> PL
    S --> PL
    Q --> PL
    D --> PAG
    PL --> PAG
    PAG --> MEM
    PAG --> SA
    FA --> P
    MEM --> OP
    SA --> OP
    SA --> CP
    

Key Decisions

Decision	Options	When to Choose
Pagination mode	OffsetParams, CursorParams	Offset for page numbers, cursor for infinite scroll
Data source	In-memory list, SQLAlchemy query	SQLAlchemy for database-backed apps
Filter format	Flat FilterSpec list, nested And/Or groups	Groups for complex boolean logic
Search mode	FuzzyMode.EXACT, FUZZY, TOKEN_SORT	Fuzzy for typo tolerance, token sort for word-order agnostic
Page construction	Pydantic (default), msgspec (pypaginate[fast])	msgspec for near-zero overhead in hot paths