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

=================
Date-based mixins
=================


YearMixin
---------

.. class:: django.views.generic.dates.YearMixin

    A mixin that can be used to retrieve and provide parsing information for a
    year component of a date.

    **Methods and Attributes**

    .. attribute:: year_format

        The :func:`~time.strftime` format to use when parsing the year.
        By default, this is ``'%Y'``.

    .. attribute:: year

        **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.

    .. method:: get_year()

        Returns the year for which this view will display data. 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` GET query argument.

        Raises a 404 if no valid year specification can be found.

MonthMixin
----------

.. class:: django.views.generic.dates.MonthMixin

    A mixin that can be used to retrieve and provide parsing information for a
    month component of a date.

    **Methods and Attributes**

    .. attribute:: month_format

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

    .. method:: get_month()

        Returns the month for which this view will display data. 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` GET query argument.

        Raises a 404 if no valid month specification can be found.

    .. 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.

    .. 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.

DayMixin
--------

.. class:: django.views.generic.dates.DayMixin

    A mixin that can be used to retrieve and provide parsing information for a
    day component of a date.

    **Methods and Attributes**

    .. attribute:: day_format

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

    .. method:: get_day()

        Returns the day for which this view will display data. 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` 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.

    .. method:: get_prev_day(date)

        Returns a date object containing the previous day. If
        ``allow_empty = False``, returns the previous day that contained data.

WeekMixin
---------

.. class:: django.views.generic.dates.WeekMixin

    A mixin that can be used to retrieve and provide parsing information for a
    week component of a date.

    **Methods and Attributes**

    .. attribute:: week_format

        The :func:`~time.strftime` format to use when parsing the week. By default, this is
        ``'%U'``.

    .. attribute:: week

        **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.

    .. method:: get_week()

        Returns the week for which this view will display data. 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
        * The value of the `week` GET query argument.

        Raises a 404 if no valid week specification can be found.


DateMixin
---------

.. class:: django.views.generic.dates.DateMixin

    A mixin class providing common behavior for all date-based views.

    **Methods and Attributes**

    .. attribute:: date_field

        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.

        When :doc:`time zone support </topics/i18n/timezones>` is enabled and
        ``date_field`` is a ``DateTimeField``, dates are assumed to be in the
        current time zone. Otherwise, the queryset could include objects from
        the previous or the next day in the end user's time zone.

        .. warning::

            In this situation, if you have implemented per-user time zone
            selection, the same URL may show a different set of objects,
            depending on the end user's time zone. To avoid this, you should
            use a ``DateField`` as the ``date_field`` attribute.

    .. attribute:: allow_future

        A boolean specifying 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. By default, this
        is ``False``.

    .. 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.

    .. 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.

BaseDateListView
----------------

.. class:: django.views.generic.dates.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``
    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.

    **Mixins**

    * :class:`~django.views.generic.dates.DateMixin`
    * :class:`~django.views.generic.list.MultipleObjectMixin`

    **Methods and Attributes**

    .. attribute:: allow_empty

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

    .. method:: get_dated_items():

        Returns a 3-tuple containing (``date_list``, ``object_list``,
        ``extra_context``).

        ``date_list`` is the list of dates for which data is available.
        ``object_list`` is the list of objects. ``extra_context`` is a
        dictionary of context data that will be added to any context data
        provided by the
        :class:`~django.views.generic.list.MultipleObjectMixin`.

    .. method:: get_dated_queryset(**lookup)

        Returns a queryset, filtered using the query arguments defined by
        ``lookup``. Enforces any restrictions on the queryset, such as
        ``allow_empty`` and ``allow_future``.

    .. method:: get_date_list(queryset, date_type)

        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.