Pagination

pagination

Lazy collections over Django REST Framework style list endpoints.

Classes:

Name	Description
Page	One page of results from a list endpoint.
PaginatedList	An iterable view over a paginated endpoint that fetches pages on demand.

Functions:

Name	Description
to_dataframe	Convert models (or plain dicts) into a pandas.DataFrame.

PANDAS_INSTALL_HINT module-attribute

PANDAS_INSTALL_HINT = "pandas is required for .to_df(); install it with `uv add 'datamermaid[pandas]'` or `pip install 'datamermaid[pandas]'`"

Page dataclass

Page(
    items: list[T] = list(),
    next_url: str | None = None,
    count: int | None = None,
)

Bases: Generic[T]

One page of results from a list endpoint.

Attributes:

Name	Type	Description
items	list[T]
next_url	str | None
count	int | None

items class-attribute instance-attribute

items: list[T] = field(default_factory=list)

next_url class-attribute instance-attribute

next_url: str | None = None

count class-attribute instance-attribute

count: int | None = None

PaginatedList

PaginatedList(
    fetch_page: Callable[[str | None], Page[T]],
)

Bases: Generic[T]

An iterable view over a paginated endpoint that fetches pages on demand.

Nothing is requested until the list is iterated, indexed, or measured. Fetched items are cached, so re-iterating or indexing backwards never issues another request.

Methods:

Name	Description
to_df	Materialise every page and return the results as a DataFrame.

Attributes:

Name	Type	Description
count	int | None	Total number of matching records, as reported by the API.
fetched	list[T]	The items fetched so far, without triggering a request.

count property

count: int | None

Total number of matching records, as reported by the API.

fetched property

fetched: list[T]

The items fetched so far, without triggering a request.

to_df

to_df(**kwargs: Any) -> DataFrame

Materialise every page and return the results as a DataFrame.

Requires the optional pandas extra.

to_dataframe

to_dataframe(items: list[Any], **kwargs: Any) -> DataFrame

Convert models (or plain dicts) into a pandas.DataFrame.