mirror of
https://github.com/django/django.git
synced 2024-12-23 17:46:27 +00:00
4a954cfd11
This patch does not remove all occurrences of the words in question. Rather, I went through all of the occurrences of the words listed below, and judged if they a) suggested the reader had some kind of knowledge/experience, and b) if they added anything of value (including tone of voice, etc). I left most of the words alone. I looked at the following words: - simply/simple - easy/easier/easiest - obvious - just - merely - straightforward - ridiculous Thanks to Carlton Gibson for guidance on how to approach this issue, and to Tim Bell for providing the idea. But the enormous lion's share of thanks go to Adam Johnson for his patient and helpful review.
337 lines
12 KiB
Plaintext
337 lines
12 KiB
Plaintext
=================
|
||
Date-based mixins
|
||
=================
|
||
|
||
.. currentmodule:: django.views.generic.dates
|
||
|
||
.. note::
|
||
|
||
All the date formatting attributes in these mixins use
|
||
:func:`~time.strftime` format characters. Do not try to use the format
|
||
characters from the :ttag:`now` template tag as they are not compatible.
|
||
|
||
``YearMixin``
|
||
=============
|
||
|
||
.. class:: 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, 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`` ``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:: 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, 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`` ``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. 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_month(date)
|
||
|
||
Returns a date object containing the first day of the month 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`.
|
||
|
||
``DayMixin``
|
||
============
|
||
|
||
.. class:: 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, 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`` ``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 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_previous_day(date)
|
||
|
||
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:: 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'``, 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
|
||
``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, 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
|
||
* The value of the ``week`` ``GET`` query argument.
|
||
|
||
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:: 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 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
|
||
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:: 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 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.
|
||
|
||
**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.
|
||
|
||
This is identical to
|
||
:attr:`django.views.generic.list.MultipleObjectMixin.allow_empty`,
|
||
except for the default value, which is ``False``.
|
||
|
||
.. attribute:: date_list_period
|
||
|
||
**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``).
|
||
|
||
``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_period()
|
||
|
||
Returns the aggregation period for ``date_list``. Returns
|
||
:attr:`~BaseDateListView.date_list_period` by default.
|
||
|
||
.. method:: get_date_list(queryset, date_type=None, ordering='ASC')
|
||
|
||
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. ``date_type``
|
||
and ``ordering`` are passed to
|
||
:meth:`QuerySet.dates()<django.db.models.query.QuerySet.dates>`.
|