django/docs/topics/pagination.txt

==========
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)
    <class 'range_iterator'>
    >>> p.page_range
    range(1, 3)

    >>> page1 = p.page(1)
    >>> page1
    <Page 1 of 2>
    >>> 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.

Paginating a ``ListView``
=========================

:class:`django.views.generic.list.ListView` provides a builtin way to paginate
the displayed list. You can do this by adding
:attr:`~django.views.generic.list.MultipleObjectMixin.paginate_by` attribute to
your view class, for example::

    from django.views.generic import ListView

    from myapp.models import Contacts

    class ContactsList(ListView):
        paginate_by = 2
        model = Contacts

The only thing your users will be missing is a way to navigate to the next or
previous page. To achieve this, add links to the next and previous page, like
shown in the below example ``list.html``.

.. _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 }}<br>
        ...
    {% endfor %}

    <div class="pagination">
        <span class="step-links">
            {% if contacts.has_previous %}
                <a href="?page=1">&laquo; first</a>
                <a href="?page={{ contacts.previous_page_number }}">previous</a>
            {% endif %}

            <span class="current">
                Page {{ contacts.number }} of {{ contacts.paginator.num_pages }}.
            </span>

            {% if contacts.has_next %}
                <a href="?page={{ contacts.next_page_number }}">next</a>
                <a href="?page={{ contacts.paginator.num_pages }}">last &raquo;</a>
            {% endif %}
        </span>
    </div>

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