pypaginate.adapters.sqlalchemy.keyset

Keyset pagination WHERE clause builder.

Constructs the lexicographic comparison needed for cursor/keyset pagination directly from SQLAlchemy column expressions. No external dependencies – pure SQLAlchemy 2.0 API.

Classes

OrderColumn

Parsed ORDER BY column with direction metadata.

Functions

build_keyset_condition(→ Any)	Build the WHERE clause for keyset pagination.
extract_order_columns(→ list[OrderColumn])	Extract ORDER BY columns from a Select statement.

Module Contents

class pypaginate.adapters.sqlalchemy.keyset.OrderColumn(element: sqlalchemy.sql.elements.ColumnElement[Any], *, is_ascending: bool)

Parsed ORDER BY column with direction metadata.

property order_clause: Any

Return the SQLAlchemy asc/desc expression for ORDER BY.

property reversed: OrderColumn

Return a copy with flipped direction.

pypaginate.adapters.sqlalchemy.keyset.build_keyset_condition(columns: list[OrderColumn], cursor_values: tuple[Any, Ellipsis]) → Any

Build the WHERE clause for keyset pagination.

For ORDER BY (a ASC, b DESC) with cursor (v1, v2):

WHERE (a > v1) OR (a = v1 AND b < v2)

Uses the conjunction-at-top-level form for optimizer friendliness.

Parameters:

• columns – Parsed ORDER BY columns.

• cursor_values – Tuple of values matching each column.

Returns:

A SQLAlchemy boolean expression.

Raises:

ConfigurationError – If columns/values count mismatch.

pypaginate.adapters.sqlalchemy.keyset.extract_order_columns(query: sqlalchemy.sql.Select[Any]) → list[OrderColumn]

Extract ORDER BY columns from a Select statement.

Unwraps UnaryExpression (asc/desc wrappers) to get the bare column element and its sort direction. Bare columns (no explicit direction) default to ascending.

Parameters:

query – A SQLAlchemy Select with an ORDER BY clause.

Returns:

Ordered list of OrderColumn objects.

Raises:

ConfigurationError – If the query has no ORDER BY clause.