From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Tue, 16 May 2023 00:17:51 +0000 (+0200)
Subject: docs: add note regarding the differences in date/time domains
X-Git-Tag: pool-3.2.0~98
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8ec349089b60ff1ea52700b81431183e0f3c9867;p=thirdparty%2Fpsycopg.git

docs: add note regarding the differences in date/time domains
---

diff --git a/docs/basic/adapt.rst b/docs/basic/adapt.rst
index 1538327a7..9bb7ef45a 100644
--- a/docs/basic/adapt.rst
+++ b/docs/basic/adapt.rst
@@ -203,6 +203,22 @@ attribute::
     >>> conn.execute("select '2048-07-08 12:00'::timestamptz").fetchone()[0]
     datetime.datetime(2048, 7, 8, 12, 0, tzinfo=zoneinfo.ZoneInfo(key='Europe/London'))
 
+.. warning::
+    PostgreSQL date and time objects can represent values that cannot be
+    represented by the Python `datetime` objects:
+
+    - dates and timestamps after the year 9999, the special value "infinity";
+    - dates and timestamps before the year 1, the special value "-infinity";
+    - the time 24:00:00.
+
+    Loading these values will raise a `~psycopg.DataError`.
+
+    If you need to handle these values you can define your own mapping (for
+    instance mapping every value greater than `datetime.date.max` to
+    `!date.max`, or the time 24:00 to 00:00) and write a subclass of the
+    default loaders implementing the added capability; please see
+    :ref:`this example <adapt-example-inf-date>` for a reference.
+
 .. note::
     PostgreSQL :sql:`timestamptz` doesn't store "a timestamp with a timezone
     attached": it stores a timestamp always in UTC, which is converted, on