Постраничная разбивка

Paginator класс

class Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None) [источник]

При использовании len() или прямом переборе объект paginator ведёт себя как последовательность объектов Page.

Paginator.object_list

Обязательный аргумент. Список, кортеж, QuerySet или другой объект, поддерживающий срезы и имеющий метод count() или __len__(). Для стабильного разбиения на страницы объекты QuerySet должны быть упорядочены, например с помощью предложения order_by() или заданного по умолчанию параметра ordering модели.

Проблемы производительности при разбиении больших наборов QuerySet на страницы

Если вы используете QuerySet с очень большим числом элементов, запрос страниц с большими номерами может выполняться медленно в некоторых базах данных, поскольку для выполнения результирующего запроса LIMIT/OFFSET необходимо подсчитать количество записей OFFSET, а с увеличением номера страницы это занимает больше времени.

Paginator.per_page

Обязательный аргумент. Максимальное число элементов на странице, не считая остатка (см. необязательный аргумент orphans ниже).

Paginator.orphans

Необязательный аргумент. Используйте его, если не хотите, чтобы на последней странице оставалось слишком мало элементов. Если на последней странице обычно было бы число элементов, меньшее или равное orphans, эти элементы будут добавлены на предыдущую страницу (которая станет последней), вместо того чтобы оставаться на отдельной странице. Например, при 23 элементах, per_page=10 и orphans=3 будет две страницы: на первой — 10 элементов, а на второй (последней) — 13. По умолчанию orphans равно нулю, то есть страницы никогда не объединяются, и на последней странице может остаться один элемент. Значение orphans должно быть меньше значения per_page.

Устарело с версии 6.0: Поддержка значения аргумента orphans, большего или равного значению аргумента per_page, объявлена устаревшей.

Paginator.allow_empty_first_page

Необязательный аргумент. Определяет, может ли первая страница быть пустой. Если False, а object_list пуст, будет вызвана ошибка EmptyPage.

Paginator.error_messages

Аргумент error_messages позволяет переопределить сообщения об ошибках, которые вызывает paginator по умолчанию. Передайте словарь с ключами, соответствующими сообщениям об ошибках, которые нужно переопределить. Доступны следующие ключи сообщений об ошибках: invalid_page, min_page и no_results.

Например, сообщение об ошибке по умолчанию выглядит так:

>>> from django.core.paginator import Paginator
>>> paginator = Paginator([1, 2, 3], 2)
>>> paginator.page(5)
Traceback (most recent call last):
  ...
EmptyPage: That page contains no results

А пользовательское сообщение об ошибке выглядит так:

>>> paginator = Paginator(
...     [1, 2, 3],
...     2,
...     error_messages={"no_results": "Page does not exist"},
... )
>>> paginator.page(5)
Traceback (most recent call last):
  ...
EmptyPage: Page does not exist

AsyncPaginator класс

class AsyncPaginator(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None) [источник]

Асинхронная версия Paginator.

AsyncPaginator имеет те же атрибуты и сигнатуры, что и Paginator, за следующими исключениями:

• Атрибут Paginator.count поддерживается как асинхронный метод AsyncPaginator.acount().
• Атрибут Paginator.num_pages поддерживается как асинхронный метод AsyncPaginator.anum_pages().
• Атрибут Paginator.page_range поддерживается как асинхронный метод AsyncPaginator.apage_range().

Для AsyncPaginator доступны асинхронные версии тех же методов, что и для Paginator; их имена имеют префикс a. Например, используйте await async_paginator.aget_page(number) вместо paginator.get_page(number).

Page класс

Обычно объекты Page не создают вручную — их получают при переборе Paginator или с помощью Paginator.page().

class Page(object_list, number, paginator) [источник]

При использовании len() или прямом переборе объект страницы ведёт себя как последовательность объектов Page.object_list.

AsyncPage класс

class AsyncPage(object_list, number, paginator) [источник]

Асинхронная версия Page.

AsyncPage имеет те же атрибуты и сигнатуры, что и Page, а также асинхронные версии всех тех же методов с префиксом a. Например, используйте await async_page.ahas_next() вместо page.has_next().

У AsyncPage есть следующий дополнительный метод:

aget_object_list()

Возвращает AsyncPage.object_list в виде списка. Прежде чем AsyncPage можно будет использовать как последовательность AsyncPage.object_list, необходимо дождаться выполнения этого метода.

Исключения

exception InvalidPage [источник]

Базовый класс исключений, вызываемых, если paginator передан недопустимый номер страницы.

Метод Paginator.page() вызывает исключение, если запрошенная страница недопустима (то есть номер не является целым числом) или не содержит объектов. Как правило, достаточно перехватить исключение InvalidPage, но для более точной обработки можно перехватывать каждое из следующих исключений:

exception PageNotAnInteger [источник]

Вызывается, если методу page() передано значение, не являющееся целым числом.

exception EmptyPage [источник]

Вызывается, если методу page() передано допустимое значение, но на этой странице нет объектов.

Оба исключения являются подклассами InvalidPage, поэтому их можно обрабатывать с помощью except InvalidPage.