From a603dbabea9efc6f5ac142417cde310e8ec62eef Mon Sep 17 00:00:00 2001 From: wesley Date: Wed, 9 Oct 2024 18:10:56 -0400 Subject: [PATCH] ticket #34699. fixed documentation spel chek error. Reformatted example to be inside warning block. --- docs/ref/models/database-functions.txt | 58 +++++++++++++------------- 1 file changed, 28 insertions(+), 30 deletions(-) diff --git a/docs/ref/models/database-functions.txt b/docs/ref/models/database-functions.txt index 75c5030989..ce191681e2 100644 --- a/docs/ref/models/database-functions.txt +++ b/docs/ref/models/database-functions.txt @@ -660,38 +660,36 @@ Usage example: .. warning:: - Trunc functions, at the database level, return a timezone naive value which - is converted to a timezone aware value by the ORM. When you use a Trunc - function in a filter you will need to remember that it is a timezone naive - value. This can lead to unexpected results if you are using timezones other - than UTC. Django will store date/time values in the database in the UTC - timezone. The following example demonstrates what happens when using the - timezone "Europe/Berlin" and how to adjust for this: + ``Trunc`` functions, at the database level, return a timezone naive value + which is converted to a timezone aware value by the ORM. When you use a + ``Trunc`` function in a filter you will need to remember that it is a + timezone naive value. This can lead to unexpected results if you are using + timezones other than UTC. Django will store date/time values in the + database in the UTC timezone. The following example demonstrates what + happens when using the timezone "Europe/Berlin" and how to adjust for this: -Filter example using the "Europe/Berlin" timezone.: + .. code-block:: pycon -.. code-block:: pycon - - >>> from django.utils import timezone - >>> from datetime import datetime - >>> from django.db.models.functions import TruncSecond - >>> import zoneinfo - >>> start = datetime(2015, 6, 15, 14, 30, 50, 321) - >>> start = timezone.make_aware(start) - >>> exp = Experiment.objects.create(start_datetime=start) - >>> find_this_exp = Experiment.objects.annotate( - ... trunc_start=TruncSecond("start_datetime") - ... ).filter(trunc_start__lte=start) - >>> find_this_exp.count() # We expect to find one result but 0 are found - ... - 0 - >>> start_adjusted = timezone.localtime(start).replace(tzinfo=zoneinfo.ZoneInfo(key='UTC')) - >>> find_this_exp_adjusted = Experiment.objects.annotate( - ... trunc_start=TruncSecond("start_datetime") - ... ).filter(trunc_start__lte=start_adjusted) - >>> find_this_exp.count() - ... - 1 + >>> from django.utils import timezone + >>> from datetime import datetime + >>> from django.db.models.functions import TruncSecond + >>> import zoneinfo + >>> start = datetime(2015, 6, 15, 14, 30, 50, 321) + >>> start = timezone.make_aware(start) + >>> exp = Experiment.objects.create(start_datetime=start) + >>> find_this_exp = Experiment.objects.annotate( + ... trunc_start=TruncSecond("start_datetime") + ... ).filter(trunc_start__lte=start) + >>> find_this_exp.count() # We expect to find one result but 0 are found + ... + 0 + >>> start_adjusted = timezone.localtime(start).replace(tzinfo=zoneinfo.ZoneInfo(key='UTC')) + >>> find_this_exp_adjusted = Experiment.objects.annotate( + ... trunc_start=TruncSecond("start_datetime") + ... ).filter(trunc_start__lte=start_adjusted) + >>> find_this_exp.count() + ... + 1 ``DateField`` truncation ~~~~~~~~~~~~~~~~~~~~~~~~