Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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
  • Loading branch information...
commit 52b877eef08f5c8e22765e2e0954c5a472ea71f3 1 parent 2a7f7e1
Gary Wilson Jr. authored August 03, 2008

Showing 1 changed file with 80 additions and 34 deletions. Show diff stats Hide diff stats

  1. 114  docs/pagination.txt
114  docs/pagination.txt
@@ -59,30 +59,65 @@ page::
59 59
     ...
60 60
     InvalidPage
61 61
 
62  
-Note that you can give ``Paginator`` a list/tuple, a Django ``QuerySet``, or
63  
-any other object with a ``count()`` or ``__len__()`` method. When determining
64  
-the number of objects contained in the passed object, ``Paginator`` will first
65  
-try calling ``count()``, then fallback to using ``len()`` if the passed object
66  
-has no ``count()`` method. This allows objects such as Django's ``QuerySet`` to
67  
-use a more efficient ``count()`` method when available.
68  
-
69 62
 ``Paginator`` objects
70 63
 =====================
71 64
 
  65
+Required arguments
  66
+------------------
  67
+
  68
+``object_list``
  69
+    A list, tuple, Django ``QuerySet``, or other sliceable object with a
  70
+    ``count()`` or ``__len__()`` method.
  71
+
  72
+``per_page``
  73
+    The maximum number of items to include on a page, not including orphans
  74
+    (see the ``orphans`` optional argument below).
  75
+
  76
+Optional arguments
  77
+------------------
  78
+
  79
+``orphans``
  80
+    The minimum number of items allowed on the last page, defaults to zero.
  81
+    Use this when you don't want to have a last page with very few items.
  82
+    If the last page would normally have a number of items less than or equal
  83
+    to ``orphans``, then those items will be added to the previous page (which
  84
+    becomes the last page) instead of leaving the items on a page by
  85
+    themselves. For example, with 23 items, ``per_page=10``, and
  86
+    ``orphans=3``, there will be two pages; the first page with 10 items and
  87
+    the  second (and last) page with 13 items.
  88
+
  89
+``allow_empty_first_page``
  90
+    Whether or not the first page is allowed to be empty.  If ``False`` and
  91
+    ``object_list`` is  empty, then a ``EmptyPage`` error will be raised.
  92
+
72 93
 Methods
73 94
 -------
74 95
 
75  
-``page(number)`` -- Returns a ``Page`` object with the given 1-based index.
76  
-Raises ``InvalidPage`` if the given page number doesn't exist.
  96
+``page(number)``
  97
+    Returns a ``Page`` object with the given 1-based index. Raises
  98
+    ``InvalidPage`` if the given page number doesn't exist.
77 99
 
78 100
 Attributes
79 101
 ----------
80 102
 
81  
-``count`` -- The total number of objects, across all pages.
  103
+In addition to the arguments above, which get stored as attributes, a
  104
+``Paginator`` object also has the following attributes:
  105
+
  106
+``count``
  107
+    The total number of objects, across all pages.
  108
+
  109
+    **Note**: When determining the number of objects contained in
  110
+    ``object_list``, ``Paginator`` will first try calling
  111
+    ``object_list.count()``. If ``object_list`` has no ``count()`` method, then
  112
+    ``Paginator`` will fallback to using ``object_list.__len__()``. This allows
  113
+    objects, such as Django's ``QuerySet``, to use a more efficient ``count()``
  114
+    method when available.
82 115
 
83  
-``num_pages`` -- The total number of pages.
  116
+``num_pages``
  117
+    The total number of pages.
84 118
 
85  
-``page_range`` -- A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.
  119
+``page_range``
  120
+    A 1-based range of page numbers, e.g., ``[1, 2, 3, 4]``.
86 121
 
87 122
 ``InvalidPage`` exceptions
88 123
 ==========================
