docs: cleanup of `results()` documentation

diff --git a/docs/api/cursors.rst b/docs/api/cursors.rst
index bcf03a8943260f1376f42ed0a9aa5c0bfe5cc64b..e63a98e18b5b1f3180559b1ce186c82d65446729 100644 (file)
--- a/docs/api/cursors.rst
+++ b/docs/api/cursors.rst
@@ -110,7 +110,7 @@ The `!Cursor` class
             Using the usual `~Cursor.fetchone()`, `~Cursor.fetchall()`, you
             will be able to read the records returned *by the first query
             executed only*. In order to read the results of the following
-            queries you can call `~Cursor.nextset()` to move to the following
+            queries you can call `nextset()` or `results()` to move across the
             result set.
 
             A typical use case for `!executemany(returning=True)` might be to
@@ -128,7 +128,7 @@ The `!Cursor` class
 
             More explicitly, `!fetchall()` alone will not return all the
             values returned! You must iterate on the results using
-            `!results()`.
+            `results()`.
 
         If `!returning=False`, the value of `rowcount` is set to the cumulated
         number of rows affected by queries. If `!returning=True`, `!rowcount`
@@ -282,6 +282,9 @@ The `!Cursor` class
 
         .. versionadded:: 3.3
 
+            In previous version you may call `nextset()` in a loop until it
+            returns a false value.
+
     .. automethod:: scroll
 
     .. attribute:: pgresult

diff --git a/docs/basic/from_pg2.rst b/docs/basic/from_pg2.rst
index e8d6b911273d428df74d599523d7eca540641031..53ac661a4a85f6bf62cde1d97807e50e582a4c35 100644 (file)
--- a/docs/basic/from_pg2.rst
+++ b/docs/basic/from_pg2.rst
@@ -198,20 +198,15 @@ result of the last statement is returned::
 In Psycopg 3 instead, all the results are available. After running the query,
 the first result will be readily available in the cursor and can be consumed
 using the usual `!fetch*()` methods. In order to access the following
-results, you can use the `Cursor.nextset()` method::
+results, you can use the `Cursor.results()` method (or `~Cursor.nextset()`
+before Psycopg 3.3)::
 
     >>> cur_pg3.execute("SELECT 1; SELECT 2")
-    >>> cur_pg3.fetchone()
+    >>> for _ in cur_pg3.results():
+    ...    print(cur_pg3.fetchone())
     (1,)
-
-    >>> cur_pg3.nextset()
-    True
-    >>> cur_pg3.fetchone()
     (2,)
 
-    >>> cur_pg3.nextset()
-    None  # no more results
-
 Remember though that you cannot use server-side bindings to :ref:`execute more
 than one statement in the same query <multi-statements>`, if you are passing
 parameters to the query.