Updated docs for dates generic views.

Fixes #18245. Refs #3542.

django/views/generic/dates.py

@@ -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):

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

@@ -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
@@ -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
@@ -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**
 
@@ -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**
 
@@ -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
@@ -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**
 
@@ -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
@@ -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**
 
@@ -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,
@@ -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**
 
@@ -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
@@ -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
@@ -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

@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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
@@ -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.
 
@@ -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
@@ -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.
@@ -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``).
@@ -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.