API Documentation

Pagination API

sqlakeyset.select_page(s: Session | Connection, selectable: Select, per_page: int = 10, after: Tuple | Literal[False] | None = None, before: Tuple | Literal[False] | None = None, page: Marker | Tuple[Tuple | None, bool] | str | None = None) → Page[Row[_TP]][source]

Get a page of results from a SQLAlchemy Core (or new-style ORM) selectable.

Specify no more than one of the arguments page, after or before. If none of these are provided, the first page is returned.

Parameters:

  • s – sqlalchemy.engine.Connection or sqlalchemy.orm.session.Session to use to execute the query.

  • selectable – The source selectable.

  • per_page (int, optional.) – The (maximum) number of rows on the page.

  • page – a (keyset, backwards) pair or string bookmark describing the page to get.

  • after – if provided, the page will consist of the rows immediately following the specified keyset.

  • before – if provided, the page will consist of the rows immediately preceding the specified keyset.

Returns:

A Page containing the requested rows and paging hooks to access surrounding pages.

async sqlakeyset.asyncio.select_page(s: AsyncSession | AsyncConnection, selectable: Select, per_page: int = 10, after: Tuple | Literal[False] | None = None, before: Tuple | Literal[False] | None = None, page: Marker | Tuple[Tuple | None, bool] | str | None = None) → Page[Row[_TP]][source]

Get a page of results from a SQLAlchemy Core (or new-style ORM) selectable using an asyncio connection.

Specify no more than one of the arguments page, after or before. If none of these are provided, the first page is returned.

Parameters:

  • s – sqlalchemy.engine.Connection or sqlalchemy.orm.session.Session to use to execute the query.

  • selectable – The source selectable.

  • per_page (int, optional.) – The (maximum) number of rows on the page.

  • page – a (keyset, backwards) pair or string bookmark describing the page to get.

  • after – if provided, the page will consist of the rows immediately following the specified keyset.

  • before – if provided, the page will consist of the rows immediately preceding the specified keyset.

Returns:

A Page containing the requested rows and paging hooks to access surrounding pages.

sqlakeyset.get_page(query: Query, per_page: int = 10, after: Tuple | Literal[False] | None = None, before: Tuple | Literal[False] | None = None, page: Marker | Tuple[Tuple | None, bool] | str | None = None) → Page[Row[_TP]][source]

Get a page of results for a legacy ORM query.

Specify no more than one of the arguments page, after or before. If none of these are provided, the first page is returned.

Parameters:

  • query (sqlalchemy.orm.query.Query.) – The source query.

  • per_page (int, optional.) – The (maximum) number of rows on the page.

  • page – a (keyset, backwards) pair or string bookmark describing the page to get.

  • after – if provided, the page will consist of the rows immediately following the specified keyset.

  • before – if provided, the page will consist of the rows immediately preceding the specified keyset.

Returns:

A Page containing the requested rows and paging hooks to access surrounding pages.

Pagination Results

class sqlakeyset.Page(iterable: Iterable[_Row], paging: Paging[_Row], keys=None)[source]

A list of result rows with access to paging information and some convenience methods.

keys() → List[str] | None[source]

Equivalent of sqlalchemy.engine.ResultProxy.keys(): returns the list of string keys for rows.

one() → _Row[source]

Assuming paging was called with per_page=1, return the single row on this page.

paging: Paging[_Row]

The Paging information describing how this page relates to the whole resultset.

scalar()[source]

Assuming paging was called with per_page=1 and a single-column query, return the single value.

class sqlakeyset.Paging(rows: List[_Row], per_page: int, backwards: bool, current_place: Tuple | None, places: List[Tuple])[source]

Metadata describing the position of a page in a collection. Most properties return a page marker. Prefix these properties with bookmark_ to get the serialized version of that page marker.

Unless you’re extending sqlakeyset you should not be constructing this class directly - use sqlakeyset.get_page or sqlakeyset.select_page to acquire a Page object, then access page.paging to get the paging metadata.

property bookmark_current: str

Bookmark for the current page in the current paging direction.

property bookmark_current_backwards: str

Bookmark for the current page in backwards direction.

property bookmark_current_forwards: str

Bookmark for the current page in forwards direction.

property bookmark_current_opposite: str

Bookmark for the current page in the opposite of the current paging direction.

property bookmark_further: str

Bookmark for the following page in the current paging direction.

bookmark_items()[source]

Iterates over the items in the page, returning a tuple (bookmark, item) for each.

property bookmark_next: str

Bookmark for the next page (in the original query order).

property bookmark_previous: str

Bookmark for the previous page (in the original query order).

property current: Marker

Marker for the current page in the current paging direction.

property current_backwards: Marker

Marker for the current page in backwards direction.

property current_forwards: Marker

Marker for the current page in forwards direction.

property current_opposite: Marker

Marker for the current page in the opposite of the current paging direction.

property further: Marker

Marker for the following page in the current paging direction.

get_bookmark_at(i)[source]

Get the bookmark for item at the given row index.

get_marker_at(i) → Marker[source]

Get the marker for item at the given row index.

property has_further: bool

Boolean flagging whether there are more rows before this page in the current paging direction.

property has_next: bool

Boolean flagging whether there are more rows after this page (in the original query order).

property has_previous: bool

Boolean flagging whether there are more rows before this page (in the original query order).

property is_full: bool

Boolean flagging whether this page contains as many rows as were requested in per_page.

items() → Iterable[Tuple[Marker, Any]][source]

Iterates over the items in the page, returning a tuple (marker, item) for each.

property next: Marker

Marker for the next page (in the original query order).

property previous: Marker

Marker for the previous page (in the original query order).

Bookmark Serialization

In most use cases, you shouldn’t need to call these directly - bookmarks can be obtained by calling the bookmark_-prefixed methods on Page objects, and can be passed directly as the page, after or before parameters to get_page() and select_page().

sqlakeyset.serialize_bookmark(marker: Marker | Tuple[Tuple | None, bool]) → str[source]
sqlakeyset.serialize_bookmark(marker: None) → None

Serialize a place marker to a bookmark string.

Returns:

A CSV-like string using ~ as a separator.

sqlakeyset.unserialize_bookmark(bookmark: str) → Marker[source]

Deserialize a bookmark string to a place marker.

Parameters:

bookmark – A string in the format produced by serialize_bookmark().

Returns:

A marker pair as described in serialize_bookmark().

Custom Types in Bookmarks

If you’re using custom types for your ordering columns, you will need to register them with sqlakeyset in order to use bookmarks.

sqlakeyset.custom_bookmark_type(type: Type[T], code: str, deserializer: Callable[[str], T] | None = None, serializer: Callable[[T], str] | None = None)[source]

Register (de)serializers for bookmarks to use for a custom type.

Parameters:

  • type (type) – Python type to register.

  • code (str) – A short alphabetic code to use to identify this type in serialized bookmarks.

  • serializer – A function mapping type values to strings. Default is str.

  • deserializer – Inverse for serializer. Default is the type constructor.