========== Pagination ========== .. module:: django.core.paginator :synopsis: Classes to help you easily manage paginated data. 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 :file:`django/core/paginator.py`. Example ======= Give :class:`Paginator` a list of objects, plus the number of items you'd like to have on each page, and it gives you methods for accessing the items for each page:: >>> from django.core.paginator import Paginator >>> objects = ['john', 'paul', 'george', 'ringo'] >>> p = Paginator(objects, 2) >>> p.count 4 >>> p.num_pages 2 >>> type(p.page_range) >>> p.page_range range(1, 3) >>> page1 = p.page(1) >>> page1 >>> page1.object_list ['john', 'paul'] >>> page2 = p.page(2) >>> page2.object_list ['george', 'ringo'] >>> page2.has_next() False >>> page2.has_previous() True >>> page2.has_other_pages() True >>> page2.next_page_number() Traceback (most recent call last): ... EmptyPage: That page contains no results >>> page2.previous_page_number() 1 >>> page2.start_index() # The 1-based index of the first item on this page 3 >>> page2.end_index() # The 1-based index of the last item on this page 4 >>> p.page(0) Traceback (most recent call last): ... EmptyPage: That page number is less than 1 >>> p.page(3) Traceback (most recent call last): ... EmptyPage: That page contains no results .. note:: Note that you can give ``Paginator`` a list/tuple, a Django ``QuerySet``, or any other object with a ``count()`` or ``__len__()`` method. When determining the number of objects contained in the passed object, ``Paginator`` will first try calling ``count()``, then fallback to using ``len()`` if the passed object has no ``count()`` method. This allows objects such as Django's ``QuerySet`` to use a more efficient ``count()`` method when available. .. _using-paginator-in-view: Using ``Paginator`` in a view ============================= Here's a slightly more complex example using :class:`Paginator` in a view to paginate a queryset. We give both the view and the accompanying template to show how you can display the results. This example assumes you have a ``Contacts`` model that has already been imported. The view function looks like this:: from django.core.paginator import Paginator from django.shortcuts import render def listing(request): contact_list = Contacts.objects.all() paginator = Paginator(contact_list, 25) # Show 25 contacts per page page = request.GET.get('page') contacts = paginator.get_page(page) return render(request, 'list.html', {'contacts': contacts}) In the template :file:`list.html`, you'll want to include navigation between pages along with any interesting information from the objects themselves: .. code-block:: html+django {% for contact in contacts %} {# Each "contact" is a Contact model object. #} {{ contact.full_name|upper }}
... {% endfor %} ``Paginator`` objects ===================== The :class:`Paginator` class has this constructor: .. class:: Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True) Required arguments ------------------ ``object_list`` 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 :meth:`~django.db.models.query.QuerySet.order_by` clause or with a default :attr:`~django.db.models.Options.ordering` on the model. .. admonition:: 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. ``per_page`` The maximum number of items to include on a page, not including orphans (see the ``orphans`` optional argument below). Optional arguments ------------------ ``orphans`` 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. ``allow_empty_first_page`` 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 ------- .. method:: Paginator.get_page(number) Returns a :class:`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. It raises an exception (:exc:`EmptyPage`) only if you specify ``Paginator(..., allow_empty_first_page=False)`` and the ``object_list`` is empty. .. method:: Paginator.page(number) Returns a :class:`Page` object with the given 1-based index. Raises :exc:`InvalidPage` if the given page number doesn't exist. Attributes ---------- .. attribute:: 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 fallback to using ``len(object_list)``. This allows objects, such as Django's ``QuerySet``, to use a more efficient ``count()`` method when available. .. attribute:: Paginator.num_pages The total number of pages. .. attribute:: Paginator.page_range A 1-based range iterator of page numbers, e.g. yielding ``[1, 2, 3, 4]``. ``InvalidPage`` exceptions ========================== .. exception:: InvalidPage A base class for exceptions raised when a paginator is passed an invalid page number. The :meth:`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 :exc:`InvalidPage`, so you can handle them both with a simple ``except InvalidPage``. ``Page`` objects ================ You usually won't construct ``Page`` objects by hand -- you'll get them using :meth:`Paginator.page`. .. class:: Page(object_list, number, paginator) A page acts like a sequence of :attr:`Page.object_list` when using ``len()`` or iterating it directly. Methods ------- .. method:: Page.has_next() Returns ``True`` if there's a next page. .. method:: Page.has_previous() Returns ``True`` if there's a previous page. .. method:: Page.has_other_pages() Returns ``True`` if there's a next *or* previous page. .. method:: Page.next_page_number() Returns the next page number. Raises :exc:`InvalidPage` if next page doesn't exist. .. method:: Page.previous_page_number() Returns the previous page number. Raises :exc:`InvalidPage` if previous page doesn't exist. .. method:: 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 :meth:`~Page.start_index` would return ``3``. .. method:: 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 :meth:`~Page.end_index` would return ``4``. Attributes ---------- .. attribute:: Page.object_list The list of objects on this page. .. attribute:: Page.number The 1-based page number for this page. .. attribute:: Page.paginator The associated :class:`Paginator` object.