|
|
@@ -2,19 +2,23 @@
|
|
|
Pagination
|
|
|
==========
|
|
|
|
|
|
-.. module:: django.core.paginator
|
|
|
- :synopsis: Classes to help you easily manage paginated data.
|
|
|
+Django provides high-level and low-level ways to help you manage paginated data
|
|
|
+-- that is, data that's split across several pages, with "Previous/Next" links.
|
|
|
|
|
|
-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`.
|
|
|
+The ``Paginator`` class
|
|
|
+=======================
|
|
|
+
|
|
|
+Under the hood, all methods of pagination use the
|
|
|
+:class:`~django.core.paginator.Paginator` class. It does all the heavy lifting
|
|
|
+of actually splitting a ``QuerySet`` into parts and handing them over to other
|
|
|
+components.
|
|
|
|
|
|
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::
|
|
|
+Give :class:`~django.core.paginator.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']
|
|
|
@@ -99,10 +103,11 @@ shown in the below example ``list.html``.
|
|
|
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.
|
|
|
+Here's a slightly more complex example using
|
|
|
+:class:`~django.core.paginator.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::
|
|
|
|
|
|
@@ -145,183 +150,3 @@ pages along with any interesting information from the objects themselves:
|
|
|
{% 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.
|
luto