Pagination¶
pagination
¶
Pagination, in the envelope.
Two kinds, and each view chooses - a numbered list in one, an endless feed
in the next. pagination.type says which, so one component on a client
reads either without guessing:
"pagination": {"type": "page", "count": 45, "page": 2, "pages": 3,
"page_size": 20, "has_next": true, "has_previous": true}
"pagination": {"type": "cursor", "next_cursor": "cD0y...", "previous_cursor": null,
"page_size": 20, "has_next": true, "has_previous": false}
The page size is read from the view, then the paginator, then
DRF_PARCEL['PAGE_SIZE'], then DRF's own PAGE_SIZE. A client may choose it only where that is
allowed - client_page_size on the view or the paginator, or
DRF_PARCEL['CLIENT_PAGE_SIZE'] - and always under a ceiling: without
one, ?page_size=1000000 is a request to read a whole table, open to
anybody. A size the client cannot have is not an error: it is the ceiling,
or the default.
PageNumberPagination
¶
Bases: _PageSize, PageNumberPagination
Numbered pages: ?page=2.
No next or previous link: a client on another domain builds
?page=3 itself, and a server behind a proxy builds its own links with
the wrong scheme or host. A page past the end is a 404, as DRF answers.
CursorPagination
¶
Bases: _PageSize, CursorPagination
An endless feed: ?cursor=....
The client sends back what it was given. There is no count and no page number: not counting is the point of a cursor, on a table too large to count on every request.
The order is the view's ordering, or the paginator's; an ordering
filter on the view, when there is one, decides as DRF's does.
A cursor is signed with the project's SECRET_KEY and carries the order
it was made for. One changed by hand, one made for another order, or one
that cannot be read is refused - 400 invalid_cursor - before the
database is asked; so whatever goes wrong while a page is read is a real
bug, and is answered and reported as one. Signed, not encrypted: a cursor
can be decoded, and holds the value the feed is ordered by.
encode_cursor
¶
The link to a page: its cursor signed, with the order it was made for.
decode_cursor
¶
The cursor a client sent back - or 400 invalid_cursor, before any query.
DRF has already settled the order asked for now, so a cursor made for another one is told apart here: its rows would be read against a column it holds no value of.
get_paginated_response_schema
¶
The envelope a feed answers in: the rows under data, the cursors beside them.
pagination_meta
¶
The cursors to send back, and whether there is anything to send them for.