TIMESTAMP->dt: Improve documentation about time_zone argument

src/crate/client/connection.py

@@ -108,6 +108,20 @@ def __init__(self,
             (optional, defaults to ``None``)
             A time zone specifier used for returning `TIMESTAMP` types as
             timezone-aware native Python `datetime` objects.
+
+            Different data types are supported. Available options are:
+
+            - ``datetime.timezone.utc``
+            - ``datetime.timezone(datetime.timedelta(hours=7), name="MST")``
+            - ``pytz.timezone("Australia/Sydney")``
+            - ``zoneinfo.ZoneInfo("Australia/Sydney")``
+            - ``+0530`` (UTC offset in string format)
+
+            When `time_zone` is `None`, the returned `datetime` objects are
+            "naive", without any `tzinfo`, converted using ``datetime.utcfromtimestamp(...)``.
+
+            When `time_zone` is given, the returned `datetime` objects are "aware",
+            with `tzinfo` set, converted using ``datetime.fromtimestamp(..., tz=...)``.
         """
 
         self._converter = converter

src/crate/client/cursor.py

@@ -255,13 +255,19 @@ def time_zone(self, tz):
         """
         Set the time zone.
 
-        It supports different ways to populate. Some examples::
+        Different data types are supported. Available options are:
 
         - ``datetime.timezone.utc``
         - ``datetime.timezone(datetime.timedelta(hours=7), name="MST")``
         - ``pytz.timezone("Australia/Sydney")``
         - ``zoneinfo.ZoneInfo("Australia/Sydney")``
         - ``+0530`` (UTC offset in string format)
+
+        When `time_zone` is `None`, the returned `datetime` objects are
+        "naive", without any `tzinfo`, converted using ``datetime.utcfromtimestamp(...)``.
+
+        When `time_zone` is given, the returned `datetime` objects are "aware",
+        with `tzinfo` set, converted using ``datetime.fromtimestamp(..., tz=...)``.
         """
 
         # Do nothing when time zone is reset.

src/crate/client/doctests/cursor.txt

@@ -391,7 +391,8 @@ For your reference, epoch 1658167836758 is ``Mon, 18 Jul 2022 18:10:36 GMT``.
     >>> cursor.fetchone()
     ['foo', datetime.datetime(2022, 7, 19, 1, 10, 36, 758000, tzinfo=datetime.timezone(datetime.timedelta(seconds=25200), 'MST'))]
 
-There are different ways to populate ``time_zone``. Some examples::
+For the ``time_zone`` keyword argument, different data types are supported.
+The available options are:
 
 - ``datetime.timezone.utc``
 - ``datetime.timezone(datetime.timedelta(hours=7), name="MST")``