---
title: "Pagination"
version: 6.0
locale: fr
source: https://docs.djangoproject.com/fr/6.0/ref/paginator/
canonical: https://djangodocs.dev/fr/6.0/ref/paginator/
---
# 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](https://github.com/django/django/blob/stable/6.0.x/django/core/paginator.py).

Pour des exemples, consultez le [guide thématique sur la pagination](/fr/6.0/topics/pagination/).

## Classe `Paginator`

#### `class Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None)`

Un paginateur se comporte comme une liste d’objets [`Page`](#django.core.paginator.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()`](/fr/6.0/ref/models/querysets/#django.db.models.query.QuerySet.order_by) ou avec un tri par défaut [`ordering`](/fr/6.0/ref/models/options/#django.db.models.Options.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`](#django.core.paginator.Paginator.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`  et `orphans=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. La valeur `orphans` doit être plus petite que la valeur [`per_page`](#django.core.paginator.Paginator.per_page).

> **Deprecated since Django 6.0**
>
> Obsolète depuis la 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`

Facultatif. Indique si la première page peut être vide. Avec la valeur `False` et une liste `object_list` vide, une erreur `EmptyPage` sera produite.

#### `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 :

```pycon
>>> 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é :

```pycon
>>> 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)`

Renvoie un objet [`Page`](#django.core.paginator.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`](#django.core.paginator.EmptyPage) que si vous indiquez `Paginator(..., allow_empty_first_page=False)` et que `object_list` est vide.

#### `Paginator.page(number)`

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

#### `Paginator.get_elided_page_range(number, * (Keyword-only parameters separator (PEP 3102)), on_each_side=3, on_ends=2)`

Renvoie une liste (commençant à 1) de numéros de pages comme avec [`Paginator.page_range`](#django.core.paginator.Paginator.page_range) mais peut appliquer une élision avant et après le numéro de page actuel lorsque [`Paginator.num_pages`](#django.core.paginator.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`](#django.core.paginator.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()`](#django.core.paginator.Paginator.get_elided_page_range). La valeur par défaut est `'…'`.

#### `Paginator.count`

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`

Le nombre total de pages.

#### `Paginator.page_range`

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

## Classe `AsyncPaginator`

> **New in Django 6.0**

#### `class AsyncPaginator(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None)`

Version asynchrone de [`Paginator`](#django.core.paginator.Paginator).

`AsyncPaginator` has the same attributes and signatures as
[`Paginator`](#django.core.paginator.Paginator), with the following exceptions:

- The attribute [`Paginator.count`](#django.core.paginator.Paginator.count) is supported as an asynchronous
  method `AsyncPaginator.acount()`.
- The attribute [`Paginator.num_pages`](#django.core.paginator.Paginator.num_pages) is supported as an
  asynchronous method `AsyncPaginator.anum_pages()`.
- The attribute [`Paginator.page_range`](#django.core.paginator.Paginator.page_range) is supported as an
  asynchronous method `AsyncPaginator.apage_range()`.

`AsyncPaginator` has asynchronous versions of the same methods as
[`Paginator`](#django.core.paginator.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`](#django.core.paginator.Paginator) ou en appelant [`Paginator.page()`](#django.core.paginator.Paginator.page).

#### `class Page(object_list, number, paginator)`

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

### Méthodes

#### `Page.has_next()`

Renvoie `True` s’il existe une page suivante.

#### `Page.has_previous()`

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

#### `Page.has_other_pages()`

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

#### `Page.next_page_number()`

Renvoie le prochain numéro de page. Génère [`InvalidPage`](#django.core.paginator.InvalidPage) s’il n’y a pas de page suivante.

#### `Page.previous_page_number()`

Renvoie le numéro de page précédent. Génère [`InvalidPage`](#django.core.paginator.InvalidPage) s’il n’y a pas de page précédente.

#### `Page.start_index()`

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()`](#django.core.paginator.Page.start_index) de la deuxième page renverrait `3`.

#### `Page.end_index()`

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()`](#django.core.paginator.Page.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`](#django.core.paginator.Paginator) associé.

## Classe `AsyncPage`

> **New in Django 6.0**

#### `class AsyncPage(object_list, number, paginator)`

Version asynchrone de [`Page`](#django.core.paginator.Page).

`AsyncPage` has the same attributes and signatures as [`Page`](#django.core.paginator.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`

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()`](#django.core.paginator.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`

Générée lorsque [`page()`](#django.core.paginator.Paginator.page) reçoit une valeur qui n’est pas un nombre entier.

#### `exception EmptyPage`

Générée lorsque [`page()`](#django.core.paginator.Paginator.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`](#django.core.paginator.InvalidPage), il est donc possible de les intercepter toutes deux par une ligne `except InvalidPage`.