Pager

Overview

Pager service sets the upper and lower bounds on data used by collection. When collection is used in loops, it gets position of the first and last record from the pager and passes these values to range method of the data service. The result is iterated over.

Collection uses ClassicPager by default. It implements pagination using page and rows_per_page parameters. These settings of the pager service are used to compute pager.start and pager.end.

Default value of the rows_per_page is 10, and page is set to 1.

>>> col = collection.Collection(
>>>     data_factory=data.StaticData,
>>>     data_settings={"data": range(1, 100)},
>>> )
>>> col.pager.start
0
>>> col.pager.end
10
>>> list(col)
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

If page is passed to pager_settings of the collection, or directly to the pager constructor, it modifies start and end.

>>> pager.ClassicPager(col, page=3)
>>> col.pager.start
20
>>> col.pager.end
30
>>> list(col)
[21, 22, 23, 24, 25, 26, 27, 28, 29, 30]

rows_per_page controls the max number of items for a single page.

>>> col = collection.Collection(
>>>     data_factory=data.StaticData,
>>>     data_settings={"data": range(1, 100)},
>>>     pager_settings={"rows_per_page": 3, "page": 5},
>>> )
>>> col.pager.start
12
>>> col.pager.end
15
>>> list(col)
[13, 14, 15]

Pagination details are often mixed with data filters, so ClassicPager, used by default in Collection, check if page and rows_per_page are available in params of the collection. If so, these values are used instead of pager settings.

Example

In this example collection have different pager settings specified by params(second positional argument) and pager_settings. In such situation params have higher priority and pager_settings are ignored.

>>> col = collection.Collection(
>>>     "",
>>>     {"rows_per_page": 1, "page": 2}, # (1)!
>>>     data_factory=data.StaticData,
>>>     data_settings={"data": range(1, 100)},
>>>     pager_settings={"rows_per_page": 3, "page": 5},  # (2)!
>>> )
>>> col.pager.start
1
>>> col.pager.end
2
>>> list(col)
[2]

1. params have higher priority and will be used by collection when present
2. pager_settings are not used because they conflict with params

Available pager factories

Pager

Base for pager service.

This class must be extended by every implementation of the pager service.

Example

class StaticPager(Pager):
    @property
    def start(self) -> int:
        return 0

    @property
    def end(self) -> int:
        return 10

    @property
    def size(self) -> int:
        return 10

ClassicPager

Page-number based pagination.

ATTRIBUTE	DESCRIPTION
page	current active page TYPE: int
rows_per_page	max number of items per page TYPE: int
prioritize_params	if params contain pagination details, use them instead of pager_settings. Defaults to True. TYPE: bool

Example

>>> col = collection.Collection(
>>>     data_factory=data.StaticData,
>>>     data_settings={"data": range(1, 100)},
>>>     pager_factory=pager.ClassicPager,
>>>     pager_settings={"page": 2, "rows_per_page": 5},
>>> )
>>> list(col)
[6, 7, 8, 9, 10]

OffsetPager

Limit/offset based pagination.

ATTRIBUTE	DESCRIPTION
offset	number of items to skip TYPE: int
limit	max number of items per page TYPE: int

Example

>>> col = collection.Collection(
>>>     data_factory=data.StaticData,
>>>     data_settings={"data": range(1, 100)},
>>>     pager_factory=pager.OffsetPager,
>>>     pager_settings={"offset": 2, "limit": 3},
>>> )
>>> list(col)
[3, 4, 5]

TemporalPager

Date based pagination.

Data service of the collection that uses TemporalPager must implement range as range(start: date | None, end: date | None).

ATTRIBUTE	DESCRIPTION
since	date of the oldest record(>=) TYPE: date | None
until	date of the newest record(<) TYPE: date | None

Example

Define data service that supports date ranges.

from datetime import datetime, timedelta

class TemporalModelData(data.TemporalSaData, data.ModelData):
    pass

Initialize the collection

>>> col = collection.Collection(
>>>     data_factory=TemporalModelData,
>>>     data_settings={
>>>         "model": model.Package,
>>>         "temporal_column": model.Package.metadata_created,
>>>     },
>>>     pager_factory=pager.TemporalPager,
>>>     pager_settings={"since": datetime.now() - timedelta(days=1)},
>>> )
>>> list(col)
[(...package created yesterday), ...]