==========

Pagination

==========

.. module:: django.core.paginator

   :synopsis: Classes to help you easily manage paginated data.

.. versionchanged:: 1.0

   Pagination facilities have been almost fully reworked.

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

    >>> p.page_range

    [1, 2]

    >>> 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()

    3

    >>> 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 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, InvalidPage, EmptyPage

    def listing(request):

        contact_list = Contacts.objects.all()

        paginator = Paginator(contact_list, 25) # Show 25 contacts per page

        # Make sure page request is an int. If not, deliver first page.

        try:

            page = int(request.GET.get('page', '1'))

        except ValueError:

            page = 1

        # If page request (9999) is out of range, deliver last page of results.

        try:

            contacts = paginator.page(page)

        except (EmptyPage, InvalidPage):

            contacts = paginator.page(paginator.num_pages)

        return render_to_response('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::

    {% for contact in contacts.object_list %}

        {# 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={{ 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>

            {% 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, Django ``QuerySet``, or other sliceable object with a

    ``count()`` or ``__len__()`` method.

``per_page``

    The maximum number of items to include on a page, not including orphans

    (see the ``orphans`` optional argument below).

Optional arguments

------------------

``orphans``

    The minimum number of items allowed on the last page, defaults to zero.

    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.

``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.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 ``object_list.__len__()``. 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 of page numbers, e.g., ``[1, 2, 3, 4]``.

``InvalidPage`` exceptions

==========================

The ``page()`` method raises ``InvalidPage`` if the requested page is invalid

(i.e., not an integer) or contains no objects. Generally, it's enough to trap

the ``InvalidPage`` exception, but if you'd like more granularity, you can trap

either of the following exceptions:

``PageNotAnInteger``

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

``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 a simple ``except InvalidPage``.

``Page`` objects

================

.. class:: Page(object_list, number, paginator)

You usually won't construct :class:`Pages <Page>` by hand -- you'll get them

using :meth:`Paginator.page`.

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. Note that this is "dumb" and will return the

    next page number regardless of whether a subsequent page exists.

.. method:: Page.previous_page_number()

    Returns the previous page number. Note that this is "dumb" and will return

    the previous page number regardless of whether a previous page exists.

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