From bf9a89f5d1ffa56fa1b37ebf23cba00fdb62f6d0 Mon Sep 17 00:00:00 2001 From: Adam Zapletal Date: Tue, 19 Mar 2024 21:19:31 -0500 Subject: [PATCH] [5.1.x] Fixed #24076 -- Added warnings on usage of dates with DateTimeField and datetimes with DateField. Backport of 99273fd525129a973639044dfb12cfd732d8f1d6 from main. --- docs/ref/models/fields.txt | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index ba46726ab8..f76ee26a70 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -808,6 +808,15 @@ Any combination of these options will result in an error. instead of a ``DateField`` and deciding how to handle the conversion from datetime to date at display time. +.. warning:: Always use :class:`DateField` with a ``datetime.date`` instance. + + If you have a ``datetime.datetime`` instance, it's recommended to convert + it to a ``datetime.date`` first. If you don't, :class:`DateField` will + localize the ``datetime.datetime`` to the :ref:`default timezone + ` and convert it to a ``datetime.date`` + instance, removing its time component. This is true for both storage and + comparison. + ``DateTimeField`` ----------------- @@ -820,6 +829,16 @@ The default form widget for this field is a single :class:`~django.forms.DateTimeInput`. The admin uses two separate :class:`~django.forms.TextInput` widgets with JavaScript shortcuts. +.. warning:: Always use :class:`DateTimeField` with a ``datetime.datetime`` + instance. + + If you have a ``datetime.date`` instance, it's recommended to convert it to + a ``datetime.datetime`` first. If you don't, :class:`DateTimeField` will + use midnight in the :ref:`default timezone ` for + the time component. This is true for both storage and comparison. To + compare the date portion of a :class:`DateTimeField` with a + ``datetime.date`` instance, use the :lookup:`date` lookup. + ``DecimalField`` ----------------