Debian Codegraph @

docs/ref/class-based-views/mixins-date-based.txt

raw
1 =================
2 Date-based mixins
3 =================
4
5 .. currentmodule:: django.views.generic.dates
6
7 .. note::
8
9 All the date formatting attributes in these mixins use
10 :func:`~time.strftime` format characters. Do not try to use the format
11 characters from the :ttag:`now` template tag as they are not compatible.
12
13 ``YearMixin``
14 =============
15
16 .. class:: YearMixin
17
18 A mixin that can be used to retrieve and provide parsing information for a
19 year component of a date.
20
21 **Methods and Attributes**
22
23 .. attribute:: year_format
24
25 The :func:`~time.strftime` format to use when parsing the year.
26 By default, this is ``'%Y'``.
27
28 .. attribute:: year
29
30 **Optional** The value for the year, as a string. By default, set to
31 ``None``, which means the year will be determined using other means.
32
33 .. method:: get_year_format()
34
35 Returns the :func:`~time.strftime` format to use when parsing the
36 year. Returns :attr:`~YearMixin.year_format` by default.
37
38 .. method:: get_year()
39
40 Returns the year for which this view will display data, as a string.
41 Tries the following sources, in order:
42
43 * The value of the :attr:`YearMixin.year` attribute.
44 * The value of the ``year`` argument captured in the URL pattern.
45 * The value of the ``year`` ``GET`` query argument.
46
47 Raises a 404 if no valid year specification can be found.
48
49 .. method:: get_next_year(date)
50
51 Returns a date object containing the first day of the year after the
52 date provided. This function can also return ``None`` or raise an
53 :class:`~django.http.Http404` exception, depending on the values of
54 :attr:`~BaseDateListView.allow_empty` and
55 :attr:`~DateMixin.allow_future`.
56
57 .. method:: get_previous_year(date)
58
59 Returns a date object containing the first day of the year before the
60 date provided. This function can also return ``None`` or raise an
61 :class:`~django.http.Http404` exception, depending on the values of
62 :attr:`~BaseDateListView.allow_empty` and
63 :attr:`~DateMixin.allow_future`.
64
65 ``MonthMixin``
66 ==============
67
68 .. class:: MonthMixin
69
70 A mixin that can be used to retrieve and provide parsing information for a
71 month component of a date.
72
73 **Methods and Attributes**
74
75 .. attribute:: month_format
76
77 The :func:`~time.strftime` format to use when parsing the month. By
78 default, this is ``'%b'``.
79
80 .. attribute:: month
81
82 **Optional** The value for the month, as a string. By default, set to
83 ``None``, which means the month will be determined using other means.
84
85 .. method:: get_month_format()
86
87 Returns the :func:`~time.strftime` format to use when parsing the
88 month. Returns :attr:`~MonthMixin.month_format` by default.
89
90 .. method:: get_month()
91
92 Returns the month for which this view will display data, as a string.
93 Tries the following sources, in order:
94
95 * The value of the :attr:`MonthMixin.month` attribute.
96 * The value of the ``month`` argument captured in the URL pattern.
97 * The value of the ``month`` ``GET`` query argument.
98
99 Raises a 404 if no valid month specification can be found.
100
101 .. method:: get_next_month(date)
102
103 Returns a date object containing the first day of the month after the
104 date provided. This function can also return ``None`` or raise an
105 :class:`~django.http.Http404` exception, depending on the values of
106 :attr:`~BaseDateListView.allow_empty` and
107 :attr:`~DateMixin.allow_future`.
108
109 .. method:: get_previous_month(date)
110
111 Returns a date object containing the first day of the month before the
112 date provided. This function can also return ``None`` or raise an
113 :class:`~django.http.Http404` exception, depending on the values of
114 :attr:`~BaseDateListView.allow_empty` and
115 :attr:`~DateMixin.allow_future`.
116
117 ``DayMixin``
118 ============
119
120 .. class:: DayMixin
121
122 A mixin that can be used to retrieve and provide parsing information for a
123 day component of a date.
124
125 **Methods and Attributes**
126
127 .. attribute:: day_format
128
129 The :func:`~time.strftime` format to use when parsing the day. By
130 default, this is ``'%d'``.
131
132 .. attribute:: day
133
134 **Optional** The value for the day, as a string. By default, set to
135 ``None``, which means the day will be determined using other means.
136
137 .. method:: get_day_format()
138
139 Returns the :func:`~time.strftime` format to use when parsing the day.
140 Returns :attr:`~DayMixin.day_format` by default.
141
142 .. method:: get_day()
143
144 Returns the day for which this view will display data, as a string.
145 Tries the following sources, in order:
146
147 * The value of the :attr:`DayMixin.day` attribute.
148 * The value of the ``day`` argument captured in the URL pattern.
149 * The value of the ``day`` ``GET`` query argument.
150
151 Raises a 404 if no valid day specification can be found.
152
153 .. method:: get_next_day(date)
154
155 Returns a date object containing the next valid day after the date
156 provided. This function can also return ``None`` or raise an
157 :class:`~django.http.Http404` exception, depending on the values of
158 :attr:`~BaseDateListView.allow_empty` and
159 :attr:`~DateMixin.allow_future`.
160
161 .. method:: get_previous_day(date)
162
163 Returns a date object containing the previous valid day. This function
164 can also return ``None`` or raise an :class:`~django.http.Http404`
165 exception, depending on the values of
166 :attr:`~BaseDateListView.allow_empty` and
167 :attr:`~DateMixin.allow_future`.
168
169 ``WeekMixin``
170 =============
171
172 .. class:: WeekMixin
173
174 A mixin that can be used to retrieve and provide parsing information for a
175 week component of a date.
176
177 **Methods and Attributes**
178
179 .. attribute:: week_format
180
181 The :func:`~time.strftime` format to use when parsing the week. By
182 default, this is ``'%U'``, which means the week starts on Sunday. Set
183 it to ``'%W'`` or ``'%V'`` (ISO 8601 week) if your week starts on
184 Monday.
185
186 .. attribute:: week
187
188 **Optional** The value for the week, as a string. By default, set to
189 ``None``, which means the week will be determined using other means.
190
191 .. method:: get_week_format()
192
193 Returns the :func:`~time.strftime` format to use when parsing the
194 week. Returns :attr:`~WeekMixin.week_format` by default.
195
196 .. method:: get_week()
197
198 Returns the week for which this view will display data, as a string.
199 Tries the following sources, in order:
200
201 * The value of the :attr:`WeekMixin.week` attribute.
202 * The value of the ``week`` argument captured in the URL pattern
203 * The value of the ``week`` ``GET`` query argument.
204
205 Raises a 404 if no valid week specification can be found.
206
207 .. method:: get_next_week(date)
208
209 Returns a date object containing the first day of the week after the
210 date provided. This function can also return ``None`` or raise an
211 :class:`~django.http.Http404` exception, depending on the values of
212 :attr:`~BaseDateListView.allow_empty` and
213 :attr:`~DateMixin.allow_future`.
214
215 .. method:: get_prev_week(date)
216
217 Returns a date object containing the first day of the week before the
218 date provided. This function can also return ``None`` or raise an
219 :class:`~django.http.Http404` exception, depending on the values of
220 :attr:`~BaseDateListView.allow_empty` and
221 :attr:`~DateMixin.allow_future`.
222
223 ``DateMixin``
224 =============
225
226 .. class:: DateMixin
227
228 A mixin class providing common behavior for all date-based views.
229
230 **Methods and Attributes**
231
232 .. attribute:: date_field
233
234 The name of the ``DateField`` or ``DateTimeField`` in the
235 ``QuerySet``’s model that the date-based archive should use to
236 determine the list of objects to display on the page.
237
238 When :doc:`time zone support </topics/i18n/timezones>` is enabled and
239 ``date_field`` is a ``DateTimeField``, dates are assumed to be in the
240 current time zone. Otherwise, the queryset could include objects from
241 the previous or the next day in the end user's time zone.
242
243 .. warning::
244
245 In this situation, if you have implemented per-user time zone
246 selection, the same URL may show a different set of objects,
247 depending on the end user's time zone. To avoid this, you should
248 use a ``DateField`` as the ``date_field`` attribute.
249
250 .. attribute:: allow_future
251
252 A boolean specifying whether to include "future" objects on this page,
253 where "future" means objects in which the field specified in
254 ``date_field`` is greater than the current date/time. By default, this
255 is ``False``.
256
257 .. method:: get_date_field()
258
259 Returns the name of the field that contains the date data that this
260 view will operate on. Returns :attr:`~DateMixin.date_field` by default.
261
262 .. method:: get_allow_future()
263
264 Determine whether to include "future" objects on this page, where
265 "future" means objects in which the field specified in ``date_field``
266 is greater than the current date/time. Returns
267 :attr:`~DateMixin.allow_future` by default.
268
269 ``BaseDateListView``
270 ====================
271
272 .. class:: BaseDateListView
273
274 A base class that provides common behavior for all date-based views. There
275 won't normally be a reason to instantiate
276 :class:`~django.views.generic.dates.BaseDateListView`; instantiate one of
277 the subclasses instead.
278
279 While this view (and its subclasses) are executing, ``self.object_list``
280 will contain the list of objects that the view is operating upon, and
281 ``self.date_list`` will contain the list of dates for which data is
282 available.
283
284 **Mixins**
285
286 * :class:`~django.views.generic.dates.DateMixin`
287 * :class:`~django.views.generic.list.MultipleObjectMixin`
288
289 **Methods and Attributes**
290
291 .. attribute:: allow_empty
292
293 A boolean specifying whether to display the page if no objects are
294 available. If this is ``True`` and no objects are available, the view
295 will display an empty page instead of raising a 404.
296
297 This is identical to
298 :attr:`django.views.generic.list.MultipleObjectMixin.allow_empty`,
299 except for the default value, which is ``False``.
300
301 .. attribute:: date_list_period
302
303 **Optional** A string defining the aggregation period for
304 ``date_list``. It must be one of ``'year'`` (default), ``'month'``, or
305 ``'day'``.
306
307 .. method:: get_dated_items()
308
309 Returns a 3-tuple containing (``date_list``, ``object_list``,
310 ``extra_context``).
311
312 ``date_list`` is the list of dates for which data is available.
313 ``object_list`` is the list of objects. ``extra_context`` is a
314 dictionary of context data that will be added to any context data
315 provided by the
316 :class:`~django.views.generic.list.MultipleObjectMixin`.
317
318 .. method:: get_dated_queryset(**lookup)
319
320 Returns a queryset, filtered using the query arguments defined by
321 ``lookup``. Enforces any restrictions on the queryset, such as
322 ``allow_empty`` and ``allow_future``.
323
324 .. method:: get_date_list_period()
325
326 Returns the aggregation period for ``date_list``. Returns
327 :attr:`~BaseDateListView.date_list_period` by default.
328
329 .. method:: get_date_list(queryset, date_type=None, ordering='ASC')
330
331 Returns the list of dates of type ``date_type`` for which ``queryset``
332 contains entries. For example, ``get_date_list(qs, 'year')`` will
333 return the list of years for which ``qs`` has entries. If
334 ``date_type`` isn't provided, the result of
335 :meth:`~BaseDateListView.get_date_list_period` is used. ``date_type``
336 and ``ordering`` are passed to
337 :meth:`QuerySet.dates()<django.db.models.query.QuerySet.dates>`.