Pagination

Django propose quelques classes pour aider à gérer des données paginées, c’est-à-dire des données divisées en plusieurs pages avec des liens « Précédent/Suivant ». Ces classes se trouvent dans django/core/paginator.py.

Pour des exemples, consultez le guide thématique sur la pagination.

Classe Paginator

class Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None)[source]

Un paginateur se comporte comme une liste d’objets Page lorsqu’on lui applique len() ou qu’on itère directement sur lui.

Paginator.object_list

Obligatoire. Une liste, un tuple, un QuerySet ou tout autre objet segmentable et doté d’une méthode count() ou __len__(). Pour une pagination cohérente, les QuerySet doivent être triés, par ex. avec une clause order_by() ou avec un tri par défaut ordering sur le modèle.

Problèmes de performances avec la pagination de QuerySet volumineux

Si vous utilisez un QuerySet avec un très grand nombre d’éléments, la récupération de numéros de page élevés peut être lent avec certaines bases de données, car la requête LIMIT/OFFSET résultante a besoin de compter le nombre d’enregistrements OFFSET, ce qui prend plus de temps avec des numéros de page élevés.

Paginator.per_page

Obligatoire. Le nombre maximum d’éléments à inclure dans une page, sans tenir compte des orphelins (voir le paramètre facultatif orphans ci-dessous).

Paginator.orphans

Optional. Use this when you don’t want to have a last page with very few items. If the last page would normally have a number of items less than or equal to orphans, then those items will be added to the previous page (which becomes the last page) instead of leaving the items on a page by themselves. For example, with 23 items, per_page=10, and orphans=3, there will be two pages; the first page with 10 items and the second (and last) page with 13 items. orphans defaults to zero, which means pages are never combined and the last page may have one item. orphans should be less than the per_page value.

Deprecated since version 6.0: Support for the orphans argument being larger than or equal to the per_page argument is deprecated.

Paginator.allow_empty_first_page

Optional. Whether or not the first page is allowed to be empty. If False and object_list is empty, then an EmptyPage error will be raised.

Paginator.error_messages

Le paramètre error_messages permet de redéfinir les messages par défaut que le paginateur génère. Passez un dictionnaire dont les clés correspondent aux messages d’erreur que vous voulez redéfinir. Les clés de messages d’erreur disponibles sont : invalid_page, min_page et no_results.

Par exemple, voici le message d’erreur par défaut :

>>> 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

Et voici un message d’erreur personnalisé :

>>> 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

Méthodes

Paginator.get_page(number)[source]

Renvoie un objet Page correspondant à l’index number (commençant à 1), en gérant également les numéros de page non valides ou hors limites.

Si la page n’est pas un nombre, la première page est renvoyée. Si le numéro de page est négatif ou plus grand que le nombre de pages, c’est la dernière page qui est renvoyée.

Ne produit une exception EmptyPage que si vous indiquez Paginator(..., allow_empty_first_page=False) et que object_list est vide.

Paginator.page(number)[source]

Renvoie un objet Page correspondant à l’index number (commençant à 1). Si number ne peut pas être converti en nombre entier avec int(), une exception PageNotAnInteger est produite. Si le numéro de page indiqué n’existe pas, une exception EmptyPage est produite.

Paginator.get_elided_page_range(number, *, on_each_side=3, on_ends=2)[source]

Renvoie une liste (commençant à 1) de numéros de pages comme avec Paginator.page_range mais peut appliquer une élision avant et après le numéro de page actuel lorsque Paginator.num_pages est grand.

Le nombre de pages à inclure de part et d’autre du numéro de page actuel est déterminé par l’argument on_each_side qui vaut 3 par défaut.

Le nombre de pages à inclure au début et à la fin de l’intervalle de pages est déterminé par l’argument on_ends qui vaut 2 par défaut.

Par exemple, avec les valeurs par défaut pour on_each_side et on_ends, si la page actuelle est 10 et qu’il y a 50 pages, l’intervalle de pages sera [1, 2, '…', 7, 8, 9, 10, 11, 12, 13, '…', 49, 50]. On trouve donc les pages 7, 8, 9 à la gauche et les pages 11, 12, 13 à la droite de la page actuelle, avec les pages 1, 2 au début et 49, 50 à la fin.

Génère InvalidPage si le numéro de page indiqué n’existe pas.

Attributs

Paginator.ELLIPSIS

