docs: mention different infinity date adaptation in psycopg2 differences pages

See #315

diff --git a/docs/advanced/adapt.rst b/docs/advanced/adapt.rst
index 7ae1c7851aff8f0716cc226078deee81aae8f79d..73a82ea325c27add2d1e26097b88a11aefff454d 100644 (file)
--- a/docs/advanced/adapt.rst
+++ b/docs/advanced/adapt.rst
@@ -172,10 +172,10 @@ PostgreSQL but not handled by Python:
 
 .. code:: python
 
-    >>> conn.execute("'infinity'::date").fetchone()
+    >>> conn.execute("SELECT 'infinity'::date").fetchone()
     Traceback (most recent call last):
        ...
-    psycopg.DataError: Python date doesn't support years after 9999: got infinity
+    DataError: date too large (after year 10K): 'infinity'
 
 One possibility would be to store Python's `datetime.date.max` as PostgreSQL
 infinity. For this, let's create a subclass for the dumper and the loader and
@@ -193,6 +193,8 @@ cursor):
         def dump(self, obj):
             if obj == date.max:
                 return b"infinity"
+            elif obj == date.min:
+                return b"-infinity"
             else:
                 return super().dump(obj)
 
@@ -200,6 +202,8 @@ cursor):
         def load(self, data):
             if data == b"infinity":
                 return date.max
+            elif data == b"-infinity":
+                return date.min
             else:
                 return super().load(data)
 

diff --git a/docs/basic/from_pg2.rst b/docs/basic/from_pg2.rst
index d6cfec3251e3c1d5c25f51d2a58897bb2cc0b2cf..2bd3bd69ec694db387cd82fc26ba878baef5f047 100644 (file)
--- a/docs/basic/from_pg2.rst
+++ b/docs/basic/from_pg2.rst
@@ -274,6 +274,36 @@ connection by running a :sql:`SET client_encoding` statement... But why would
 you?
 
 
+.. _infinity-datetime:
+
+No default infinity dates handling
+----------------------------------
+
+PostgreSQL can represent has a much wider range of dates and timestamps than
+Python. While Python dates are limited to the years between 1 and 9999
+(represented by constants such as `datetime.date.min` and
+`~datetime.date.max`), PostgreSQL dates extend to BC dates and past the year
+10K. Furthermore PostgreSQL can also represent symbolic dates "infinity", in
+both directions.
+
+In psycopg2, by default, `infinity dates and timestamps map to 'date.max'`__
+and similar constants. This has the problem of creating a non-bijective
+mapping (two Postgres dates, infinity and 9999-12-31, both map to the same
+Python date). There is also the perversity that valid Postgres dates, greater
+than Python `!date.max` but arguably lesser than infinity, will still
+overflow.
+
+In Psycopg 3, every date greater than year 9999 will overflow, including
+infinity. If you would like to customize this mapping (for instance flattening
+every date past Y10K on `!date.max`) you can subclass and adapt the
+appropriate loaders: take a look at :ref:`this example
+<adapt-example-inf-date>` to see how.
+
+.. __: https://www.psycopg.org/docs/usage.html#infinite-dates-handling
+
+
+.. _whats-new:
+
 What's new in Psycopg 3
 -----------------------