mirror of
https://github.com/django/django.git
synced 2024-12-22 17:16:24 +00:00
Fixed #28581 -- Moved django.core.paginator documentation to API Reference.
Co-Authored-By: Arman <armansabyrov@gmail.com>
This commit is contained in:
parent
93b611c797
commit
d37ea5f09b
@ -19,6 +19,7 @@ API Reference
|
||||
middleware
|
||||
migration-operations
|
||||
models/index
|
||||
paginator
|
||||
request-response
|
||||
schema-editor
|
||||
settings
|
||||
|
186
docs/ref/paginator.txt
Normal file
186
docs/ref/paginator.txt
Normal file
@ -0,0 +1,186 @@
|
||||
=========
|
||||
Paginator
|
||||
=========
|
||||
|
||||
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 :source:`django/core/paginator.py`.
|
||||
|
||||
.. module:: django.core.paginator
|
||||
:synopsis: Classes to help you easily manage paginated data.
|
||||
|
||||
``Paginator`` class
|
||||
===================
|
||||
|
||||
.. class:: Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True)
|
||||
|
||||
.. attribute:: Paginator.object_list
|
||||
|
||||
Required. 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.
|
||||
|
||||
.. attribute:: Paginator.per_page
|
||||
|
||||
Required. The maximum number of items to include on a page, not including
|
||||
orphans (see the :attr:`~Paginator.orphans` optional argument below).
|
||||
|
||||
.. attribute:: Paginator.orphans
|
||||
|
||||
Optional. 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.
|
||||
|
||||
.. attribute:: Paginator.allow_empty_first_page
|
||||
|
||||
Optional. 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.
|
||||
|
||||
Raises an :exc:`EmptyPage` exception 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
|
||||
fall back to using ``len(object_list)``. This allows objects, such as
|
||||
``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]``.
|
||||
|
||||
``Page`` class
|
||||
==============
|
||||
|
||||
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.
|
||||
|
||||
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 :meth:`~Paginator.page` is given a value that isn't an integer.
|
||||
|
||||
.. exception:: EmptyPage
|
||||
|
||||
Raised when :meth:`~Paginator.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 ``except InvalidPage``.
|
@ -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.
|
||||
|
Loading…
Reference in New Issue
Block a user