Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Updated docs for dates generic views.

Fixes #18245. Refs #3542.
  • Loading branch information...
commit 7207327dd313522954da167f9a41396b97354c78 1 parent 3da43c1
Aymeric Augustin authored
3  django/views/generic/dates.py
@@ -372,6 +372,9 @@ def get_dated_queryset(self, ordering=None, **lookup):
372 372
         return qs
373 373
 
374 374
     def get_date_list_period(self):
  375
+        """
  376
+        Get the aggregation period for the list of dates: 'year', 'month', or 'day'.
  377
+        """
375 378
         return self.date_list_period
376 379
 
377 380
     def get_date_list(self, queryset, date_type=None):
128  docs/ref/class-based-views/generic-date-based.txt
@@ -2,13 +2,15 @@
2 2
 Generic date views
3 3
 ==================
4 4
 
5  
-Date-based generic views (in the module :mod:`django.views.generic.dates`)
6  
-are views for displaying drilldown pages for date-based data.
  5
+.. module:: django.views.generic.dates
  6
+
  7
+Date-based generic views, provided in :mod:`django.views.generic.dates`, are
  8
+views for displaying drilldown pages for date-based data.
7 9
 
8 10
 ArchiveIndexView
9 11
 ----------------
10 12
 
11  
-.. class:: django.views.generic.dates.ArchiveIndexView
  13
+.. class:: ArchiveIndexView
12 14
 
13 15
     A top-level index page showing the "latest" objects, by date. Objects with
14 16
     a date in the *future* are not included unless you set ``allow_future`` to
@@ -36,7 +38,7 @@ ArchiveIndexView
36 38
 YearArchiveView
37 39
 ---------------
38 40
 
39  
-.. class:: django.views.generic.dates.YearArchiveView
  41
+.. class:: YearArchiveView
40 42
 
41 43
     A yearly archive page showing all available months in a given year. Objects
42 44
     with a date in the *future* are not displayed unless you set
@@ -58,13 +60,15 @@ YearArchiveView
58 60
 
59 61
         A boolean specifying whether to retrieve the full list of objects for
60 62
         this year and pass those to the template. If ``True``, the list of
61  
-        objects will be made available to the context. By default, this is
  63
+        objects will be made available to the context. If ``False``, the
  64
+        ``None`` queryset will be used as the object list. By default, this is
62 65
         ``False``.
63 66
 
64 67
     .. method:: get_make_object_list()
65 68
 
66  
-        Determine if an object list will be returned as part of the context. If
67  
-        ``False``, the ``None`` queryset will be used as the object list.
  69
+        Determine if an object list will be returned as part of the context.
  70
+        Returns :attr:`~YearArchiveView.make_object_list` by default.
  71
+
68 72
 
69 73
     **Context**
70 74
 
@@ -80,16 +84,18 @@ YearArchiveView
80 84
       :class:`datetime.datetime<python:datetime.datetime>` objects, in
81 85
       ascending order.
82 86
 
83  
-    * ``year``: A :class:`datetime.date<python:datetime.date>` object
  87
+    * ``year``: A :class:`~datetime.date` object
84 88
       representing the given year.
85 89
 
86  
-    * ``next_year``: A :class:`datetime.date<python:datetime.date>` object
87  
-      representing the first day of the next year. If the next year is in the
88  
-      future, this will be ``None``.
  90
+    * ``next_year``: A :class:`~datetime.date` object
  91
+      representing the first day of the next year, according to
  92
+      :attr:`~BaseDateListView.allow_empty` and
  93
+      :attr:`~DateMixin.allow_future`.
89 94
 
90  
-    * ``previous_year``: A :class:`datetime.date<python:datetime.date>` object
91  
-      representing the first day of the previous year. Unlike ``next_year``,
92  
-      this will never be ``None``.
  95
+    * ``previous_year``: A :class:`~datetime.date` object
  96
+      representing the first day of the previous year, according to
  97
+      :attr:`~BaseDateListView.allow_empty` and
  98
