Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Fixed #7781 -- Documented the `per_page` argument/attribute for `Pagi…

…nator` objects. Also documented `Paginator`'s other arguments and made use of ReST definition lists. Thanks to hiukkanen for the

report.


git-svn-id: http://code.djangoproject.com/svn/django/trunk@8195 bcc190cf-cafb-0310-a4f2-bffc1f526a37
commit 52b877eef08f5c8e22765e2e0954c5a472ea71f3 1 parent 2a7f7e1
@gdub gdub authored
Showing with 80 additions and 34 deletions.
  1. +80 −34 docs/pagination.txt
View
114 docs/pagination.txt
@@ -59,30 +59,65 @@ page::
...
InvalidPage
-Note that you can give ``Paginator`` a list/tuple, a Django ``QuerySet``, or
-any other object with a ``count()`` or ``__len__()`` method. When determining
-the number of objects contained in the passed object, ``Paginator`` will first
-try calling ``count()``, then fallback to using ``len()`` if the passed object
-has no ``count()`` method. This allows objects such as Django's ``QuerySet`` to
-use a more efficient ``count()`` method when available.
-
``Paginator`` objects
=====================
+Required arguments
+------------------
+
+``object_list``
+ A list, tuple, Django ``QuerySet``, or other sliceable object with a
+ ``count()`` or ``__len__()`` method.
+
+``per_page``
+ The maximum number of items to include on a page, not including orphans
+ (see the ``orphans`` optional argument below).
+
+Optional arguments
+------------------
+
+``orphans``
+ The minimum number of items allowed on the last page, defaults to zero.
+ 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.
+
+``allow_empty_first_page``
+ Whether or not the first page is allowed to be empty. If ``False`` and
+ ``object_list`` is empty, then a ``EmptyPage`` error will be raised.
+
Methods
-------
-``page(number)`` -- Returns a ``Page`` object with the given 1-based index.
-Raises ``InvalidPage`` if the given page number doesn't exist.
+``page(number)``
+ Returns a ``Page`` object with the given 1-based index. Raises
+ ``InvalidPage`` if the given page number doesn't exist.
Attributes
----------
-``count`` -- The total number of objects, across all pages.
+In addition to the arguments above, which get stored as attributes, a
+``Paginator`` object also has the following attributes:
+
+``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 ``object_list.__len__()``. This allows
+ objects, such as Django's ``QuerySet``, to use a more efficient ``count()``
+ method when available.
-``num_pages`` -- The total number of pages.
+``num_pages``
+ The total number of pages.
-``page_range`` -- A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.
+``page_range``
+ A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.
``InvalidPage`` exceptions
==========================
@@ -92,9 +127,12 @@ The ``page()`` method raises ``InvalidPage`` if the requested page is invalid
the ``InvalidPage`` exception, but if you'd like more granularity, you can trap
either of the following exceptions:
-``PageNotAnInteger`` -- Raised when ``page()`` is given a value that isn't an integer.
+``PageNotAnInteger``
+ Raised when ``page()`` is given a value that isn't an integer.
-``EmptyPage`` -- Raised when ``page()`` is given a valid value but no objects exist on that page.
+``EmptyPage``
+ Raised when ``page()`` is given a valid value but no objects exist on that
+ page.
Both of the exceptions are subclasses of ``InvalidPage``, so you can handle
them both with a simple ``except InvalidPage``.
@@ -105,35 +143,43 @@ them both with a simple ``except InvalidPage``.
Methods
-------
-``has_next()`` -- Returns ``True`` if there's a next page.
+``has_next()``
+ Returns ``True`` if there's a next page.
-``has_previous()`` -- Returns ``True`` if there's a previous page.
+``has_previous()``
+ Returns ``True`` if there's a previous page.
-``has_other_pages()`` -- Returns ``True`` if there's a next *or* previous page.
+``has_other_pages()``
+ Returns ``True`` if there's a next *or* previous page.
-``next_page_number()`` -- Returns the next page number. Note that this is
-"dumb" and will return the next page number regardless of whether a subsequent
-page exists.
+``next_page_number()``
+ Returns the next page number. Note that this is "dumb" and will return the
+ next page number regardless of whether a subsequent page exists.
-``previous_page_number()`` -- Returns the previous page number. Note that this
-is "dumb" and will return the previous page number regardless of whether a
-previous page exists.
+``previous_page_number()``
+ Returns the previous page number. Note that this is "dumb" and will return
+ the previous page number regardless of whether a previous page exists.
-``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
-``start_index()`` would return ``3``.
+``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 ``start_index()``
+ would return ``3``.
-``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
-``end_index()`` would return ``4``.
+``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 ``end_index()``
+ would return ``4``.
Attributes
----------
-``object_list`` -- The list of objects on this page.
+``object_list``
+ The list of objects on this page.
-``number`` -- The 1-based page number for this page.
+``number``
+ The 1-based page number for this page.
-``paginator`` -- The associated ``Paginator`` object.
+``paginator``
+ The associated ``Paginator`` object.
Please sign in to comment.
Something went wrong with that request. Please try again.