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 appliquelen()
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éthodecount()
ou__len__()
. Pour une pagination cohérente, lesQuerySet
doivent être triés, par ex. avec une clauseorder_by()
ou avec un tri par défautordering
sur le modèle.Problèmes de performances avec la pagination de
QuerySet
volumineuxSi 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êteLIMIT
/OFFSET
résultante a besoin de compter le nombre d’enregistrementsOFFSET
, 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
¶ Facultatif. Utilisez ce paramètre lorsque vous ne souhaitez pas de dernière page avec très peu d’éléments. Lorsque la dernière page ne contient que le nombre
orphans
d’éléments ou moins, ces éléments sont alors ajoutés à la page précédente (qui devient la dernière page) au lieu de les laisser seuls sur une page. Par exemple, avec 23 éléments,per_page=10
etorphans=3
, il y aura deux pages ; la première avec 10 éléments et la seconde (et dernière) avec 13 éléments.orphans
vaut zéro par défaut, ce qui signifie que les pages ne sont jamais jointes et que la dernière page peut ne posséder qu’un seul élément.
-
Paginator.
allow_empty_first_page
¶ Facultatif. Indique si la première page peut être vide. Avec la valeur
False
et une listeobject_list
vide, une erreurEmptyPage
sera produite.
-
Paginator.
error_messages
¶ - New in Django 5.0.
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
etno_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’indexnumber
(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 indiquezPaginator(..., allow_empty_first_page=False)
et queobject_list
est vide.
-
Paginator.
page
(number)[source]¶ Renvoie un objet
Page
correspondant à l’indexnumber
(commençant à 1). Sinumber
ne peut pas être converti en nombre entier avecint()
, une exceptionPageNotAnInteger
est produite. Si le numéro de page indiqué n’existe pas, une exceptionEmptyPage
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 lorsquePaginator.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
eton_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’appelerobject_list.count()
. Siobject_list
n’a pas de méthodecount()
,Paginator
se rabat surlen(object_list)
. Cela permet à des objets comme lesQuerySet
d’utiliser une méthodecount()
plus efficace le cas échéant.
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 appliquelen()
ou qu’on effectue une itération sur elle.
Méthodes¶
-
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 renverrait3
.
-
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 renverrait4
.
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
.