+      :attr:`~DateMixin.allow_future`.
93 99
 
94 100
     **Notes**
95 101
 
@@ -98,7 +104,7 @@ YearArchiveView
98 104
 MonthArchiveView
99 105
 ----------------
100 106
 
101  
-.. class:: django.views.generic.dates.MonthArchiveView
  107
+.. class:: MonthArchiveView
102 108
 
103 109
     A monthly archive page showing all objects in a given month. Objects with a
104 110
     date in the *future* are not displayed unless you set ``allow_future`` to
@@ -131,16 +137,18 @@ MonthArchiveView
131 137
       :class:`datetime.datetime<python:datetime.datetime>` objects, in
132 138
       ascending order.
133 139
 
134  
-    * ``month``: A :class:`datetime.date<python:datetime.date>` object
  140
+    * ``month``: A :class:`~datetime.date` object
135 141
       representing the given month.
136 142
 
137  
-    * ``next_month``: A :class:`datetime.date<python:datetime.date>` object
138  
-      representing the first day of the next month. If the next month is in the
139  
-      future, this will be ``None``.
  143
+    * ``next_month``: A :class:`~datetime.date` object
  144
+      representing the first day of the next month, according to
  145
+      :attr:`~BaseDateListView.allow_empty` and
  146
+      :attr:`~DateMixin.allow_future`.
140 147
 
141  
-    * ``previous_month``: A :class:`datetime.date<python:datetime.date>` object
142  
-      representing the first day of the previous month. Unlike ``next_month``,
143  
-      this will never be ``None``.
  148
+    * ``previous_month``: A :class:`~datetime.date` object
  149
+      representing the first day of the previous month, according to
  150
+      :attr:`~BaseDateListView.allow_empty` and
  151
+      :attr:`~DateMixin.allow_future`.
144 152
 
145 153
     **Notes**
146 154
 
@@ -149,7 +157,7 @@ MonthArchiveView
149 157
 WeekArchiveView
150 158
 ---------------
151 159
 
152  
-.. class:: django.views.generic.dates.WeekArchiveView
  160
+.. class:: WeekArchiveView
153 161
 
154 162
     A weekly archive page showing all objects in a given week. Objects with a
155 163
     date in the *future* are not displayed unless you set ``allow_future`` to
@@ -175,16 +183,18 @@ WeekArchiveView
175 183
     :class:`~django.views.generic.dates.BaseDateListView`), the template's
176 184
     context will be:
177 185
 
178  
-    * ``week``: A :class:`datetime.date<python:datetime.date>` object
  186
+    * ``week``: A :class:`~datetime.date` object
179 187
       representing the first day of the given week.
180 188
 
181  
-    * ``next_week``: A :class:`datetime.date<python:datetime.date>` object
182  
-      representing the first day of the next week. If the next week is in the
183  
-      future, this will be ``None``.
  189
+    * ``next_week``: A :class:`~datetime.date` object
  190
+      representing the first day of the next week, according to
  191
+      :attr:`~BaseDateListView.allow_empty` and
  192
+      :attr:`~DateMixin.allow_future`.
184 193
 
185  
-    * ``previous_week``: A :class:`datetime.date<python:datetime.date>` object
186  
-      representing the first day of the previous week. Unlike ``next_week``,
187  
-      this will never be ``None``.
  194
+    * ``previous_week``: A :class:`~datetime.date` object
  195
+      representing the first day of the previous week, according to
  196
+      :attr:`~BaseDateListView.allow_empty` and
  197
+      :attr:`~DateMixin.allow_future`.
188 198
 
189 199
     **Notes**
190 200
 
@@ -193,7 +203,7 @@ WeekArchiveView
193 203
 DayArchiveView
194 204
 --------------
195 205
 
196  
-.. class:: django.views.generic.dates.DayArchiveView
  206
+.. class:: DayArchiveView
197 207
 
198 208
     A day archive page showing all objects in a given day. Days in the future
199 209
     throw a 404 error, regardless of whether any objects exist for future days,
