Debian Codegraph @

docs/ref/paginator.txt

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