docs: add porting tips for cursor subclasses

diff --git a/docs/advanced/rows.rst b/docs/advanced/rows.rst
index c23efe5c543c155999c34c242cb82c5202b05c54..fcb89ce9a8b3d4261e89c1a96713a2c3447ab185 100644 (file)
--- a/docs/advanced/rows.rst
+++ b/docs/advanced/rows.rst
@@ -92,7 +92,7 @@ Formally, these objects are represented by the `~psycopg.rows.RowFactory` and
        def __call__(self, values: Sequence[Any]) -> dict[str, Any]:
            return dict(zip(self.fields, values))
 
-or as a plain function:
+or as nested functions:
 
 .. code:: python
 

diff --git a/docs/api/rows.rst b/docs/api/rows.rst
index 204f1eacb730a1b633bd0b904bbf153479c5528d..d4c438242541908d7ef608f083a29a1af3ba8478 100644 (file)
--- a/docs/api/rows.rst
+++ b/docs/api/rows.rst
@@ -9,7 +9,7 @@ The module exposes a few generic `~psycopg.RowFactory` implementation, which
 can be used to retrieve data from the database in more complex structures than
 the basic tuples.
 
-Check out :ref:`row-factories` for information about how to use these objects.
+Check out :ref:`row-factory-create` for information about how to use these objects.
 
 .. autofunction:: tuple_row
 .. autofunction:: dict_row

diff --git a/docs/basic/from_pg2.rst b/docs/basic/from_pg2.rst
index 79e07034ac7c669ba1a486298fe3785aa32aec77..c449c10319b73f251bed05882e5aa117c1079f18 100644 (file)
--- a/docs/basic/from_pg2.rst
+++ b/docs/basic/from_pg2.rst
@@ -272,6 +272,36 @@ Analogously you can use :sql:`IS DISTINCT FROM %s` as a parametric version of
 :sql:`IS NOT %s`.
 
 
+.. _diff-cursors:
+
+Cursors subclasses
+------------------
+
+In `!psycopg2`, a few cursor subclasses allowed to return data in different
+form than tuples. In Psycopg 3 the same can be achieved by setting a :ref:`row
+factory <row-factories>`:
+
+- instead of `~psycopg2.extras.RealDictCursor` you can use
+  `~psycopg.rows.dict_row`;
+
+- instead of `~psycopg2.extras.NamedTupleCursor` you can use
+  `~psycopg.rows.namedtuple_row`.
+
+Other row factories are available in the `psycopg.rows` module. There isn't an
+object behaving like `~psycopg2.extras.DictCursor` (whose results are
+indexable both by column position and by column name).
+
+.. code::
+
+    from psycopg.rows import dict_row, namedtuple_row
+
+    # By default, every cursor will return dicts.
+    conn = psycopg.connect(DSN, row_factory=dict_row)
+
+    # You can set a row factory on a single cursor too.
+    cur = conn.cursor(row_factory=namedtuple_row)
+
+
 .. _diff-adapt:
 
 Different adaptation system