پرش به محتویات

صفحه‌بندی

این صفحه از docstringهای خود کد ساخته می‌شود، که به انگلیسی‌اند.

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.

get_paginated_response_schema

get_paginated_response_schema(schema: dict[str, Any]) -> dict[str, Any]

The envelope a page answers in: the rows under data, the pager beside them.

pagination_meta

pagination_meta() -> dict[str, Any]

Everything a client needs to draw a pager, and nothing else.

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

encode_cursor(cursor: Cursor) -> str

The link to a page: its cursor signed, with the order it was made for.

decode_cursor

decode_cursor(request: Request) -> pagination.Cursor | None

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

get_paginated_response_schema(schema: dict[str, Any]) -> dict[str, Any]

The envelope a feed answers in: the rows under data, the cursors beside them.

pagination_meta

pagination_meta() -> dict[str, Any]

The cursors to send back, and whether there is anything to send them for.