@@ -220,24 +230,28 @@ DayArchiveView
220 230
     :class:`~django.views.generic.dates.BaseDateListView`), the template's
221 231
     context will be:
222 232
 
223  
-    * ``day``: A :class:`datetime.date<python:datetime.date>` object
  233
+    * ``day``: A :class:`~datetime.date` object
224 234
       representing the given day.
225 235
 
226  
-    * ``next_day``: A :class:`datetime.date<python:datetime.date>` object
227  
-      representing the next day. If the next day is in the future, this will be
228  
-      ``None``.
  236
+    * ``next_day``: A :class:`~datetime.date` object
  237
+      representing the next day, according to
  238
+      :attr:`~BaseDateListView.allow_empty` and
  239
+      :attr:`~DateMixin.allow_future`.
229 240
 
230  
-    * ``previous_day``: A :class:`datetime.date<python:datetime.date>` object
231  
-      representing the previous day. Unlike ``next_day``, this will never be
232  
-      ``None``.
  241
+    * ``previous_day``: A :class:`~datetime.date` object
  242
+      representing the previous day, according to
  243
+      :attr:`~BaseDateListView.allow_empty` and
  244
+      :attr:`~DateMixin.allow_future`.
233 245
 
234  
-    * ``next_month``: A :class:`datetime.date<python:datetime.date>` object
235  
-      representing the first day of the next month. If the next month is in the
236  
-      future, this will be ``None``.
  246
+    * ``next_month``: A :class:`~datetime.date` object
  247
+      representing the first day of the next month, according to
  248
+      :attr:`~BaseDateListView.allow_empty` and
  249
+      :attr:`~DateMixin.allow_future`.
237 250
 
238  
-    * ``previous_month``: A :class:`datetime.date<python:datetime.date>` object
239  
-      representing the first day of the previous month. Unlike ``next_month``,
240  
-      this will never be ``None``.
  251
+    * ``previous_month``: A :class:`~datetime.date` object
  252
+      representing the first day of the previous month, according to
  253
+      :attr:`~BaseDateListView.allow_empty` and
  254
+      :attr:`~DateMixin.allow_future`.
241 255
 
242 256
     **Notes**
243 257
 
@@ -246,7 +260,7 @@ DayArchiveView
246 260
 TodayArchiveView
247 261
 ----------------
248 262
 
249  
-.. class:: django.views.generic.dates.TodayArchiveView
  263
+.. class:: TodayArchiveView
250 264
 
251 265
     A day archive page showing all objects for *today*. This is exactly the
252 266
     same as :class:`django.views.generic.dates.DayArchiveView`, except today's
@@ -271,7 +285,7 @@ TodayArchiveView
271 285
 DateDetailView
272 286
 --------------
273 287
 
274  
-.. class:: django.views.generic.dates.DateDetailView
  288
+.. class:: DateDetailView
275 289
 
276 290
     A page representing an individual object. If the object has a date value in
277 291
     the future, the view will throw a 404 error by default, unless you set
@@ -293,6 +307,22 @@ DateDetailView
293 307
 
294 308
 .. note::
295 309
 
296  
-    All of the generic views listed above have matching Base* views that only
297  
-    differ in that the they do not include the
298  
-    :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`.
  310
+    All of the generic views listed above have matching ``Base`` views that
  311
+    only differ in that the they do not include the
  312
+    :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`:
  313
+
  314
+    .. class:: BaseArchiveIndexView
  315
+
  316
+    .. class:: BaseYearArchiveView
  317
+
  318
+    .. class:: BaseMonthArchiveView
  319
+
  320
+    .. class:: BaseWeekArchiveView
  321
+
  322
+    .. class:: BaseDayArchiveView
  323
+
  324
+    .. class:: BaseTodayArchiveView
  325
+
  326
+    .. class:: BaseDateDetailView
  327
+
  328
+
173  docs/ref/class-based-views/mixins-date-based.txt
@@ -2,11 +2,12 @@
2 2
 Date-based mixins
