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

diff --git a/docs/basic/adapt.rst b/docs/basic/adapt.rst
index 1538327a74290c6df7c05f47b594c356286d70f2..9bb7ef45afe40d0993d46e43a90befd7d2bf758b 100644 (file)
--- 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