# Django 4.0.11.dev20230214085346 documentation

# Paginator

Django provides a few classes that help you manage paginated data – that is, data that’s split across several pages, with “Previous/Next” links. These classes live in django/core/paginator.py.

For examples, see the Pagination topic guide.

## `Paginator` class

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

  A paginator acts like a sequence of `Page` when using `len()` or iterating it directly.

`Paginator.``object_list`

  Required. A list, tuple, `QuerySet`, or other sliceable object with a `count()` or `__len__()` method. For consistent pagination, `QuerySet`s should be ordered, e.g. with an `order_by()` clause or with a default `ordering` on the model.

  Performance issues paginating large `QuerySet`s

  If you’re using a `QuerySet` with a very large number of items, requesting high page numbers might be slow on some databases, because the resulting `LIMIT`/`OFFSET` query needs to count the number of `OFFSET` records which takes longer as the page number gets higher.

`Paginator.``per_page`

  Required. The maximum number of items to include on a page, not including orphans (see the `orphans` optional argument below).

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

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

### Methods

`Paginator.``get_page`(number)

  Returns a `Page` object with the given 1-based index, while also handling out of range and invalid page numbers.

  If the page isn’t a number, it returns the first page. If the page number is negative or greater than the number of pages, it returns the last page.

  Raises an `EmptyPage` exception only if you specify `Paginator(..., allow_empty_first_page=False)` and the `object_list` is empty.

`Paginator.``page`(number)

  Returns a `Page` object with the given 1-based index. Raises `PageNotAnInteger` if the `number` cannot be converted to an integer by calling `int()`. Raises `EmptyPage` if the given page number doesn’t exist.

`Paginator.``get_elided_page_range`(number, *, on_each_side=3, on_ends=2)
  New in Django 3.2.

  Returns a 1-based list of page numbers similar to `Paginator.page_range`, but may add an ellipsis to either or both sides of the current page number when `Paginator.num_pages` is large.

  The number of pages to include on each side of the current page number is determined by the `on_each_side` argument which defaults to 3.

  The number of pages to include at the beginning and end of page range is determined by the `on_ends` argument which defaults to 2.

  For example, with the default values for `on_each_side` and `on_ends`, if the current page is 10 and there are 50 pages, the page range will be `[1, 2, '…', 7, 8, 9, 10, 11, 12, 13, '…', 49, 50]`. This will result in pages 7, 8, and 9 to the left of and 11, 12, and 13 to the right of the current page as well as pages 1 and 2 at the start and 49 and 50 at the end.

  Raises `InvalidPage` if the given page number doesn’t exist.

### Attributes

`Paginator.``ELLIPSIS`
  New in Django 3.2.

  A translatable string used as a substitute for elided page numbers in the page range returned by `get_elided_page_range()`. Default is `'…'`.

`Paginator.``count`

  The total number of objects, across all pages.

  Note

  When determining the number of objects contained in `object_list`, `Paginator` will first try calling `object_list.count()`. If `object_list` has no `count()` method, then `Paginator` will fall back to using `len(object_list)`. This allows objects, such as `QuerySet`, to use a more efficient `count()` method when available.

`Paginator.``num_pages`

  The total number of pages.

`Paginator.``page_range`

  A 1-based range iterator of page numbers, e.g. yielding `[1, 2, 3, 4]`.

## `Page` class

You usually won’t construct `Page` objects by hand – you’ll get them by iterating `Paginator`, or by using `Paginator.page()`.

class `Page`(object_list, number, paginator)

  A page acts like a sequence of `Page.object_list` when using `len()` or iterating it directly.

### Methods

`Page.``has_next`()

  Returns `True` if there’s a next page.

`Page.``has_previous`()

  Returns `True` if there’s a previous page.

`Page.``has_other_pages`()

  Returns `True` if there’s a next or previous page.

`Page.``next_page_number`()

  Returns the next page number. Raises `InvalidPage` if next page doesn’t exist.

`Page.``previous_page_number`()

  Returns the previous page number. Raises `InvalidPage` if previous page doesn’t exist.

`Page.``start_index`()

  Returns the 1-based index of the first object on the page, relative to all of the objects in the paginator’s list. For example, when paginating a list of 5 objects with 2 objects per page, the second page’s `start_index()` would return `3`.

`Page.``end_index`()

  Returns the 1-based index of the last object on the page, relative to all of the objects in the paginator’s list. For example, when paginating a list of 5 objects with 2 objects per page, the second page’s `end_index()` would return `4`.

### Attributes

`Page.``object_list`

  The list of objects on this page.

`Page.``number`

  The 1-based page number for this page.

`Page.``paginator`

  The associated `Paginator` object.

## Exceptions

exception `InvalidPage`

  A base class for exceptions raised when a paginator is passed an invalid page number.

The `Paginator.page()` method raises an exception if the requested page is invalid (i.e. not an integer) or contains no objects. Generally, it’s enough to catch the `InvalidPage` exception, but if you’d like more granularity, you can catch either of the following exceptions:

exception `PageNotAnInteger`

  Raised when `page()` is given a value that isn’t an integer.

exception `EmptyPage`

  Raised when `page()` is given a valid value but no objects exist on that page.

Both of the exceptions are subclasses of `InvalidPage`, so you can handle them both with `except InvalidPage`.