Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Documented QuerySet.datetimes and updated QuerySet.dates.

  • Loading branch information...
commit 29413eab2bd1d5e004598900c0dadc0521bbf4d3 1 parent ac4faa6
@aaugustin aaugustin authored
Showing with 75 additions and 14 deletions.
  1. +56 −14 docs/ref/models/querysets.txt
  2. +19 −0 docs/releases/1.6.txt
View
70 docs/ref/models/querysets.txt
@@ -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,58 @@ 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``.
+
+.. 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
~~~~
View
19 docs/releases/1.6.txt
@@ -30,6 +30,16 @@ prevention <clickjacking-prevention>` are turned on.
If the default templates don't suit your tastes, you can use :ref:`custom
project and app templates <custom-app-and-project-templates>`.
+Time zone aware aggregation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The support for :doc:`time zones </topics/i18n/timezones>` introduced in
+Django 1.4 didn't work well with :meth:`QuerySet.dates()
+<django.db.models.query.QuerySet.dates>`: aggregation was always performed in
+UTC. This limitation was lifted in Django 1.6. Use :meth:`QuerySet.datetimes()
+<django.db.models.query.QuerySet.datetimes>` to perform time zone aware
+aggregation on a :class:`~django.db.models.DateTimeField`.
+
Minor features
~~~~~~~~~~~~~~
@@ -80,6 +90,15 @@ Backwards incompatible changes in 1.6
:meth:`~django.db.models.query.QuerySet.none` has been called:
``isinstance(qs.none(), EmptyQuerySet)``
+* :meth:`QuerySet.dates() <django.db.models.query.QuerySet.dates>` raises an
+ error if it's used on :class:`~django.db.models.DateTimeField` when time
+ zone support is active. Use :meth:`QuerySet.datetimes()
+ <django.db.models.query.QuerySet.datetimes>` instead.
+
+* :meth:`QuerySet.dates() <django.db.models.query.QuerySet.dates>` returns a
+ list of :class:`~datetime.date`. It used to return a list of
+ :class:`~datetime.datetime`.
+
* If your CSS/Javascript code used to access HTML input widgets by type, you
should review it as ``type='text'`` widgets might be now output as
``type='email'`` or ``type='url'`` depending on their corresponding field type.
Please sign in to comment.
Something went wrong with that request. Please try again.