mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-08-04 10:59:45 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Fixed #17260 -- Added time zone aware aggregation and lookups.

Browse source 
Thanks Carl Meyer for the review.

Squashed commit of the following:

commit 4f290bdb60
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date:   Wed Feb 13 21:21:30 2013 +0100

    Used '0:00' instead of 'UTC' which doesn't always exist in Oracle.

    Thanks Ian Kelly for the suggestion.

commit 01b6366f3c
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date:   Wed Feb 13 13:38:43 2013 +0100

    Made tzname a parameter of datetime_extract/trunc_sql.

    This is required to work around a bug in Oracle.

commit 924a144ef8
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date:   Wed Feb 13 14:47:44 2013 +0100

    Added support for parameters in SELECT clauses.

commit b4351d2890
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date:   Mon Feb 11 22:30:22 2013 +0100

    Documented backwards incompatibilities in the two previous commits.

commit 91ef84713c
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date:   Mon Feb 11 09:42:31 2013 +0100

    Used QuerySet.datetimes for the admin's date_hierarchy.

commit 0d0de288a5
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date:   Mon Feb 11 09:29:38 2013 +0100

    Used QuerySet.datetimes in date-based generic views.

commit 9c0859ff7c
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date:   Sun Feb 10 21:43:25 2013 +0100

    Implemented QuerySet.datetimes on Oracle.

commit 68ab511a4f
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date:   Sun Feb 10 21:43:14 2013 +0100

    Implemented QuerySet.datetimes on MySQL.

commit 22d52681d3
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date:   Sun Feb 10 21:42:29 2013 +0100

    Implemented QuerySet.datetimes on SQLite.

commit f6800fd04c
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date:   Sun Feb 10 21:43:03 2013 +0100

    Implemented QuerySet.datetimes on PostgreSQL.

commit 0c829c23f4
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date:   Sun Feb 10 21:41:08 2013 +0100

    Added datetime-handling infrastructure in the ORM layers.

commit 104d82a777
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date:   Mon Feb 11 10:05:55 2013 +0100

    Updated null_queries tests to avoid clashing with the __second lookup.

commit c01bbb3235
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date:   Sun Feb 10 23:07:41 2013 +0100

    Updated tests of .dates().

    Replaced .dates() by .datetimes() for DateTimeFields.
    Replaced dates with datetimes in the expected output for DateFields.

commit 50fb7a5246
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date:   Sun Feb 10 21:40:09 2013 +0100

    Updated and added tests for QuerySet.datetimes.

commit a8451a5004
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date:   Sun Feb 10 22:34:46 2013 +0100

    Documented the new time lookups and updated the date lookups.

commit 29413eab2b
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date:   Sun Feb 10 16:15:49 2013 +0100

    Documented QuerySet.datetimes and updated QuerySet.dates.
This commit is contained in:
Aymeric Augustin 2013-02-10 16:15:49 +01:00
parent 91c26eadc9
commit e74e207cce
51 changed files with 1041 additions and 300 deletions
Download patch file Download diff file Expand all files Collapse all files

157
docs/ref/models/querysets.txt
View file

