| 1 |
========= |
| 2 |
Paginator |
| 3 |
========= |
| 4 |
|
| 5 |
Django provides a few classes that help you manage paginated data -- that is, |
| 6 |
data that's split across several pages, with "Previous/Next" links. These |
| 7 |
classes live in :source:`django/core/paginator.py`. |
| 8 |
|
| 9 |
For examples, see the :doc:`Pagination topic guide </topics/pagination>`. |
| 10 |
|
| 11 |
.. module:: django.core.paginator |
| 12 |
:synopsis: Classes to help you easily manage paginated data. |
| 13 |
|
| 14 |
``Paginator`` class |
| 15 |
=================== |
| 16 |
|
| 17 |
.. class:: Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None) |
| 18 |
|
| 19 |
A paginator acts like a sequence of :class:`Page` when using ``len()`` or |
| 20 |
iterating it directly. |
| 21 |
|
| 22 |
.. attribute:: Paginator.object_list |
| 23 |
|
| 24 |
Required. A list, tuple, ``QuerySet``, or other sliceable object with a |
| 25 |
``count()`` or ``__len__()`` method. For consistent pagination, |
| 26 |
``QuerySet``\s should be ordered, e.g. with an |
| 27 |
:meth:`~django.db.models.query.QuerySet.order_by` clause or with a default |
| 28 |
:attr:`~django.db.models.Options.ordering` on the model. |
| 29 |
|
| 30 |
.. admonition:: Performance issues paginating large ``QuerySet``\s |
| 31 |
|
| 32 |
If you're using a ``QuerySet`` with a very large number of items, |
| 33 |
requesting high page numbers might be slow on some databases, because |
| 34 |
the resulting ``LIMIT``/``OFFSET`` query needs to count the number of |
| 35 |
``OFFSET`` records which takes longer as the page number gets higher. |
| 36 |
|
| 37 |
.. attribute:: Paginator.per_page |
| 38 |
|
| 39 |
Required. The maximum number of items to include on a page, not including |
| 40 |
orphans (see the :attr:`~Paginator.orphans` optional argument below). |
| 41 |
|
| 42 |
.. attribute:: Paginator.orphans |
| 43 |
|
| 44 |
Optional. Use this when you don't want to have a last page with very few |
| 45 |
items. If the last page would normally have a number of items less than or |
| 46 |
equal to ``orphans``, then those items will be added to the previous page |
| 47 |
(which becomes the last page) instead of leaving the items on a page by |
| 48 |
themselves. For example, with 23 items, ``per_page=10``, and ``orphans=3``, |
| 49 |
there will be two pages; the first page with 10 items and the second |
| 50 |
(and last) page with 13 items. ``orphans`` defaults to zero, which means |
| 51 |
pages are never combined and the last page may have one item. |
| 52 |
|
| 53 |
.. attribute:: Paginator.allow_empty_first_page |
| 54 |
|
| 55 |
Optional. Whether or not the first page is allowed to be empty. If |
| 56 |
``False`` and ``object_list`` is empty, then an ``EmptyPage`` error will |
| 57 |
be raised. |
| 58 |
|
| 59 |
.. attribute:: Paginator.error_messages |
| 60 |
|
| 61 |
The ``error_messages`` argument lets you override the default messages that |
| 62 |
the paginator will raise. Pass in a dictionary with keys matching the error |
| 63 |
messages you want to override. Available error message keys are: |
| 64 |
``invalid_page``, ``min_page``, and ``no_results``. |
| 65 |
|
| 66 |
For example, here is the default error message: |
| 67 |
|
| 68 |
.. code-block:: pycon |
| 69 |
|
| 70 |
>>> from django.core.paginator import Paginator |
| 71 |
>>> paginator = Paginator([1, 2, 3], 2) |
| 72 |
>>> paginator.page(5) |
| 73 |
Traceback (most recent call last): |
| 74 |
... |
| 75 |
EmptyPage: That page contains no results |
| 76 |
|
| 77 |
And here is a custom error message: |
| 78 |
|
| 79 |
.. code-block:: pycon |
| 80 |
|
| 81 |
>>> paginator = Paginator( |
| 82 |
... [1, 2, 3], |
| 83 |
... 2, |
| 84 |
... error_messages={"no_results": "Page does not exist"}, |
| 85 |
... ) |
| 86 |
>>> paginator.page(5) |
| 87 |
Traceback (most recent call last): |
| 88 |
... |
| 89 |
EmptyPage: Page does not exist |
| 90 |
|
| 91 |
Methods |
| 92 |
------- |
| 93 |
|
| 94 |
.. method:: Paginator.get_page(number) |
| 95 |
|
| 96 |
Returns a :class:`Page` object with the given 1-based index, while also |
| 97 |
handling out of range and invalid page numbers. |
| 98 |
|
| 99 |
If the page isn't a number, it returns the first page. If the page number |
| 100 |
is negative or greater than the number of pages, it returns the last page. |
| 101 |
|
| 102 |
Raises an :exc:`EmptyPage` exception only if you specify |
| 103 |
``Paginator(..., allow_empty_first_page=False)`` and the ``object_list`` is |
| 104 |
empty. |
| 105 |
|
| 106 |
.. method:: Paginator.page(number) |
| 107 |
|
| 108 |
Returns a :class:`Page` object with the given 1-based index. Raises |
| 109 |
:exc:`PageNotAnInteger` if the ``number`` cannot be converted to an integer |
| 110 |
by calling ``int()``. Raises :exc:`EmptyPage` if the given page number |
| 111 |
doesn't exist. |
| 112 |
|
| 113 |
.. method:: Paginator.get_elided_page_range(number, *, on_each_side=3, on_ends=2) |
| 114 |
|
| 115 |
Returns a 1-based list of page numbers similar to |
| 116 |
:attr:`Paginator.page_range`, but may add an ellipsis to either or both |
| 117 |
sides of the current page number when :attr:`Paginator.num_pages` is large. |
| 118 |
|
| 119 |
The number of pages to include on each side of the current page number is |
| 120 |
determined by the ``on_each_side`` argument which defaults to 3. |
| 121 |
|
| 122 |
The number of pages to include at the beginning and end of page range is |
| 123 |
determined by the ``on_ends`` argument which defaults to 2. |
| 124 |
|
| 125 |
For example, with the default values for ``on_each_side`` and ``on_ends``, |
| 126 |
if the current page is 10 and there are 50 pages, the page range will be |
| 127 |
``[1, 2, '…', 7, 8, 9, 10, 11, 12, 13, '…', 49, 50]``. This will result in |
| 128 |
pages 7, 8, and 9 to the left of and 11, 12, and 13 to the right of the |
| 129 |
current page as well as pages 1 and 2 at the start and 49 and 50 at the |
| 130 |
end. |
| 131 |
|
| 132 |
Raises :exc:`InvalidPage` if the given page number doesn't exist. |
| 133 |
|
| 134 |
Attributes |
| 135 |
---------- |
| 136 |
|
| 137 |
.. attribute:: Paginator.ELLIPSIS |
| 138 |
|
| 139 |
A translatable string used as a substitute for elided page numbers in the |
| 140 |
page range returned by :meth:`~Paginator.get_elided_page_range`. Default is |
| 141 |
``'…'``. |
| 142 |
|
| 143 |
.. attribute:: Paginator.count |
| 144 |
|
| 145 |
The total number of objects, across all pages. |
| 146 |
|
| 147 |
.. note:: |
| 148 |
|
| 149 |
When determining the number of objects contained in ``object_list``, |
| 150 |
``Paginator`` will first try calling ``object_list.count()``. If |
| 151 |
``object_list`` has no ``count()`` method, then ``Paginator`` will |
| 152 |
fall back to using ``len(object_list)``. This allows objects, such as |
| 153 |
``QuerySet``, to use a more efficient ``count()`` method when |
| 154 |
available. |
| 155 |
|
| 156 |
.. attribute:: Paginator.num_pages |
| 157 |
|
| 158 |
The total number of pages. |
| 159 |
|
| 160 |
.. attribute:: Paginator.page_range |
| 161 |
|
| 162 |
A 1-based range iterator of page numbers, e.g. yielding ``[1, 2, 3, 4]``. |
| 163 |
|
| 164 |
``Page`` class |
| 165 |
============== |
| 166 |
|
| 167 |
You usually won't construct ``Page`` objects by hand -- you'll get them by |
| 168 |
iterating :class:`Paginator`, or by using :meth:`Paginator.page`. |
| 169 |
|
| 170 |
.. class:: Page(object_list, number, paginator) |
| 171 |
|
| 172 |
A page acts like a sequence of :attr:`Page.object_list` when using |
| 173 |
``len()`` or iterating it directly. |
| 174 |
|
| 175 |
Methods |
| 176 |
------- |
| 177 |
|
| 178 |
.. method:: Page.has_next() |
| 179 |
|
| 180 |
Returns ``True`` if there's a next page. |
| 181 |
|
| 182 |
.. method:: Page.has_previous() |
| 183 |
|
| 184 |
Returns ``True`` if there's a previous page. |
| 185 |
|
| 186 |
.. method:: Page.has_other_pages() |
| 187 |
|
| 188 |
Returns ``True`` if there's a next **or** previous page. |
| 189 |
|
| 190 |
.. method:: Page.next_page_number() |
| 191 |
|
| 192 |
Returns the next page number. Raises :exc:`InvalidPage` if next page |
| 193 |
doesn't exist. |
| 194 |
|
| 195 |
.. method:: Page.previous_page_number() |
| 196 |
|
| 197 |
Returns the previous page number. Raises :exc:`InvalidPage` if previous |
| 198 |
page doesn't exist. |
| 199 |
|
| 200 |
.. method:: Page.start_index() |
| 201 |
|
| 202 |
Returns the 1-based index of the first object on the page, relative to all |
| 203 |
of the objects in the paginator's list. For example, when paginating a list |
| 204 |
of 5 objects with 2 objects per page, the second page's |
| 205 |
:meth:`~Page.start_index` would return ``3``. |
| 206 |
|
| 207 |
.. method:: Page.end_index() |
| 208 |
|
| 209 |
Returns the 1-based index of the last object on the page, relative to all |
| 210 |
of the objects in the paginator's list. For example, when paginating a list |
| 211 |
of 5 objects with 2 objects per page, the second page's |
| 212 |
:meth:`~Page.end_index` would return ``4``. |
| 213 |
|
| 214 |
Attributes |
| 215 |
---------- |
| 216 |
|
| 217 |
.. attribute:: Page.object_list |
| 218 |
|
| 219 |
The list of objects on this page. |
| 220 |
|
| 221 |
.. attribute:: Page.number |
| 222 |
|
| 223 |
The 1-based page number for this page. |
| 224 |
|
| 225 |
.. attribute:: Page.paginator |
| 226 |
|
| 227 |
The associated :class:`Paginator` object. |
| 228 |
|
| 229 |
Exceptions |
| 230 |
========== |
| 231 |
|
| 232 |
.. exception:: InvalidPage |
| 233 |
|
| 234 |
A base class for exceptions raised when a paginator is passed an invalid |
| 235 |
page number. |
| 236 |
|
| 237 |
The :meth:`Paginator.page` method raises an exception if the requested page is |
| 238 |
invalid (i.e. not an integer) or contains no objects. Generally, it's enough |
| 239 |
to catch the ``InvalidPage`` exception, but if you'd like more granularity, |
| 240 |
you can catch either of the following exceptions: |
| 241 |
|
| 242 |
.. exception:: PageNotAnInteger |
| 243 |
|
| 244 |
Raised when :meth:`~Paginator.page` is given a value that isn't an integer. |
| 245 |
|
| 246 |
.. exception:: EmptyPage |
| 247 |
|
| 248 |
Raised when :meth:`~Paginator.page` is given a valid value but no objects |
| 249 |
exist on that page. |
| 250 |
|
| 251 |
Both of the exceptions are subclasses of :exc:`InvalidPage`, so you can handle |
| 252 |
them both with ``except InvalidPage``. |