p15693087
/
django
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Fixed #28581 -- Moved django.core.paginator documentation to API Reference. 

Co-Authored-By: Arman <armansabyrov@gmail.com>
This commit is contained in:
luto 2019-03-26 02:11:19 +06:00 committed by Mariusz Felisiak
parent 93b611c797
commit d37ea5f09b
3 changed files with 204 additions and 192 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/ref/index.txt
View File

@ -19,6 +19,7 @@ API Reference
middleware
migration-operations
models/index
paginator
request-response
schema-editor
settings

186
docs/ref/paginator.txt Normal file
View 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``.

209
docs/topics/pagination.txt
View File

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