3 3
 =================
4 4
 
  5
+.. currentmodule:: django.views.generic.dates
5 6
 
6 7
 YearMixin
7 8
 ---------
8 9
 
9  
-.. class:: django.views.generic.dates.YearMixin
  10
+.. class:: YearMixin
10 11
 
11 12
     A mixin that can be used to retrieve and provide parsing information for a
12 13
     year component of a date.
@@ -20,29 +21,45 @@ YearMixin
20 21
 
21 22
     .. attribute:: year
22 23
 
23  
-        **Optional** The value for the year (as a string). By default, set to
  24
+        **Optional** The value for the year, as a string. By default, set to
24 25
         ``None``, which means the year will be determined using other means.
25 26
 
26 27
     .. method:: get_year_format()
27 28
 
28  
-        Returns the :func:`~time.strftime` format to use when parsing the year. Returns
29  
-        :attr:`YearMixin.year_format` by default.
  29
+        Returns the :func:`~time.strftime` format to use when parsing the
  30
+        year. Returns :attr:`~YearMixin.year_format` by default.
30 31
 
31 32
     .. method:: get_year()
32 33
 
33  
-        Returns the year for which this view will display data. Tries the
34  
-        following sources, in order:
  34
+        Returns the year for which this view will display data, as a string.
  35
+        Tries the following sources, in order:
35 36
 
36 37
         * The value of the :attr:`YearMixin.year` attribute.
37  
-        * The value of the `year` argument captured in the URL pattern
  38
+        * The value of the `year` argument captured in the URL pattern.
38 39
         * The value of the `year` GET query argument.
39 40
 
40 41
         Raises a 404 if no valid year specification can be found.
41 42
 
  43
+    .. method:: get_next_year(date)
  44
+
  45
+        Returns a date object containing the first day of the year after the
  46
+        date provided. This function can also return ``None`` or raise an
  47
+        :class:`~django.http.Http404` exception, depending on the values of
  48
+        :attr:`~BaseDateListView.allow_empty` and
  49
+        :attr:`~DateMixin.allow_future`.
  50
+
  51
+    .. method:: get_previous_year(date)
  52
+
  53
+        Returns a date object containing the first day of the year before the
  54
+        date provided. This function can also return ``None`` or raise an
  55
+        :class:`~django.http.Http404` exception, depending on the values of
  56
+        :attr:`~BaseDateListView.allow_empty` and
  57
+        :attr:`~DateMixin.allow_future`.
  58
+
42 59
 MonthMixin
43 60
 ----------
44 61
 
45  
-.. class:: django.views.generic.dates.MonthMixin
  62
+.. class:: MonthMixin
46 63
 
47 64
     A mixin that can be used to retrieve and provide parsing information for a
48 65
     month component of a date.
@@ -51,26 +68,26 @@ MonthMixin
51 68
 
52 69
     .. attribute:: month_format
53 70
 
54  
-        The :func:`~time.strftime` format to use when parsing the month. By default, this is
55  
-        ``'%b'``.
  71
+        The :func:`~time.strftime` format to use when parsing the month. By
  72
+        default, this is ``'%b'``.
56 73
 
57 74
     .. attribute:: month
58 75
 
59  
-        **Optional** The value for the month (as a string). By default, set to
  76
+        **Optional** The value for the month, as a string. By default, set to
60 77
         ``None``, which means the month will be determined using other means.
61 78
 
62 79
     .. method:: get_month_format()
63 80
 
64  
-        Returns the :func:`~time.strftime` format to use when parsing the month. Returns
65  
-        :attr:`MonthMixin.month_format` by default.
  81
+        Returns the :func:`~time.strftime` format to use when parsing the
  82
+        month. Returns :attr:`~MonthMixin.month_format` by default.
66 83
 
67 84
     .. method:: get_month()
68 85
 
69  
-        Returns the month for which this view will display data. Tries the
70  
-        following sources, in order:
  86
+        Returns the month for which this view will display data, as a string.
  87