@@ -92,9 +127,12 @@ The ``page()`` method raises ``InvalidPage`` if the requested page is invalid
92 127
 the ``InvalidPage`` exception, but if you'd like more granularity, you can trap
93 128
 either of the following exceptions:
94 129
 
95  
-``PageNotAnInteger`` -- Raised when ``page()`` is given a value that isn't an integer.
  130
+``PageNotAnInteger``
  131
+    Raised when ``page()`` is given a value that isn't an integer.
96 132
 
97  
-``EmptyPage`` -- Raised when ``page()`` is given a valid value but no objects exist on that page.
  133
+``EmptyPage``
  134
+    Raised when ``page()`` is given a valid value but no objects exist on that
  135
+    page.
98 136
 
99 137
 Both of the exceptions are subclasses of ``InvalidPage``, so you can handle
100 138
 them both with a simple ``except InvalidPage``.
@@ -105,35 +143,43 @@ them both with a simple ``except InvalidPage``.
105 143
 Methods
106 144
 -------
107 145
 
108  
-``has_next()`` -- Returns ``True`` if there's a next page.
  146
+``has_next()``
  147
+    Returns ``True`` if there's a next page.
109 148
 
110  
-``has_previous()`` -- Returns ``True`` if there's a previous page.
  149
+``has_previous()``
  150
+    Returns ``True`` if there's a previous page.
111 151
 
112  
-``has_other_pages()`` -- Returns ``True`` if there's a next *or* previous page.
  152
+``has_other_pages()``
  153
+    Returns ``True`` if there's a next *or* previous page.
113 154
 
114  
-``next_page_number()`` -- Returns the next page number. Note that this is
115  
-"dumb" and will return the next page number regardless of whether a subsequent
116  
-page exists.
  155
+``next_page_number()``
  156
+    Returns the next page number. Note that this is "dumb" and will return the
  157
+    next page number regardless of whether a subsequent page exists.
117 158
 
118  
-``previous_page_number()`` -- Returns the previous page number. Note that this
119  
-is "dumb" and will return the previous page number regardless of whether a
120  
-previous page exists.
  159
+``previous_page_number()``
  160
+    Returns the previous page number. Note that this is "dumb" and will return
  161
+    the previous page number regardless of whether a previous page exists.
121 162
 
122  
-``start_index()`` -- Returns the 1-based index of the first object on the page,
123  
-relative to all of the objects in the paginator's list. For example, when
124  
-paginating a list of 5 objects with 2 objects per page, the second page's
125  
-``start_index()`` would return ``3``.
  163
+``start_index()``
  164
+    Returns the 1-based index of the first object on the page, relative to all
  165
+    of the objects in the paginator's list. For example, when paginating a list
  166
+    of 5 objects with 2 objects per page, the second page's ``start_index()``
  167
+    would return ``3``.
126 168
 
127  
-``end_index()`` -- Returns the 1-based index of the last object on the page,
128  
-relative to all of the objects in the paginator's list. For example, when
129  
-paginating a list of 5 objects with 2 objects per page, the second page's
130  
-``end_index()`` would return ``4``.
  169
+``end_index()``
  170
+    Returns the 1-based index of the last object on the page, relative to all
  171
+    of the objects in the paginator's list. For example, when paginating a list
  172
+    of 5 objects with 2 objects per page, the second page's ``end_index()``
  173
+    would return ``4``.
131 174
 
132 175
 Attributes
133 176
 ----------
134 177
 
135  
-``object_list`` -- The list of objects on this page.
  178
+``object_list``
  179
+    The list of objects on this page.
136 180
 
137  
-``number`` -- The 1-based page number for this page.
  181
+``number``
  182
+    The 1-based page number for this page.
138 183
 
139  
-``paginator`` -- The associated ``Paginator`` object.
  184
+``paginator``
  185
+    The associated ``Paginator`` object.

0 notes on commit 52b877e

Please sign in to comment.
Something went wrong with that request. Please try again.