DatetimeIdCursor

class safir.database.DatetimeIdCursor(previous, time, id)

Bases: PaginationCursor[E]

Pagination cursor using a datetime and unique column ID.

Cursors that first order by time and then by a unique integer column ID can subclass this class and only define the id_column and time_column static methods to return the ORM model fields for the timestamp and column ID.

Examples

Here is a specialization of this cursor class for a simple ORM model where the timestamp field to order by is named creation_time and the unique row ID is named id.

class TableCursor(DatetimeIdCursor):
    @staticmethod
    def id_column() -> InstrumentedAttribute:
        return Table.id

    @staticmethod
    def time_column() -> InstrumentedAttribute:
        return Table.creation_time

Parameters:

• previous (bool)

• time (datetime)

• id (int)

Methods Summary

apply_cursor(stmt)	Apply the restrictions from the cursor to a select statement.
apply_order(stmt, *[, reverse])	Apply the sort order of the cursor to a select statement.
from_str(cursor)	Build cursor from the string serialization form.
id_column()	Return SQL model attribute holding the ID.
invert()	Return the inverted cursor (going the opposite direction).
time_column()	Return SQL model attribute holding the time position.

Methods Documentation

apply_cursor(stmt)

Apply the restrictions from the cursor to a select statement.

Forward cursors (the default) must include the entry the cursor was based on. Reverse cursors must exclude that entry and return data beginning with the entry immediately previous.

Parameters:

stmt (Select) – Select statement to modify.

Returns:

Modified select statement.

Return type:

sqlalchemy.sql.expression.Select

classmethod apply_order(stmt, *, reverse=False)

Apply the sort order of the cursor to a select statement.

This is independent of the cursor and only needs to know the underlying ORM fields, so it is available as a class method on the cursor class, allowing it to be used without a cursor (such as for the initial query). This does, however, mean that the caller has to explicitly say whether to reverse the order, which is required when using a previous cursor.

Parameters:

• stmt (Select) – SQL select statement.

• reverse (bool, default: False) – Whether to reverse the sort order.

Returns:

The same select statement but sorted in the order expected by the cursor.

Return type:

sqlalchemy.sql.expression.Select

classmethod from_str(cursor)

Build cursor from the string serialization form.

Parameters:

cursor (str) – Serialized form of the cursor.

Returns:

The cursor represented as an object.

Return type:

PaginationCursor

Raises:

ValueError – Raised if the cursor is invalid.

abstract static id_column()

Return SQL model attribute holding the ID.

Return type:

InstrumentedAttribute

invert()

Return the inverted cursor (going the opposite direction).

Parameters:

cursor – Cursor to invert.

Returns:

The inverted cursor.

Return type:

PaginationCursor

abstract static time_column()

Return SQL model attribute holding the time position.

Return type:

InstrumentedAttribute