+        Tries the following sources, in order:
71 88
 
72 89
         * The value of the :attr:`MonthMixin.month` attribute.
73  
-        * The value of the `month` argument captured in the URL pattern
  90
+        * The value of the `month` argument captured in the URL pattern.
74 91
         * The value of the `month` GET query argument.
75 92
 
76 93
         Raises a 404 if no valid month specification can be found.
@@ -78,20 +95,23 @@ MonthMixin
78 95
     .. method:: get_next_month(date)
79 96
 
80 97
         Returns a date object containing the first day of the month after the
81  
-        date provided. Returns ``None`` if mixed with a view that sets
82  
-        ``allow_future = False``, and the next month is in the future. If
83  
-        ``allow_empty = False``, returns the next month that contains data.
  98
+        date provided. This function can also return ``None`` or raise an
  99
+        :class:`~django.http.Http404` exception, depending on the values of
  100
+        :attr:`~BaseDateListView.allow_empty` and
  101
+        :attr:`~DateMixin.allow_future`.
84 102
 
85 103
     .. method:: get_prev_month(date)
86 104
 
87 105
         Returns a date object containing the first day of the month before the
88  
-        date provided. If ``allow_empty = False``, returns the previous month
89  
-        that contained data.
  106
+        date provided. This function can also return ``None`` or raise an
  107
+        :class:`~django.http.Http404` exception, depending on the values of
  108
+        :attr:`~BaseDateListView.allow_empty` and
  109
+        :attr:`~DateMixin.allow_future`.
90 110
 
91 111
 DayMixin
92 112
 --------
93 113
 
94  
-.. class:: django.views.generic.dates.DayMixin
  114
+.. class:: DayMixin
95 115
 
96 116
     A mixin that can be used to retrieve and provide parsing information for a
97 117
     day component of a date.
@@ -100,46 +120,50 @@ DayMixin
100 120
 
101 121
     .. attribute:: day_format
102 122
 
103  
-        The :func:`~time.strftime` format to use when parsing the day. By default, this is
104  
-        ``'%d'``.
  123
+        The :func:`~time.strftime` format to use when parsing the day. By
  124
+        default, this is ``'%d'``.
105 125
 
106 126
     .. attribute:: day
107 127
 
108  
-        **Optional** The value for the day (as a string). By default, set to
  128
+        **Optional** The value for the day, as a string. By default, set to
109 129
         ``None``, which means the day will be determined using other means.
110 130
 
111 131
     .. method:: get_day_format()
112 132
 
113  
-        Returns the :func:`~time.strftime` format to use when parsing the day. Returns
114  
-        :attr:`DayMixin.day_format` by default.
  133
+        Returns the :func:`~time.strftime` format to use when parsing the day.
  134
+        Returns :attr:`~DayMixin.day_format` by default.
115 135
 
116 136
     .. method:: get_day()
117 137
 
118  
-        Returns the day for which this view will display data. Tries the
119  
-        following sources, in order:
  138
+        Returns the day for which this view will display data, as a string.
  139
+        Tries the following sources, in order:
120 140
 
121 141
         * The value of the :attr:`DayMixin.day` attribute.
122  
-        * The value of the `day` argument captured in the URL pattern
  142
+        * The value of the `day` argument captured in the URL pattern.
123 143
         * The value of the `day` GET query argument.
124 144
 
125 145
         Raises a 404 if no valid day specification can be found.
126 146
 
127 147
     .. method:: get_next_day(date)
128 148
 
129  
-        Returns a date object containing the next day after the date provided.
130  
-        Returns ``None`` if mixed with a view that sets ``allow_future = False``,
131  
-        and the next day is in the future. If ``allow_empty = False``, returns
132  
-        the next day that contains data.
  149
+        Returns a date object containing the next valid day after the date
  150
+        provided. This function can also return ``None`` or raise an
  151
+        :class:`~django.http.Http404` exception, depending on the values of
  152
+        :attr:`~BaseDateListView.allow_empty` and
  153
