From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Thu, 26 Aug 2021 12:51:08 +0000 (+0200)
Subject: Clean up datetime adaptation docs
X-Git-Tag: 3.0.beta1~31
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=aa4a1c3abd328fd86131d43477e0fdfc58c1e2e4;p=thirdparty%2Fpsycopg.git

Clean up datetime adaptation docs
---

diff --git a/docs/basic/adapt.rst b/docs/basic/adapt.rst
index 9b0f70537..7189a944e 100644
--- a/docs/basic/adapt.rst
+++ b/docs/basic/adapt.rst
@@ -268,12 +268,26 @@ PostgreSQL :sql:`timestamptz` values are returned with a timezone set to the
 `~zoneinfo.ZoneInfo` object in the `!Connection.info`.\ `~ConnectionInfo.timezone`
 attribute::
 
-    >>> cnn.info.timezone
+    >>> conn.info.timezone
     zoneinfo.ZoneInfo(key='Europe/London')
 
-    >>> cnn.execute("select '2048-07-08 12:00'::timestamptz").fetchone()[0]
+    >>> conn.execute("select '2048-07-08 12:00'::timestamptz").fetchone()[0]
     datetime.datetime(2048, 7, 8, 12, 0, tzinfo=zoneinfo.ZoneInfo(key='Europe/London'))
 
+.. note::
+    PostgreSQL :sql:`timestamptz` doesn't store "a timestamp with a timezone
+    attached": it stores a timestamp always in UTC, which is converted, on
+    output, to the connection TimeZone setting::
+
+    >>> conn.execute("SET TIMEZONE to 'Europe/Rome'")  # UTC+2 in summer
+
+    >>> conn.execute("SELECT '2042-07-01 12:00Z'::timestamptz").fetchone()[0]  # UTC input
+    datetime.datetime(2042, 7, 1, 14, 0, tzinfo=zoneinfo.ZoneInfo(key='Europe/Rome'))
+
+    Check out the `PostgreSQL documentation about timezones`__ for all the
+    details.
+
+    .. __: https://www.postgresql.org/docs/13/datatype-datetime.html#DATATYPE-TIMEZONES
 
 .. __: https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-TIMEZONE