[REF] *: use native date/datetime for Date/Datetime fields

From this commit onwards, Date fields will return datetime.date objects and Datetime fields will return datetime.datetime objects, this implies a number of things that are clearly explained both in the ORM API for master.

This commit also introduces a number of helper functions for dates and datetimes that are exposed in tools.date_utils and fields.Date[time], explained in the documentation as well.

Task-ID: 47189

1 files changed, 46 insertions, 2 deletions

diff --git a/doc/reference/orm.rst b/doc/reference/orm.rst
index 9ce03c8709a..1a0dba9edf1 100644
--- a/doc/reference/orm.rst
+++ b/doc/reference/orm.rst
@@ -866,13 +866,57 @@ Basic fields
 .. autoclass:: odoo.fields.Html
     :show-inheritance:
 
+.. _reference/orm/fields/date_datetime:
+
+Date and Datetime fields
+------------------------
+
+Dates and Datetimes are very important fields in any kind of business
+application, they are heavily used in many popular Odoo applications such as
+logistics or accounting and their misuse can create invisible yet painful
+bugs, this excerpt aims to provide Odoo developers with the knowledge required
+to avoid misusing these fields.
+
+When assigning a value to a Date/Datetime field, the following options are valid:
+    * A string in the proper server format **(YYYY-MM-DD)** for Date fields,
+      **(YYYY-MM-DD HH:MM:SS)** for Datetime fields.
+    * A `date` or `datetime` object.
+    * `False` or `None`.
+
+If not sure of the type of the value being assigned to a Date/Datetime object,
+the best course of action is to pass the value to
+:func:`~odoo.fields.Date.to_date` or :func:`~odoo.fields.Datetime.to_datetime`
+which will attempt to convert the value to a date or datetime object
+respectively, which can then be assigned to the field in question.
+
+.. admonition:: Example
+
+    To parse date/datetimes coming from external sources::
+
+        fields.Date.to_date(self._context.get('date_from'))
+
+Date / Datetime comparison best practices:
+    * Date fields can **only** be compared to date objects.
+    * Datetime fields can **only** be compared to datetime objects.
+
+    .. warning:: Strings representing dates and datetimes can be compared
+                 between each other, however the result may not be the expected
+                 result, as a datetime string will always be greater than a
+                 date string, therefore this practice is **heavily**
+                 discouraged.
+
+Common operations with dates and datetimes such as addition, substraction or
+fetching the start/end of a period are exposed through both
+:class:`~odoo.fields.Date` and :class:`~odoo.fields.Datetime`.
+These helpers are also available by importing `odoo.tools.date_utils`.
+
 .. autoclass:: odoo.fields.Date
     :show-inheritance:
-    :members: today, context_today, from_string, to_string
+    :members: today, context_today, to_date, to_string, start_of, end_of, add, subtract
 
 .. autoclass:: odoo.fields.Datetime
     :show-inheritance:
-    :members: now, context_timestamp, from_string, to_string
+    :members: now, today, context_timestamp, to_datetime, to_string, start_of, end_of, add, subtract
 
 .. _reference/orm/fields/relational: