mirror of
https://github.com/django/django.git
synced 2024-12-23 01:25:58 +00:00
Fixed #7781 -- Documented the per_page
argument/attribute for Paginator
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
This commit is contained in:
parent
2a7f7e1b97
commit
52b877eef0
@ -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:
|
||||
|
||||
``num_pages`` -- The total number of pages.
|
||||
``count``
|
||||
The total number of objects, across all pages.
|
||||
|
||||
``page_range`` -- A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.
|
||||
**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.
|
||||
|
||||
``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.
|
||||
|
Loading…
Reference in New Issue
Block a user