+        :attr:`~DateMixin.allow_future`.
133 154
 
134 155
     .. method:: get_prev_day(date)
135 156
 
136  
-        Returns a date object containing the previous day. If
137  
-        ``allow_empty = False``, returns the previous day that contained data.
  157
+        Returns a date object containing the previous valid day. This function
  158
+        can also return ``None`` or raise an :class:`~django.http.Http404`
  159
+        exception, depending on the values of
  160
+        :attr:`~BaseDateListView.allow_empty` and
  161
+        :attr:`~DateMixin.allow_future`.
138 162
 
139 163
 WeekMixin
140 164
 ---------
141 165
 
142  
-.. class:: django.views.generic.dates.WeekMixin
  166
+.. class:: WeekMixin
143 167
 
144 168
     A mixin that can be used to retrieve and provide parsing information for a
145 169
     week component of a date.
@@ -148,23 +172,24 @@ WeekMixin
148 172
 
149 173
     .. attribute:: week_format
150 174
 
151  
-        The :func:`~time.strftime` format to use when parsing the week. By default, this is
152  
-        ``'%U'``.
  175
+        The :func:`~time.strftime` format to use when parsing the week. By
  176
+        default, this is ``'%U'``, which means the week starts on Sunday. Set
  177
+        it to ``'%W'`` if your week starts on Monday.
153 178
 
154 179
     .. attribute:: week
155 180
 
156  
-        **Optional** The value for the week (as a string). By default, set to
  181
+        **Optional** The value for the week, as a string. By default, set to
157 182
         ``None``, which means the week will be determined using other means.
158 183
 
159 184
     .. method:: get_week_format()
160 185
 
161  
-        Returns the :func:`~time.strftime` format to use when parsing the week. Returns
162  
-        :attr:`WeekMixin.week_format` by default.
  186
+        Returns the :func:`~time.strftime` format to use when parsing the
  187
+        week. Returns :attr:`~WeekMixin.week_format` by default.
163 188
 
164 189
     .. method:: get_week()
165 190
 
166  
-        Returns the week for which this view will display data. Tries the
167  
-        following sources, in order:
  191
+        Returns the week for which this view will display data, as a string.
  192
+        Tries the following sources, in order:
168 193
 
169 194
         * The value of the :attr:`WeekMixin.week` attribute.
170 195
         * The value of the `week` argument captured in the URL pattern
@@ -172,11 +197,26 @@ WeekMixin
172 197
 
173 198
         Raises a 404 if no valid week specification can be found.
174 199
 
  200
+    .. method:: get_next_week(date)
  201
+
  202
+        Returns a date object containing the first day of the week after the
  203
+        date provided. This function can also return ``None`` or raise an
  204
+        :class:`~django.http.Http404` exception, depending on the values of
  205
+        :attr:`~BaseDateListView.allow_empty` and
  206
+        :attr:`~DateMixin.allow_future`.
  207
+
  208
+    .. method:: get_prev_week(date)
  209
+
  210
+        Returns a date object containing the first day of the week before the
  211
+        date provided. This function can also return ``None`` or raise an
  212
+        :class:`~django.http.Http404` exception, depending on the values of
  213
+        :attr:`~BaseDateListView.allow_empty` and
  214
+        :attr:`~DateMixin.allow_future`.
175 215
 
176 216
 DateMixin
177 217
 ---------
178 218
 
179  
-.. class:: django.views.generic.dates.DateMixin
  219
+.. class:: DateMixin
180 220
 
181 221
     A mixin class providing common behavior for all date-based views.
182 222
 
@@ -186,7 +226,7 @@ DateMixin
186 226
 
187 227
         The name of the ``DateField`` or ``DateTimeField`` in the
188 228
         ``QuerySet``'s model that the date-based archive should use to
189  
-        determine the objects on the page.
  229
+        determine the list of objects to display on the page.
190 230
 
191 231
         When :doc:`time zone support </topics/i18n/timezones>` is enabled and