@ -550,14 +550,19 @@ dates
.. method:: dates(field, kind, order='ASC')
Returns a ``DateQuerySet`` — a ``QuerySet`` that evaluates to a list of
``datetime.datetime`` objects representing all available dates of a particular
kind within the contents of the ``QuerySet``.
:class:`datetime.date` objects representing all available dates of a
particular kind within the contents of the ``QuerySet``.
``field`` should be the name of a ``DateField`` or ``DateTimeField`` of your
model.
.. versionchanged:: 1.6
``dates`` used to return a list of :class:`datetime.datetime` objects.
``field`` should be the name of a ``DateField`` of your model.
.. versionchanged:: 1.6
``dates`` used to accept operating on a ``DateTimeField``.
``kind`` should be either ``"year"``, ``"month"`` or ``"day"``. Each
``datetime.datetime`` object in the result list is "truncated" to the given
``datetime.date`` object in the result list is "truncated" to the given
``type``.
* ``"year"`` returns a list of all distinct year values for the field.
@ -572,21 +577,60 @@ model.
Examples::
>>> Entry.objects.dates('pub_date', 'year')
[datetime.datetime(2005, 1, 1)]
[datetime.date(2005, 1, 1)]
>>> Entry.objects.dates('pub_date', 'month')
[datetime.datetime(2005, 2, 1), datetime.datetime(2005, 3, 1)]
[datetime.date(2005, 2, 1), datetime.date(2005, 3, 1)]
>>> Entry.objects.dates('pub_date', 'day')
[datetime.datetime(2005, 2, 20), datetime.datetime(2005, 3, 20)]
[datetime.date(2005, 2, 20), datetime.date(2005, 3, 20)]
>>> Entry.objects.dates('pub_date', 'day', order='DESC')
[datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)]
[datetime.date(2005, 3, 20), datetime.date(2005, 2, 20)]
>>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')
[datetime.datetime(2005, 3, 20)]
[datetime.date(2005, 3, 20)]
.. warning::
datetimes
~~~~~~~~~
When :doc:`time zone support </topics/i18n/timezones>` is enabled, Django
uses UTC in the database connection, which means the aggregation is
performed in UTC. This is a known limitation of the current implementation.
.. versionadded:: 1.6
.. method:: datetimes(field, kind, order='ASC', tzinfo=None)
Returns a ``DateTimeQuerySet`` — a ``QuerySet`` that evaluates to a list of
:class:`datetime.datetime` objects representing all available dates of a
particular kind within the contents of the ``QuerySet``.
``field`` should be the name of a ``DateTimeField`` of your model.
``kind`` should be either ``"year"``, ``"month"``, ``"day"``, ``"hour"``,
``"minute"`` or ``"second"``. Each ``datetime.datetime`` object in the result
list is "truncated" to the given ``type``.
``order``, which defaults to ``'ASC'``, should be either ``'ASC'`` or
``'DESC'``. This specifies how to order the results.
``tzinfo`` defines the time zone to which datetimes are converted prior to
truncation. Indeed, a given datetime has different representations depending
on the time zone in use. This parameter must be a :class:`datetime.tzinfo`
object. If it's ``None``, Django uses the :ref:`current time zone
<default-current-time-zone>`. It has no effect when :setting:`USE_TZ` is
``False``.
.. _database-time-zone-definitions:
.. note::
This function performs time zone conversions directly in the database.
As a consequence, your database must be able to interpret the value of
``tzinfo.tzname(None)``. This translates into the following requirements:
- SQLite: install pytz_ — conversions are actually performed in Python.
- PostgreSQL: no requirements (see `Time Zones`_).
- Oracle: no requirements (see `Choosing a Time Zone File`_).
- MySQL: load the time zone tables with `mysql_tzinfo_to_sql`_.
.. _pytz: http://pytz.sourceforge.net/
.. _Time Zones: http://www.postgresql.org/docs/9.2/static/datatype-datetime.html#DATATYPE-TIMEZONES
.. _Choosing a Time Zone File: http://docs.oracle.com/cd/B19306_01/server.102/b14225/ch4datetime.htm#i1006667
.. _mysql_tzinfo_to_sql: http://dev.mysql.com/doc/refman/5.5/en/mysql-tzinfo-to-sql.html
none
~~~~
@ -2020,7 +2064,7 @@ numbers and even characters.
year
~~~~
For date/datetime fields, exact year match. Takes a four-digit year.
For date and datetime fields, an exact year match. Takes an integer year.
Example::
@ -2032,6 +2076,9 @@ SQL equivalent::
(The exact SQL syntax varies for each database engine.)
When :setting:`USE_TZ` is ``True``, datetime fields are converted to the
current time zone before filtering.
.. fieldlookup:: month
month
@ -2050,12 +2097,15 @@ SQL equivalent::
(The exact SQL syntax varies for each database engine.)
When :setting:`USE_TZ` is ``True``, datetime fields are converted to the
current time zone before filtering.
.. fieldlookup:: day
day
~~~
For date and datetime fields, an exact day match.
For date and datetime fields, an exact day match. Takes an integer day.
Example::
@ -2070,6 +2120,9 @@ SQL equivalent::
Note this will match any record with a pub_date on the third day of the month,
such as January 3, July 3, etc.
When :setting:`USE_TZ` is ``True``, datetime fields are converted to the
current time zone before filtering.
.. fieldlookup:: week_day
week_day
@ -2091,12 +2144,74 @@ Note this will match any record with a ``pub_date`` that falls on a Monday (day
2 of the week), regardless of the month or year in which it occurs. Week days
are indexed with day 1 being Sunday and day 7 being Saturday.
.. warning::
When :setting:`USE_TZ` is ``True``, datetime fields are converted to the
current time zone before filtering.
When :doc:`time zone support </topics/i18n/timezones>` is enabled, Django
uses UTC in the database connection, which means the ``year``, ``month``,
``day`` and ``week_day`` lookups are performed in UTC. This is a known
limitation of the current implementation.
.. fieldlookup:: hour
hour
~~~~
.. versionadded:: 1.6
For datetime fields, an exact hour match. Takes an integer between 0 and 23.
Example::
Event.objects.filter(timestamp__hour=23)
SQL equivalent::
SELECT ... WHERE EXTRACT('hour' FROM timestamp) = '23';
(The exact SQL syntax varies for each database engine.)
When :setting:`USE_TZ` is ``True``, values are converted to the current time
zone before filtering.
.. fieldlookup:: minute
minute
~~~~~~
.. versionadded:: 1.6
For datetime fields, an exact minute match. Takes an integer between 0 and 59.
Example::
Event.objects.filter(timestamp__minute=29)
SQL equivalent::
SELECT ... WHERE EXTRACT('minute' FROM timestamp) = '29';
(The exact SQL syntax varies for each database engine.)
When :setting:`USE_TZ` is ``True``, values are converted to the current time
zone before filtering.
.. fieldlookup:: second
second
~~~~~~
.. versionadded:: 1.6
For datetime fields, an exact second match. Takes an integer between 0 and 59.
Example::
Event.objects.filter(timestamp__second=31)
SQL equivalent::
SELECT ... WHERE EXTRACT('second' FROM timestamp) = '31';
(The exact SQL syntax varies for each database engine.)
When :setting:`USE_TZ` is ``True``, values are converted to the current time
zone before filtering.
.. fieldlookup:: isnull