Update documentation about obtaining timezone-aware timestamps

Co-authored-by: Mathias Fußenegger <[email protected]>

Author: amotl

CHANGES.txt

@@ -11,7 +11,7 @@ Unreleased
 - SQLAlchemy DDL: Allow setting ``server_default`` on columns to enable
   server-generated defaults. Thanks, @JanLikar.
 
-- Allow handling "aware" datetime values with time zone info when inserting or updating.
+- Allow handling datetime values tagged with time zone info when inserting or updating.
 
 
 2023/04/18 0.31.1

docs/by-example/client.rst

@@ -142,8 +142,9 @@ Refresh locations:
 Updating Data
 =============
 
-Both when inserting or updating data, values for ``TIMESTAMP`` columns can be obtained
-in different formats. Both literal strings and datetime objects are supported.
+Values for ``TIMESTAMP`` columns can be obtained as a string literal, ``date``,
+or ``datetime`` object. If it contains timezone information, it is converted to
+UTC, and the timezone information is discarded.
 
     >>> import datetime as dt
     >>> timestamp_full = "2023-06-26T09:24:00.123+02:00"

docs/data-types.rst

@@ -99,13 +99,14 @@ __ https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#c
 
 .. NOTE::
 
-    Values of ``TIMESTAMP`` columns will always be stored using a ``LONG`` type,
-    representing the `Unix time`_ (epoch) timestamp, i.e. number of seconds which
-    have passed since 00:00:00 UTC on Thursday, 1 January 1970.
+    When using ``date`` or ``datetime`` objects with ``timezone`` information,
+    the value is implicitly converted to a `Unix time`_ (epoch) timestamp, i.e.
+    the number of seconds which have passed since 00:00:00 UTC on
+    Thursday, 1 January 1970.
 
     This means, when inserting or updating records using timezone-aware Python
-    ``datetime`` objects, timezone information will not be preserved. If you
-    need to store it, you will need to use a separate column.
+    ``date`` or ``datetime`` objects, timezone information will not be
+    preserved. If you need to store it, you will need to use a separate column.
 
 
 .. _data-types-sqlalchemy: