Fixed #7781 -- Documented the `per_page` argument/attribute for `Paginator`... (52b877ee) · Commits · Dom Sekotill / django

docs/pagination.txt

+80 −34

Original line number	Diff line number	Diff line
		@@ -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.