192 232
         ``date_field`` is a ``DateTimeField``, dates are assumed to be in the
@@ -210,26 +250,26 @@ DateMixin
210 250
     .. method:: get_date_field()
211 251
 
212 252
         Returns the name of the field that contains the date data that this
213  
-        view will operate on. Returns :attr:`DateMixin.date_field` by default.
  253
+        view will operate on. Returns :attr:`~DateMixin.date_field` by default.
214 254
 
215 255
     .. method:: get_allow_future()
216 256
 
217 257
         Determine whether to include "future" objects on this page, where
218 258
         "future" means objects in which the field specified in ``date_field``
219 259
         is greater than the current date/time. Returns
220  
-        :attr:`DateMixin.allow_future` by default.
  260
+        :attr:`~DateMixin.allow_future` by default.
221 261
 
222 262
 BaseDateListView
223 263
 ----------------
224 264
 
225  
-.. class:: django.views.generic.dates.BaseDateListView
  265
+.. class:: BaseDateListView
226 266
 
227 267
     A base class that provides common behavior for all date-based views. There
228 268
     won't normally be a reason to instantiate
229 269
     :class:`~django.views.generic.dates.BaseDateListView`; instantiate one of
230 270
     the subclasses instead.
231 271
 
232  
-    While this view (and it's subclasses) are executing, ``self.object_list``
  272
+    While this view (and its subclasses) are executing, ``self.object_list``
233 273
     will contain the list of objects that the view is operating upon, and
234 274
     ``self.date_list`` will contain the list of dates for which data is
235 275
     available.
@@ -245,10 +285,18 @@ BaseDateListView
245 285
 
246 286
         A boolean specifying whether to display the page if no objects are
247 287
         available. If this is ``True`` and no objects are available, the view
248  
-        will display an empty page instead of raising a 404. By default, this
249  
-        is ``False``.
  288
+        will display an empty page instead of raising a 404.
  289
+
  290
+        This is identical to :attr:`MultipleObjectMixin.allow_empty`, except
  291
+        for the default value, which is ``False``.
  292
+
  293
+    .. attribute:: date_list_period
250 294
 
251  
-    .. method:: get_dated_items():
  295
+        **Optional** A string defining the aggregation period for
  296
+        ``date_list``. It must be one of ``'year'`` (default), ``'month'``, or
  297
+        ``'day'``.
  298
+
  299
+    .. method:: get_dated_items()
252 300
 
253 301
         Returns a 3-tuple containing (``date_list``, ``object_list``,
254 302
         ``extra_context``).
@@ -265,10 +313,17 @@ BaseDateListView
265 313
         ``lookup``. Enforces any restrictions on the queryset, such as
266 314
         ``allow_empty`` and ``allow_future``.
267 315
 
268  
-    .. method:: get_date_list(queryset, date_type)
  316
+    .. method:: get_date_list_period()
  317
+
  318
+        Returns the aggregation period for ``date_list``. Returns
  319
+        :attr:`~BaseDateListView.date_list_period` by default.
  320
+
  321
+    .. method:: get_date_list(queryset, date_type=None)
269 322
 
270  
-        Returns the list of dates of type ``date_type`` for which
271  
-        ``queryset`` contains entries. For example, ``get_date_list(qs,
272  
-        'year')`` will return the list of years for which ``qs`` has entries.
273  
-        See :meth:`~django.db.models.query.QuerySet.dates()` for the
274  
-        ways that the ``date_type`` argument can be used.
  323
+        Returns the list of dates of type ``date_type`` for which ``queryset``
  324
+        contains entries. For example, ``get_date_list(qs, 'year')`` will
  325
+        return the list of years for which ``qs`` has entries. If
  326
+        ``date_type`` isn't provided, the result of
  327
+        :meth:`BaseDateListView.get_date_list_period` is used. See
  328
+        :meth:`~django.db.models.query.QuerySet.dates()` for the ways that the
  329
+        ``date_type`` argument can be used.

0 notes on commit 7207327

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