Loading django/views/generic/dates.py +3 −0 Original line number Diff line number Diff line Loading @@ -372,6 +372,9 @@ class BaseDateListView(MultipleObjectMixin, DateMixin, View): return qs def get_date_list_period(self): """ Get the aggregation period for the list of dates: 'year', 'month', or 'day'. """ return self.date_list_period def get_date_list(self, queryset, date_type=None): Loading docs/ref/class-based-views/generic-date-based.txt +79 −49 Original line number Diff line number Diff line Loading @@ -2,13 +2,15 @@ Generic date views ================== Date-based generic views (in the module :mod:`django.views.generic.dates`) are views for displaying drilldown pages for date-based data. .. module:: django.views.generic.dates Date-based generic views, provided in :mod:`django.views.generic.dates`, are views for displaying drilldown pages for date-based data. ArchiveIndexView ---------------- .. class:: django.views.generic.dates.ArchiveIndexView .. class:: ArchiveIndexView A top-level index page showing the "latest" objects, by date. Objects with a date in the *future* are not included unless you set ``allow_future`` to Loading Loading @@ -36,7 +38,7 @@ ArchiveIndexView YearArchiveView --------------- .. class:: django.views.generic.dates.YearArchiveView .. class:: YearArchiveView A yearly archive page showing all available months in a given year. Objects with a date in the *future* are not displayed unless you set Loading @@ -58,13 +60,15 @@ YearArchiveView A boolean specifying whether to retrieve the full list of objects for this year and pass those to the template. If ``True``, the list of objects will be made available to the context. By default, this is objects will be made available to the context. If ``False``, the ``None`` queryset will be used as the object list. By default, this is ``False``. .. method:: get_make_object_list() Determine if an object list will be returned as part of the context. If ``False``, the ``None`` queryset will be used as the object list. Determine if an object list will be returned as part of the context. Returns :attr:`~YearArchiveView.make_object_list` by default. **Context** Loading @@ -80,16 +84,18 @@ YearArchiveView :class:`datetime.datetime<python:datetime.datetime>` objects, in ascending order. * ``year``: A :class:`datetime.date<python:datetime.date>` object * ``year``: A :class:`~datetime.date` object representing the given year. * ``next_year``: A :class:`datetime.date<python:datetime.date>` object representing the first day of the next year. If the next year is in the future, this will be ``None``. * ``next_year``: A :class:`~datetime.date` object representing the first day of the next year, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. * ``previous_year``: A :class:`datetime.date<python:datetime.date>` object representing the first day of the previous year. Unlike ``next_year``, this will never be ``None``. * ``previous_year``: A :class:`~datetime.date` object representing the first day of the previous year, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. **Notes** Loading @@ -98,7 +104,7 @@ YearArchiveView MonthArchiveView ---------------- .. class:: django.views.generic.dates.MonthArchiveView .. class:: MonthArchiveView A monthly archive page showing all objects in a given month. Objects with a date in the *future* are not displayed unless you set ``allow_future`` to Loading Loading @@ -131,16 +137,18 @@ MonthArchiveView :class:`datetime.datetime<python:datetime.datetime>` objects, in ascending order. * ``month``: A :class:`datetime.date<python:datetime.date>` object * ``month``: A :class:`~datetime.date` object representing the given month. * ``next_month``: A :class:`datetime.date<python:datetime.date>` object representing the first day of the next month. If the next month is in the future, this will be ``None``. * ``next_month``: A :class:`~datetime.date` object representing the first day of the next month, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. * ``previous_month``: A :class:`datetime.date<python:datetime.date>` object representing the first day of the previous month. Unlike ``next_month``, this will never be ``None``. * ``previous_month``: A :class:`~datetime.date` object representing the first day of the previous month, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. **Notes** Loading @@ -149,7 +157,7 @@ MonthArchiveView WeekArchiveView --------------- .. class:: django.views.generic.dates.WeekArchiveView .. class:: WeekArchiveView A weekly archive page showing all objects in a given week. Objects with a date in the *future* are not displayed unless you set ``allow_future`` to Loading @@ -175,16 +183,18 @@ WeekArchiveView :class:`~django.views.generic.dates.BaseDateListView`), the template's context will be: * ``week``: A :class:`datetime.date<python:datetime.date>` object * ``week``: A :class:`~datetime.date` object representing the first day of the given week. * ``next_week``: A :class:`datetime.date<python:datetime.date>` object representing the first day of the next week. If the next week is in the future, this will be ``None``. * ``next_week``: A :class:`~datetime.date` object representing the first day of the next week, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. * ``previous_week``: A :class:`datetime.date<python:datetime.date>` object representing the first day of the previous week. Unlike ``next_week``, this will never be ``None``. * ``previous_week``: A :class:`~datetime.date` object representing the first day of the previous week, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. **Notes** Loading @@ -193,7 +203,7 @@ WeekArchiveView DayArchiveView -------------- .. class:: django.views.generic.dates.DayArchiveView .. class:: DayArchiveView A day archive page showing all objects in a given day. Days in the future throw a 404 error, regardless of whether any objects exist for future days, Loading @@ -220,24 +230,28 @@ DayArchiveView :class:`~django.views.generic.dates.BaseDateListView`), the template's context will be: * ``day``: A :class:`datetime.date<python:datetime.date>` object * ``day``: A :class:`~datetime.date` object representing the given day. * ``next_day``: A :class:`datetime.date<python:datetime.date>` object representing the next day. If the next day is in the future, this will be ``None``. * ``next_day``: A :class:`~datetime.date` object representing the next day, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. * ``previous_day``: A :class:`datetime.date<python:datetime.date>` object representing the previous day. Unlike ``next_day``, this will never be ``None``. * ``previous_day``: A :class:`~datetime.date` object representing the previous day, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. * ``next_month``: A :class:`datetime.date<python:datetime.date>` object representing the first day of the next month. If the next month is in the future, this will be ``None``. * ``next_month``: A :class:`~datetime.date` object representing the first day of the next month, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. * ``previous_month``: A :class:`datetime.date<python:datetime.date>` object representing the first day of the previous month. Unlike ``next_month``, this will never be ``None``. * ``previous_month``: A :class:`~datetime.date` object representing the first day of the previous month, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. **Notes** Loading @@ -246,7 +260,7 @@ DayArchiveView TodayArchiveView ---------------- .. class:: django.views.generic.dates.TodayArchiveView .. class:: TodayArchiveView A day archive page showing all objects for *today*. This is exactly the same as :class:`django.views.generic.dates.DayArchiveView`, except today's Loading @@ -271,7 +285,7 @@ TodayArchiveView DateDetailView -------------- .. class:: django.views.generic.dates.DateDetailView .. class:: DateDetailView A page representing an individual object. If the object has a date value in the future, the view will throw a 404 error by default, unless you set Loading @@ -293,6 +307,22 @@ DateDetailView .. note:: All of the generic views listed above have matching Base* views that only differ in that the they do not include the :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`. All of the generic views listed above have matching ``Base`` views that only differ in that the they do not include the :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`: .. class:: BaseArchiveIndexView .. class:: BaseYearArchiveView .. class:: BaseMonthArchiveView .. class:: BaseWeekArchiveView .. class:: BaseDayArchiveView .. class:: BaseTodayArchiveView .. class:: BaseDateDetailView docs/ref/class-based-views/mixins-date-based.txt +114 −59 Original line number Diff line number Diff line Loading @@ -2,11 +2,12 @@ Date-based mixins ================= .. currentmodule:: django.views.generic.dates YearMixin --------- .. class:: django.views.generic.dates.YearMixin .. class:: YearMixin A mixin that can be used to retrieve and provide parsing information for a year component of a date. Loading @@ -20,29 +21,45 @@ YearMixin .. attribute:: year **Optional** The value for the year (as a string). By default, set to **Optional** The value for the year, as a string. By default, set to ``None``, which means the year will be determined using other means. .. method:: get_year_format() Returns the :func:`~time.strftime` format to use when parsing the year. Returns :attr:`YearMixin.year_format` by default. Returns the :func:`~time.strftime` format to use when parsing the year. Returns :attr:`~YearMixin.year_format` by default. .. method:: get_year() Returns the year for which this view will display data. Tries the following sources, in order: Returns the year for which this view will display data, as a string. Tries the following sources, in order: * The value of the :attr:`YearMixin.year` attribute. * The value of the `year` argument captured in the URL pattern * The value of the `year` argument captured in the URL pattern. * The value of the `year` GET query argument. Raises a 404 if no valid year specification can be found. .. method:: get_next_year(date) Returns a date object containing the first day of the year after the date provided. This function can also return ``None`` or raise an :class:`~django.http.Http404` exception, depending on the values of :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. .. method:: get_previous_year(date) Returns a date object containing the first day of the year before the date provided. This function can also return ``None`` or raise an :class:`~django.http.Http404` exception, depending on the values of :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. MonthMixin ---------- .. class:: django.views.generic.dates.MonthMixin .. class:: MonthMixin A mixin that can be used to retrieve and provide parsing information for a month component of a date. Loading @@ -51,26 +68,26 @@ MonthMixin .. attribute:: month_format The :func:`~time.strftime` format to use when parsing the month. By default, this is ``'%b'``. The :func:`~time.strftime` format to use when parsing the month. By default, this is ``'%b'``. .. attribute:: month **Optional** The value for the month (as a string). By default, set to **Optional** The value for the month, as a string. By default, set to ``None``, which means the month will be determined using other means. .. method:: get_month_format() Returns the :func:`~time.strftime` format to use when parsing the month. Returns :attr:`MonthMixin.month_format` by default. Returns the :func:`~time.strftime` format to use when parsing the month. Returns :attr:`~MonthMixin.month_format` by default. .. method:: get_month() Returns the month for which this view will display data. Tries the following sources, in order: Returns the month for which this view will display data, as a string. Tries the following sources, in order: * The value of the :attr:`MonthMixin.month` attribute. * The value of the `month` argument captured in the URL pattern * The value of the `month` argument captured in the URL pattern. * The value of the `month` GET query argument. Raises a 404 if no valid month specification can be found. Loading @@ -78,20 +95,23 @@ MonthMixin .. method:: get_next_month(date) Returns a date object containing the first day of the month after the date provided. Returns ``None`` if mixed with a view that sets ``allow_future = False``, and the next month is in the future. If ``allow_empty = False``, returns the next month that contains data. date provided. This function can also return ``None`` or raise an :class:`~django.http.Http404` exception, depending on the values of :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. .. method:: get_prev_month(date) Returns a date object containing the first day of the month before the date provided. If ``allow_empty = False``, returns the previous month that contained data. date provided. This function can also return ``None`` or raise an :class:`~django.http.Http404` exception, depending on the values of :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. DayMixin -------- .. class:: django.views.generic.dates.DayMixin .. class:: DayMixin A mixin that can be used to retrieve and provide parsing information for a day component of a date. Loading @@ -100,46 +120,50 @@ DayMixin .. attribute:: day_format The :func:`~time.strftime` format to use when parsing the day. By default, this is ``'%d'``. The :func:`~time.strftime` format to use when parsing the day. By default, this is ``'%d'``. .. attribute:: day **Optional** The value for the day (as a string). By default, set to **Optional** The value for the day, as a string. By default, set to ``None``, which means the day will be determined using other means. .. method:: get_day_format() Returns the :func:`~time.strftime` format to use when parsing the day. Returns :attr:`DayMixin.day_format` by default. Returns the :func:`~time.strftime` format to use when parsing the day. Returns :attr:`~DayMixin.day_format` by default. .. method:: get_day() Returns the day for which this view will display data. Tries the following sources, in order: Returns the day for which this view will display data, as a string. Tries the following sources, in order: * The value of the :attr:`DayMixin.day` attribute. * The value of the `day` argument captured in the URL pattern * The value of the `day` argument captured in the URL pattern. * The value of the `day` GET query argument. Raises a 404 if no valid day specification can be found. .. method:: get_next_day(date) Returns a date object containing the next day after the date provided. Returns ``None`` if mixed with a view that sets ``allow_future = False``, and the next day is in the future. If ``allow_empty = False``, returns the next day that contains data. Returns a date object containing the next valid day after the date provided. This function can also return ``None`` or raise an :class:`~django.http.Http404` exception, depending on the values of :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. .. method:: get_prev_day(date) Returns a date object containing the previous day. If ``allow_empty = False``, returns the previous day that contained data. Returns a date object containing the previous valid day. This function can also return ``None`` or raise an :class:`~django.http.Http404` exception, depending on the values of :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. WeekMixin --------- .. class:: django.views.generic.dates.WeekMixin .. class:: WeekMixin A mixin that can be used to retrieve and provide parsing information for a week component of a date. Loading @@ -148,23 +172,24 @@ WeekMixin .. attribute:: week_format The :func:`~time.strftime` format to use when parsing the week. By default, this is ``'%U'``. The :func:`~time.strftime` format to use when parsing the week. By default, this is ``'%U'``, which means the week starts on Sunday. Set it to ``'%W'`` if your week starts on Monday. .. attribute:: week **Optional** The value for the week (as a string). By default, set to **Optional** The value for the week, as a string. By default, set to ``None``, which means the week will be determined using other means. .. method:: get_week_format() Returns the :func:`~time.strftime` format to use when parsing the week. Returns :attr:`WeekMixin.week_format` by default. Returns the :func:`~time.strftime` format to use when parsing the week. Returns :attr:`~WeekMixin.week_format` by default. .. method:: get_week() Returns the week for which this view will display data. Tries the following sources, in order: Returns the week for which this view will display data, as a string. Tries the following sources, in order: * The value of the :attr:`WeekMixin.week` attribute. * The value of the `week` argument captured in the URL pattern Loading @@ -172,11 +197,26 @@ WeekMixin Raises a 404 if no valid week specification can be found. .. method:: get_next_week(date) Returns a date object containing the first day of the week after the date provided. This function can also return ``None`` or raise an :class:`~django.http.Http404` exception, depending on the values of :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. .. method:: get_prev_week(date) Returns a date object containing the first day of the week before the date provided. This function can also return ``None`` or raise an :class:`~django.http.Http404` exception, depending on the values of :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. DateMixin --------- .. class:: django.views.generic.dates.DateMixin .. class:: DateMixin A mixin class providing common behavior for all date-based views. Loading @@ -186,7 +226,7 @@ DateMixin The name of the ``DateField`` or ``DateTimeField`` in the ``QuerySet``'s model that the date-based archive should use to determine the objects on the page. determine the list of objects to display on the page. When :doc:`time zone support </topics/i18n/timezones>` is enabled and ``date_field`` is a ``DateTimeField``, dates are assumed to be in the Loading @@ -210,26 +250,26 @@ DateMixin .. method:: get_date_field() Returns the name of the field that contains the date data that this view will operate on. Returns :attr:`DateMixin.date_field` by default. view will operate on. Returns :attr:`~DateMixin.date_field` by default. .. method:: get_allow_future() Determine whether to include "future" objects on this page, where "future" means objects in which the field specified in ``date_field`` is greater than the current date/time. Returns :attr:`DateMixin.allow_future` by default. :attr:`~DateMixin.allow_future` by default. BaseDateListView ---------------- .. class:: django.views.generic.dates.BaseDateListView .. class:: BaseDateListView A base class that provides common behavior for all date-based views. There won't normally be a reason to instantiate :class:`~django.views.generic.dates.BaseDateListView`; instantiate one of the subclasses instead. While this view (and it's subclasses) are executing, ``self.object_list`` While this view (and its subclasses) are executing, ``self.object_list`` will contain the list of objects that the view is operating upon, and ``self.date_list`` will contain the list of dates for which data is available. Loading @@ -245,10 +285,18 @@ BaseDateListView A boolean specifying whether to display the page if no objects are available. If this is ``True`` and no objects are available, the view will display an empty page instead of raising a 404. By default, this is ``False``. will display an empty page instead of raising a 404. This is identical to :attr:`MultipleObjectMixin.allow_empty`, except for the default value, which is ``False``. .. attribute:: date_list_period .. method:: get_dated_items(): **Optional** A string defining the aggregation period for ``date_list``. It must be one of ``'year'`` (default), ``'month'``, or ``'day'``. .. method:: get_dated_items() Returns a 3-tuple containing (``date_list``, ``object_list``, ``extra_context``). Loading @@ -265,10 +313,17 @@ BaseDateListView ``lookup``. Enforces any restrictions on the queryset, such as ``allow_empty`` and ``allow_future``. .. method:: get_date_list(queryset, date_type) .. method:: get_date_list_period() Returns the aggregation period for ``date_list``. Returns :attr:`~BaseDateListView.date_list_period` by default. .. method:: get_date_list(queryset, date_type=None) Returns the list of dates of type ``date_type`` for which ``queryset`` contains entries. For example, ``get_date_list(qs, 'year')`` will return the list of years for which ``qs`` has entries. See :meth:`~django.db.models.query.QuerySet.dates()` for the ways that the ``date_type`` argument can be used. Returns the list of dates of type ``date_type`` for which ``queryset`` contains entries. For example, ``get_date_list(qs, 'year')`` will return the list of years for which ``qs`` has entries. If ``date_type`` isn't provided, the result of :meth:`BaseDateListView.get_date_list_period` is used. See :meth:`~django.db.models.query.QuerySet.dates()` for the ways that the ``date_type`` argument can be used. Loading
django/views/generic/dates.py +3 −0 Original line number Diff line number Diff line Loading @@ -372,6 +372,9 @@ class BaseDateListView(MultipleObjectMixin, DateMixin, View): return qs def get_date_list_period(self): """ Get the aggregation period for the list of dates: 'year', 'month', or 'day'. """ return self.date_list_period def get_date_list(self, queryset, date_type=None): Loading
docs/ref/class-based-views/generic-date-based.txt +79 −49 Original line number Diff line number Diff line Loading @@ -2,13 +2,15 @@ Generic date views ================== Date-based generic views (in the module :mod:`django.views.generic.dates`) are views for displaying drilldown pages for date-based data. .. module:: django.views.generic.dates Date-based generic views, provided in :mod:`django.views.generic.dates`, are views for displaying drilldown pages for date-based data. ArchiveIndexView ---------------- .. class:: django.views.generic.dates.ArchiveIndexView .. class:: ArchiveIndexView A top-level index page showing the "latest" objects, by date. Objects with a date in the *future* are not included unless you set ``allow_future`` to Loading Loading @@ -36,7 +38,7 @@ ArchiveIndexView YearArchiveView --------------- .. class:: django.views.generic.dates.YearArchiveView .. class:: YearArchiveView A yearly archive page showing all available months in a given year. Objects with a date in the *future* are not displayed unless you set Loading @@ -58,13 +60,15 @@ YearArchiveView A boolean specifying whether to retrieve the full list of objects for this year and pass those to the template. If ``True``, the list of objects will be made available to the context. By default, this is objects will be made available to the context. If ``False``, the ``None`` queryset will be used as the object list. By default, this is ``False``. .. method:: get_make_object_list() Determine if an object list will be returned as part of the context. If ``False``, the ``None`` queryset will be used as the object list. Determine if an object list will be returned as part of the context. Returns :attr:`~YearArchiveView.make_object_list` by default. **Context** Loading @@ -80,16 +84,18 @@ YearArchiveView :class:`datetime.datetime<python:datetime.datetime>` objects, in ascending order. * ``year``: A :class:`datetime.date<python:datetime.date>` object * ``year``: A :class:`~datetime.date` object representing the given year. * ``next_year``: A :class:`datetime.date<python:datetime.date>` object representing the first day of the next year. If the next year is in the future, this will be ``None``. * ``next_year``: A :class:`~datetime.date` object representing the first day of the next year, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. * ``previous_year``: A :class:`datetime.date<python:datetime.date>` object representing the first day of the previous year. Unlike ``next_year``, this will never be ``None``. * ``previous_year``: A :class:`~datetime.date` object representing the first day of the previous year, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. **Notes** Loading @@ -98,7 +104,7 @@ YearArchiveView MonthArchiveView ---------------- .. class:: django.views.generic.dates.MonthArchiveView .. class:: MonthArchiveView A monthly archive page showing all objects in a given month. Objects with a date in the *future* are not displayed unless you set ``allow_future`` to Loading Loading @@ -131,16 +137,18 @@ MonthArchiveView :class:`datetime.datetime<python:datetime.datetime>` objects, in ascending order. * ``month``: A :class:`datetime.date<python:datetime.date>` object * ``month``: A :class:`~datetime.date` object representing the given month. * ``next_month``: A :class:`datetime.date<python:datetime.date>` object representing the first day of the next month. If the next month is in the future, this will be ``None``. * ``next_month``: A :class:`~datetime.date` object representing the first day of the next month, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. * ``previous_month``: A :class:`datetime.date<python:datetime.date>` object representing the first day of the previous month. Unlike ``next_month``, this will never be ``None``. * ``previous_month``: A :class:`~datetime.date` object representing the first day of the previous month, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. **Notes** Loading @@ -149,7 +157,7 @@ MonthArchiveView WeekArchiveView --------------- .. class:: django.views.generic.dates.WeekArchiveView .. class:: WeekArchiveView A weekly archive page showing all objects in a given week. Objects with a date in the *future* are not displayed unless you set ``allow_future`` to Loading @@ -175,16 +183,18 @@ WeekArchiveView :class:`~django.views.generic.dates.BaseDateListView`), the template's context will be: * ``week``: A :class:`datetime.date<python:datetime.date>` object * ``week``: A :class:`~datetime.date` object representing the first day of the given week. * ``next_week``: A :class:`datetime.date<python:datetime.date>` object representing the first day of the next week. If the next week is in the future, this will be ``None``. * ``next_week``: A :class:`~datetime.date` object representing the first day of the next week, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. * ``previous_week``: A :class:`datetime.date<python:datetime.date>` object representing the first day of the previous week. Unlike ``next_week``, this will never be ``None``. * ``previous_week``: A :class:`~datetime.date` object representing the first day of the previous week, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. **Notes** Loading @@ -193,7 +203,7 @@ WeekArchiveView DayArchiveView -------------- .. class:: django.views.generic.dates.DayArchiveView .. class:: DayArchiveView A day archive page showing all objects in a given day. Days in the future throw a 404 error, regardless of whether any objects exist for future days, Loading @@ -220,24 +230,28 @@ DayArchiveView :class:`~django.views.generic.dates.BaseDateListView`), the template's context will be: * ``day``: A :class:`datetime.date<python:datetime.date>` object * ``day``: A :class:`~datetime.date` object representing the given day. * ``next_day``: A :class:`datetime.date<python:datetime.date>` object representing the next day. If the next day is in the future, this will be ``None``. * ``next_day``: A :class:`~datetime.date` object representing the next day, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. * ``previous_day``: A :class:`datetime.date<python:datetime.date>` object representing the previous day. Unlike ``next_day``, this will never be ``None``. * ``previous_day``: A :class:`~datetime.date` object representing the previous day, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. * ``next_month``: A :class:`datetime.date<python:datetime.date>` object representing the first day of the next month. If the next month is in the future, this will be ``None``. * ``next_month``: A :class:`~datetime.date` object representing the first day of the next month, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. * ``previous_month``: A :class:`datetime.date<python:datetime.date>` object representing the first day of the previous month. Unlike ``next_month``, this will never be ``None``. * ``previous_month``: A :class:`~datetime.date` object representing the first day of the previous month, according to :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. **Notes** Loading @@ -246,7 +260,7 @@ DayArchiveView TodayArchiveView ---------------- .. class:: django.views.generic.dates.TodayArchiveView .. class:: TodayArchiveView A day archive page showing all objects for *today*. This is exactly the same as :class:`django.views.generic.dates.DayArchiveView`, except today's Loading @@ -271,7 +285,7 @@ TodayArchiveView DateDetailView -------------- .. class:: django.views.generic.dates.DateDetailView .. class:: DateDetailView A page representing an individual object. If the object has a date value in the future, the view will throw a 404 error by default, unless you set Loading @@ -293,6 +307,22 @@ DateDetailView .. note:: All of the generic views listed above have matching Base* views that only differ in that the they do not include the :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`. All of the generic views listed above have matching ``Base`` views that only differ in that the they do not include the :class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`: .. class:: BaseArchiveIndexView .. class:: BaseYearArchiveView .. class:: BaseMonthArchiveView .. class:: BaseWeekArchiveView .. class:: BaseDayArchiveView .. class:: BaseTodayArchiveView .. class:: BaseDateDetailView
docs/ref/class-based-views/mixins-date-based.txt +114 −59 Original line number Diff line number Diff line Loading @@ -2,11 +2,12 @@ Date-based mixins ================= .. currentmodule:: django.views.generic.dates YearMixin --------- .. class:: django.views.generic.dates.YearMixin .. class:: YearMixin A mixin that can be used to retrieve and provide parsing information for a year component of a date. Loading @@ -20,29 +21,45 @@ YearMixin .. attribute:: year **Optional** The value for the year (as a string). By default, set to **Optional** The value for the year, as a string. By default, set to ``None``, which means the year will be determined using other means. .. method:: get_year_format() Returns the :func:`~time.strftime` format to use when parsing the year. Returns :attr:`YearMixin.year_format` by default. Returns the :func:`~time.strftime` format to use when parsing the year. Returns :attr:`~YearMixin.year_format` by default. .. method:: get_year() Returns the year for which this view will display data. Tries the following sources, in order: Returns the year for which this view will display data, as a string. Tries the following sources, in order: * The value of the :attr:`YearMixin.year` attribute. * The value of the `year` argument captured in the URL pattern * The value of the `year` argument captured in the URL pattern. * The value of the `year` GET query argument. Raises a 404 if no valid year specification can be found. .. method:: get_next_year(date) Returns a date object containing the first day of the year after the date provided. This function can also return ``None`` or raise an :class:`~django.http.Http404` exception, depending on the values of :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. .. method:: get_previous_year(date) Returns a date object containing the first day of the year before the date provided. This function can also return ``None`` or raise an :class:`~django.http.Http404` exception, depending on the values of :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. MonthMixin ---------- .. class:: django.views.generic.dates.MonthMixin .. class:: MonthMixin A mixin that can be used to retrieve and provide parsing information for a month component of a date. Loading @@ -51,26 +68,26 @@ MonthMixin .. attribute:: month_format The :func:`~time.strftime` format to use when parsing the month. By default, this is ``'%b'``. The :func:`~time.strftime` format to use when parsing the month. By default, this is ``'%b'``. .. attribute:: month **Optional** The value for the month (as a string). By default, set to **Optional** The value for the month, as a string. By default, set to ``None``, which means the month will be determined using other means. .. method:: get_month_format() Returns the :func:`~time.strftime` format to use when parsing the month. Returns :attr:`MonthMixin.month_format` by default. Returns the :func:`~time.strftime` format to use when parsing the month. Returns :attr:`~MonthMixin.month_format` by default. .. method:: get_month() Returns the month for which this view will display data. Tries the following sources, in order: Returns the month for which this view will display data, as a string. Tries the following sources, in order: * The value of the :attr:`MonthMixin.month` attribute. * The value of the `month` argument captured in the URL pattern * The value of the `month` argument captured in the URL pattern. * The value of the `month` GET query argument. Raises a 404 if no valid month specification can be found. Loading @@ -78,20 +95,23 @@ MonthMixin .. method:: get_next_month(date) Returns a date object containing the first day of the month after the date provided. Returns ``None`` if mixed with a view that sets ``allow_future = False``, and the next month is in the future. If ``allow_empty = False``, returns the next month that contains data. date provided. This function can also return ``None`` or raise an :class:`~django.http.Http404` exception, depending on the values of :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. .. method:: get_prev_month(date) Returns a date object containing the first day of the month before the date provided. If ``allow_empty = False``, returns the previous month that contained data. date provided. This function can also return ``None`` or raise an :class:`~django.http.Http404` exception, depending on the values of :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. DayMixin -------- .. class:: django.views.generic.dates.DayMixin .. class:: DayMixin A mixin that can be used to retrieve and provide parsing information for a day component of a date. Loading @@ -100,46 +120,50 @@ DayMixin .. attribute:: day_format The :func:`~time.strftime` format to use when parsing the day. By default, this is ``'%d'``. The :func:`~time.strftime` format to use when parsing the day. By default, this is ``'%d'``. .. attribute:: day **Optional** The value for the day (as a string). By default, set to **Optional** The value for the day, as a string. By default, set to ``None``, which means the day will be determined using other means. .. method:: get_day_format() Returns the :func:`~time.strftime` format to use when parsing the day. Returns :attr:`DayMixin.day_format` by default. Returns the :func:`~time.strftime` format to use when parsing the day. Returns :attr:`~DayMixin.day_format` by default. .. method:: get_day() Returns the day for which this view will display data. Tries the following sources, in order: Returns the day for which this view will display data, as a string. Tries the following sources, in order: * The value of the :attr:`DayMixin.day` attribute. * The value of the `day` argument captured in the URL pattern * The value of the `day` argument captured in the URL pattern. * The value of the `day` GET query argument. Raises a 404 if no valid day specification can be found. .. method:: get_next_day(date) Returns a date object containing the next day after the date provided. Returns ``None`` if mixed with a view that sets ``allow_future = False``, and the next day is in the future. If ``allow_empty = False``, returns the next day that contains data. Returns a date object containing the next valid day after the date provided. This function can also return ``None`` or raise an :class:`~django.http.Http404` exception, depending on the values of :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. .. method:: get_prev_day(date) Returns a date object containing the previous day. If ``allow_empty = False``, returns the previous day that contained data. Returns a date object containing the previous valid day. This function can also return ``None`` or raise an :class:`~django.http.Http404` exception, depending on the values of :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. WeekMixin --------- .. class:: django.views.generic.dates.WeekMixin .. class:: WeekMixin A mixin that can be used to retrieve and provide parsing information for a week component of a date. Loading @@ -148,23 +172,24 @@ WeekMixin .. attribute:: week_format The :func:`~time.strftime` format to use when parsing the week. By default, this is ``'%U'``. The :func:`~time.strftime` format to use when parsing the week. By default, this is ``'%U'``, which means the week starts on Sunday. Set it to ``'%W'`` if your week starts on Monday. .. attribute:: week **Optional** The value for the week (as a string). By default, set to **Optional** The value for the week, as a string. By default, set to ``None``, which means the week will be determined using other means. .. method:: get_week_format() Returns the :func:`~time.strftime` format to use when parsing the week. Returns :attr:`WeekMixin.week_format` by default. Returns the :func:`~time.strftime` format to use when parsing the week. Returns :attr:`~WeekMixin.week_format` by default. .. method:: get_week() Returns the week for which this view will display data. Tries the following sources, in order: Returns the week for which this view will display data, as a string. Tries the following sources, in order: * The value of the :attr:`WeekMixin.week` attribute. * The value of the `week` argument captured in the URL pattern Loading @@ -172,11 +197,26 @@ WeekMixin Raises a 404 if no valid week specification can be found. .. method:: get_next_week(date) Returns a date object containing the first day of the week after the date provided. This function can also return ``None`` or raise an :class:`~django.http.Http404` exception, depending on the values of :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. .. method:: get_prev_week(date) Returns a date object containing the first day of the week before the date provided. This function can also return ``None`` or raise an :class:`~django.http.Http404` exception, depending on the values of :attr:`~BaseDateListView.allow_empty` and :attr:`~DateMixin.allow_future`. DateMixin --------- .. class:: django.views.generic.dates.DateMixin .. class:: DateMixin A mixin class providing common behavior for all date-based views. Loading @@ -186,7 +226,7 @@ DateMixin The name of the ``DateField`` or ``DateTimeField`` in the ``QuerySet``'s model that the date-based archive should use to determine the objects on the page. determine the list of objects to display on the page. When :doc:`time zone support </topics/i18n/timezones>` is enabled and ``date_field`` is a ``DateTimeField``, dates are assumed to be in the Loading @@ -210,26 +250,26 @@ DateMixin .. method:: get_date_field() Returns the name of the field that contains the date data that this view will operate on. Returns :attr:`DateMixin.date_field` by default. view will operate on. Returns :attr:`~DateMixin.date_field` by default. .. method:: get_allow_future() Determine whether to include "future" objects on this page, where "future" means objects in which the field specified in ``date_field`` is greater than the current date/time. Returns :attr:`DateMixin.allow_future` by default. :attr:`~DateMixin.allow_future` by default. BaseDateListView ---------------- .. class:: django.views.generic.dates.BaseDateListView .. class:: BaseDateListView A base class that provides common behavior for all date-based views. There won't normally be a reason to instantiate :class:`~django.views.generic.dates.BaseDateListView`; instantiate one of the subclasses instead. While this view (and it's subclasses) are executing, ``self.object_list`` While this view (and its subclasses) are executing, ``self.object_list`` will contain the list of objects that the view is operating upon, and ``self.date_list`` will contain the list of dates for which data is available. Loading @@ -245,10 +285,18 @@ BaseDateListView A boolean specifying whether to display the page if no objects are available. If this is ``True`` and no objects are available, the view will display an empty page instead of raising a 404. By default, this is ``False``. will display an empty page instead of raising a 404. This is identical to :attr:`MultipleObjectMixin.allow_empty`, except for the default value, which is ``False``. .. attribute:: date_list_period .. method:: get_dated_items(): **Optional** A string defining the aggregation period for ``date_list``. It must be one of ``'year'`` (default), ``'month'``, or ``'day'``. .. method:: get_dated_items() Returns a 3-tuple containing (``date_list``, ``object_list``, ``extra_context``). Loading @@ -265,10 +313,17 @@ BaseDateListView ``lookup``. Enforces any restrictions on the queryset, such as ``allow_empty`` and ``allow_future``. .. method:: get_date_list(queryset, date_type) .. method:: get_date_list_period() Returns the aggregation period for ``date_list``. Returns :attr:`~BaseDateListView.date_list_period` by default. .. method:: get_date_list(queryset, date_type=None) Returns the list of dates of type ``date_type`` for which ``queryset`` contains entries. For example, ``get_date_list(qs, 'year')`` will return the list of years for which ``qs`` has entries. See :meth:`~django.db.models.query.QuerySet.dates()` for the ways that the ``date_type`` argument can be used. Returns the list of dates of type ``date_type`` for which ``queryset`` contains entries. For example, ``get_date_list(qs, 'year')`` will return the list of years for which ``qs`` has entries. If ``date_type`` isn't provided, the result of :meth:`BaseDateListView.get_date_list_period` is used. See :meth:`~django.db.models.query.QuerySet.dates()` for the ways that the ``date_type`` argument can be used.
