PaginatedList

class safir.database.PaginatedList(entries, next_cursor, prev_cursor)

Bases: Generic

Paginated SQL results with accompanying pagination metadata.

Holds a paginated list of any Pydantic type with pagination cursors. Can hold any type of entry and any type of cursor, but implicitly requires the entry type be one that is meaningfully paginated by that type of cursor.

Parameters:

• entries (list[TypeVar(E, bound= BaseModel)])

• next_cursor (Optional[TypeVar(C, bound= PaginationCursor)])

• prev_cursor (Optional[TypeVar(C, bound= PaginationCursor)])

Attributes Summary

entries	A batch of entries.
next_cursor	Cursor for the next batch of entries.
prev_cursor	Cursor for the previous batch of entries.

Methods Summary

first_url(current_url)	Construct a URL to the first group of results for this query.
from_transform(other, transform)	Build a new paginated list via a transform of each member.
link_header(current_url)	Construct an RFC 8288 Link header for a paginated result.
next_url(current_url)	Construct a URL to the next group of results for this query.
prev_url(current_url)	Construct a URL to the previous group of results for this query.

Attributes Documentation

entries: list[TypeVar(E, bound= BaseModel)] = <dataclasses._MISSING_TYPE object>

A batch of entries.

next_cursor: Optional[TypeVar(C, bound= PaginationCursor)] = <dataclasses._MISSING_TYPE object>

Cursor for the next batch of entries.

prev_cursor: Optional[TypeVar(C, bound= PaginationCursor)] = <dataclasses._MISSING_TYPE object>

Cursor for the previous batch of entries.

Methods Documentation

first_url(current_url)

Construct a URL to the first group of results for this query.

Parameters:

current_url (URL) – The starting URL of the current group of entries.

Returns:

URL to the first group of entries for this query.

Return type:

str

classmethod from_transform(other, transform)

Build a new paginated list via a transform of each member.

Some web services will need to transform the members of a paginated list, to convert from internal to API models for example, without losing the pagination information. This method performs that operation, returning a new paginated list for the new type with the same pagination details.

Parameters:

• transform (Callable[[TypeVar(F, bound= BaseModel)], TypeVar(E, bound= BaseModel)]) – A function that converts from the entry type of this list to the entry type of the new list. This will be called for each entry.

• other (PaginatedList)

Returns:

A new paginated list holding the transformed entries but with the same cursors.

Return type:

PaginatedList

link_header(current_url)

Construct an RFC 8288 Link header for a paginated result.

Parameters:

current_url (URL) – The starting URL of the current group of entries.

Returns:

Contents of an RFC 8288 Link header.

Return type:

str

next_url(current_url)

Construct a URL to the next group of results for this query.

Parameters:

current_url (URL) – The starting URL of the current group of entries.

Returns:

URL to the next group of entries for this query or None if there are no further entries.

Return type:

str or None

prev_url(current_url)

Construct a URL to the previous group of results for this query.

Parameters:

current_url (URL) – The starting URL of the current group of entries.

Returns:

URL to the previous group of entries for this query or None if there are no further entries.

Return type:

str or None