Fixed #33308 -- Added support for psycopg version 3.

Thanks Simon Charette, Tim Graham, and Adam Johnson for reviews.

Co-authored-by: Florian Apolloner <florian@apolloner.eu>
Co-authored-by: Mariusz Felisiak <felisiak.mariusz@gmail.com>

4 files changed, 38 insertions, 32 deletions

diff --git a/docs/ref/contrib/gis/install/index.txt b/docs/ref/contrib/gis/install/index.txt
index 51b3235279..026c64ccd1 100644
--- a/docs/ref/contrib/gis/install/index.txt
+++ b/docs/ref/contrib/gis/install/index.txt
@@ -429,14 +429,14 @@ Install Django and set up database
 recommended that you create a :doc:`virtual environment
 <python:tutorial/venv>` for each project you create.
 
-psycopg2
-~~~~~~~~
+psycopg
+~~~~~~~
 
-The ``psycopg2`` Python module provides the interface between Python and the
-PostgreSQL database. ``psycopg2`` can be installed via pip within your Python
+The ``psycopg`` Python module provides the interface between Python and the
+PostgreSQL database. ``psycopg`` can be installed via pip within your Python
 virtual environment::
 
-    ...\> py -m pip install psycopg2
+    ...\> py -m pip install psycopg
 
 .. rubric:: Footnotes
 .. [#] GeoDjango uses the :func:`~ctypes.util.find_library` routine from
diff --git a/docs/ref/contrib/gis/install/postgis.txt b/docs/ref/contrib/gis/install/postgis.txt
index 0c7d20ae84..e469ede4d0 100644
--- a/docs/ref/contrib/gis/install/postgis.txt
+++ b/docs/ref/contrib/gis/install/postgis.txt
@@ -7,20 +7,25 @@ into a spatial database. :ref:`geosbuild`, :ref:`proj4` and
 :ref:`gdalbuild` should be installed prior to building PostGIS. You
 might also need additional libraries, see `PostGIS requirements`_.
 
-The `psycopg2`_ module is required for use as the database adapter when using
-GeoDjango with PostGIS.
+The `psycopg`_ or `psycopg2`_ module is required for use as the database
+adapter when using GeoDjango with PostGIS.
 
 On Debian/Ubuntu, you are advised to install the following packages:
 ``postgresql-x``, ``postgresql-x-postgis-3``, ``postgresql-server-dev-x``,
-and ``python3-psycopg2`` (x matching the PostgreSQL version you want to
+and ``python3-psycopg3`` (x matching the PostgreSQL version you want to
 install). Alternately, you can `build from source`_. Consult the
 platform-specific instructions if you are on :ref:`macos` or :ref:`windows`.
 
 .. _PostGIS: https://postgis.net/
+.. _psycopg: https://www.psycopg.org/psycopg3/
 .. _psycopg2: https://www.psycopg.org/
 .. _PostGIS requirements: https://postgis.net/docs/postgis_installation.html#install_requirements
 .. _build from source: https://postgis.net/docs/postgis_installation.html#install_short_version
 
+.. versionchanged:: 4.2
+
+    Support for ``psycopg`` 3.1+ was added.
+
 Post-installation
 =================
 
diff --git a/docs/ref/contrib/postgres/fields.txt b/docs/ref/contrib/postgres/fields.txt
index 2e6ce4253e..34ad06a09a 100644
--- a/docs/ref/contrib/postgres/fields.txt
+++ b/docs/ref/contrib/postgres/fields.txt
@@ -538,8 +538,8 @@ PostgreSQL. These fields are used to store a range of values; for example the
 start and end timestamps of an event, or the range of ages an activity is
 suitable for.
 
-All of the range fields translate to :ref:`psycopg2 Range objects
-<psycopg2:adapt-range>` in Python, but also accept tuples as input if no bounds
+All of the range fields translate to :ref:`psycopg Range objects
+<psycopg:adapt-range>` in Python, but also accept tuples as input if no bounds
 information is necessary. The default is lower bound included, upper bound
 excluded, that is ``[)`` (see the PostgreSQL documentation for details about
 `different bounds`_). The default bounds can be changed for non-discrete range
@@ -553,8 +553,8 @@ the ``default_bounds`` argument.
 
     Stores a range of integers. Based on an
     :class:`~django.db.models.IntegerField`. Represented by an ``int4range`` in
-    the database and a :class:`~psycopg2:psycopg2.extras.NumericRange` in
-    Python.
+    the database and a
+    ``django.db.backends.postgresql.psycopg_any.NumericRange`` in Python.
 
     Regardless of the bounds specified when saving the data, PostgreSQL always
     returns a range in a canonical form that includes the lower bound and
@@ -567,8 +567,8 @@ the ``default_bounds`` argument.
 
     Stores a range of large integers. Based on a
     :class:`~django.db.models.BigIntegerField`. Represented by an ``int8range``
-    in the database and a :class:`~psycopg2:psycopg2.extras.NumericRange` in
-    Python.
+    in the database and a
+    ``django.db.backends.postgresql.psycopg_any.NumericRange`` in Python.
 
     Regardless of the bounds specified when saving the data, PostgreSQL always
     returns a range in a canonical form that includes the lower bound and
@@ -581,8 +581,8 @@ the ``default_bounds`` argument.
 
     Stores a range of floating point values. Based on a
     :class:`~django.db.models.DecimalField`. Represented by a ``numrange`` in
-    the database and a :class:`~psycopg2:psycopg2.extras.NumericRange` in
-    Python.
+    the database and a
+    ``django.db.backends.postgresql.psycopg_any.NumericRange`` in Python.
 
     .. attribute:: DecimalRangeField.default_bounds
 
@@ -592,7 +592,7 @@ the ``default_bounds`` argument.
         default is lower bound included, upper bound excluded, that is ``[)``
         (see the PostgreSQL documentation for details about
         `different bounds`_). ``default_bounds`` is not used for
-        :class:`~psycopg2:psycopg2.extras.NumericRange` inputs.
+        ``django.db.backends.postgresql.psycopg_any.NumericRange`` inputs.
 
 ``DateTimeRangeField``
 ----------------------
@@ -601,8 +601,8 @@ the ``default_bounds`` argument.
 
     Stores a range of timestamps. Based on a
     :class:`~django.db.models.DateTimeField`. Represented by a ``tstzrange`` in
-    the database and a :class:`~psycopg2:psycopg2.extras.DateTimeTZRange` in
-    Python.
+    the database and a
+    ``django.db.backends.postgresql.psycopg_any.DateTimeTZRange`` in Python.
 
     .. attribute:: DateTimeRangeField.default_bounds
 
@@ -612,7 +612,7 @@ the ``default_bounds`` argument.
         default is lower bound included, upper bound excluded, that is ``[)``
         (see the PostgreSQL documentation for details about
         `different bounds`_). ``default_bounds`` is not used for
-        :class:`~psycopg2:psycopg2.extras.DateTimeTZRange` inputs.
+        ``django.db.backends.postgresql.psycopg_any.DateTimeTZRange`` inputs.
 
 ``DateRangeField``
 ------------------
@@ -621,7 +621,8 @@ the ``default_bounds`` argument.
 
     Stores a range of dates. Based on a
     :class:`~django.db.models.DateField`. Represented by a ``daterange`` in the
-    database and a :class:`~psycopg2:psycopg2.extras.DateRange` in Python.
+    database and a ``django.db.backends.postgresql.psycopg_any.DateRange`` in
+    Python.
 
     Regardless of the bounds specified when saving the data, PostgreSQL always
     returns a range in a canonical form that includes the lower bound and
@@ -655,7 +656,7 @@ We will also use the following example objects::
 
 and ``NumericRange``:
 
-    >>> from psycopg2.extras import NumericRange
+    >>> from django.db.backends.postgresql.psycopg_any import NumericRange
 
 Containment functions
 ~~~~~~~~~~~~~~~~~~~~~
@@ -690,7 +691,7 @@ The ``contained_by`` lookup is also available on the non-range field types:
 :class:`~django.db.models.DateField`, and
 :class:`~django.db.models.DateTimeField`. For example::
 
-    >>> from psycopg2.extras import DateTimeTZRange
+    >>> from django.db.backends.postgresql.psycopg_any import DateTimeTZRange
     >>> Event.objects.filter(
     ...     start__contained_by=DateTimeTZRange(
     ...         timezone.now() - datetime.timedelta(hours=1),
@@ -864,9 +865,9 @@ Defining your own range types
 -----------------------------
 
 PostgreSQL allows the definition of custom range types. Django's model and form
-field implementations use base classes below, and psycopg2 provides a
-:func:`~psycopg2:psycopg2.extras.register_range` to allow use of custom range
-types.
+field implementations use base classes below, and ``psycopg`` provides a
+:func:`~psycopg:psycopg.types.range.register_range` to allow use of custom
+range types.
 
 .. class:: RangeField(**options)
 
@@ -878,7 +879,7 @@ types.
 
     .. attribute:: range_type
 
-        The psycopg2 range type to use.
+        The range type to use.
 
     .. attribute:: form_field
 
@@ -895,7 +896,7 @@ types.
 
     .. attribute:: range_type
 
-        The psycopg2 range type to use.
+        The range type to use.
 
 Range operators
 ---------------
diff --git a/docs/ref/contrib/postgres/forms.txt b/docs/ref/contrib/postgres/forms.txt
index e5d597655f..8f9dd449d1 100644
--- a/docs/ref/contrib/postgres/forms.txt
+++ b/docs/ref/contrib/postgres/forms.txt
@@ -173,7 +173,7 @@ not greater than the upper bound. All of these fields use
 .. class:: IntegerRangeField
 
     Based on :class:`~django.forms.IntegerField` and translates its input into
-    :class:`~psycopg2:psycopg2.extras.NumericRange`. Default for
+    ``django.db.backends.postgresql.psycopg_any.NumericRange``. Default for
     :class:`~django.contrib.postgres.fields.IntegerRangeField` and
     :class:`~django.contrib.postgres.fields.BigIntegerRangeField`.
 
@@ -183,7 +183,7 @@ not greater than the upper bound. All of these fields use
 .. class:: DecimalRangeField
 
     Based on :class:`~django.forms.DecimalField` and translates its input into
-    :class:`~psycopg2:psycopg2.extras.NumericRange`. Default for
+    ``django.db.backends.postgresql.psycopg_any.NumericRange``. Default for
     :class:`~django.contrib.postgres.fields.DecimalRangeField`.
 
 ``DateTimeRangeField``
@@ -192,7 +192,7 @@ not greater than the upper bound. All of these fields use
 .. class:: DateTimeRangeField
 
     Based on :class:`~django.forms.DateTimeField` and translates its input into
-    :class:`~psycopg2:psycopg2.extras.DateTimeTZRange`. Default for
+    ``django.db.backends.postgresql.psycopg_any.DateTimeTZRange``. Default for
     :class:`~django.contrib.postgres.fields.DateTimeRangeField`.
 
 ``DateRangeField``
@@ -201,7 +201,7 @@ not greater than the upper bound. All of these fields use
 .. class:: DateRangeField
 
     Based on :class:`~django.forms.DateField` and translates its input into
-    :class:`~psycopg2:psycopg2.extras.DateRange`. Default for
+    ``django.db.backends.postgresql.psycopg_any.DateRange``. Default for
     :class:`~django.contrib.postgres.fields.DateRangeField`.
 
 Widgets