diff --git a/docs/ref/index.txt b/docs/ref/index.txt index b81d8dd7d4..1a10e2b42c 100644 --- a/docs/ref/index.txt +++ b/docs/ref/index.txt @@ -19,6 +19,7 @@ API Reference middleware migration-operations models/index + paginator request-response schema-editor settings diff --git a/docs/ref/paginator.txt b/docs/ref/paginator.txt new file mode 100644 index 0000000000..9ee6f0104c --- /dev/null +++ b/docs/ref/paginator.txt @@ -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``. diff --git a/docs/topics/pagination.txt b/docs/topics/pagination.txt index a22cd9eb95..80e6932a6b 100644 --- a/docs/topics/pagination.txt +++ b/docs/topics/pagination.txt @@ -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 %} - -``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.