Une chaîne traduisible utilisée comme substituant pour l’élision des numéros de pages dans l’intervalle de pages renvoyé par get_elided_page_range(). La valeur par défaut est '…'.

Paginator.count[source]

Le nombre total d’objets sur toutes les pages.

Note

Lors de la détermination du nombre d’objets contenus dans object_list, Paginator essaie d’abord d’appeler object_list.count(). Si object_list n’a pas de méthode count(), Paginator se rabat sur len(object_list). Cela permet à des objets comme les QuerySet d’utiliser une méthode count() plus efficace le cas échéant.

Paginator.num_pages[source]

Le nombre total de pages.

Paginator.page_range[source]

Une itération d’intervalle de numéros de pages commençant à 1, par ex. produisant [1, 2, 3, 4].

AsyncPaginator class

New in Django 6.0.

class AsyncPaginator(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None)[source]

Asynchronous version of Paginator.

AsyncPaginator has the same attributes and signatures as Paginator, with the following exceptions:

• The attribute Paginator.count is supported as an asynchronous method AsyncPaginator.acount().

• The attribute Paginator.num_pages is supported as an asynchronous method AsyncPaginator.anum_pages().

• The attribute Paginator.page_range is supported as an asynchronous method AsyncPaginator.apage_range().

AsyncPaginator has asynchronous versions of the same methods as Paginator, using an a prefix - for example, use await async_paginator.aget_page(number) rather than paginator.get_page(number).

Classe Page

Les objets Page ne sont normalement pas construits manuellement, mais plutôt obtenus en itérant sur Paginator ou en appelant Paginator.page().

class Page(object_list, number, paginator)[source]

Une page se comporte comme un liste de Page.object_list lorsqu’on lui applique len() ou qu’on effectue une itération sur elle.

Méthodes

Page.has_next()[source]

Renvoie True s’il existe une page suivante.

Page.has_previous()[source]

Renvoie True s’il existe une page précédente.

Page.has_other_pages()[source]

Renvoie True s’il existe une page suivante ou une page précédente.

Page.next_page_number()[source]

Renvoie le prochain numéro de page. Génère InvalidPage s’il n’y a pas de page suivante.

Page.previous_page_number()[source]

Renvoie le numéro de page précédent. Génère InvalidPage s’il n’y a pas de page précédente.

Page.start_index()[source]

Renvoie l’index (commençant par 1) du premier objet de la page, relatif à tous les autres objets de la liste du paginateur. Par exemple, lors de la pagination d’une liste de 5 objets par groupes de 2, la méthode start_index() de la deuxième page renverrait 3.

Page.end_index()[source]

Renvoie l’index (commençant par 1) du dernier objet de la page, relatif à tous les autres objets de la liste du paginateur. Par exemple, lors de la pagination d’une liste de 5 objets par groupes de 2, la méthode end_index() de la deuxième page renverrait 4.

Attributs

Page.object_list

La liste des objets de cette page.

Page.number

Le numéro de page (commençant par 1) de cette page.

Page.paginator

L’objet Paginator associé.

AsyncPage class

New in Django 6.0.

class AsyncPage(object_list, number, paginator)[source]

Asynchronous version of Page.

AsyncPage has the same attributes and signatures as Page, as well as asynchronous versions of all the same methods, using an a prefix - for example, use await async_page.ahas_next() rather than page.has_next().

AsyncPage has the following additional method:

aget_object_list()

Returns AsyncPage.object_list as a list. This method must be awaited before AsyncPage can be treated as a sequence of AsyncPage.object_list.

Exceptions

exception InvalidPage[source]

Une classe de base pour les exceptions levées lorsqu’un paginateur reçoit un numéro de page non valable.

La méthode Paginator.page() lève une exception quand la page demandée n’est pas valable (par ex. pas un nombre entier) ou quand elle ne contient aucun objet. Il est généralement suffisant d’intercepter l’exception InvalidPage, mais si vous souhaitez plus de finesse, vous pouvez intercepter l’une des exceptions suivantes :

exception PageNotAnInteger[source]

Générée lorsque page() reçoit une valeur qui n’est pas un nombre entier.

exception EmptyPage[source]

Générée lorsque page() reçoit une valeur valable, mais que la page en question ne contient pas d’objet.

Ces deux exceptions sont des sous-classes de InvalidPage, il est donc possible de les intercepter toutes deux par une ligne except InvalidPage.