From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Sat, 12 Jul 2025 05:03:08 +0000 (+0200)
Subject: docs: cleanup of `results()` documentation
X-Git-Url: http://git.ipfire.org/gitweb/gitweb.cgi?a=commitdiff_plain;h=336aeba5818bb9d98eb9c857c576f6daf67beb81;p=thirdparty%2Fpsycopg.git

docs: cleanup of `results()` documentation
---

diff --git a/docs/api/cursors.rst b/docs/api/cursors.rst
index bcf03a894..e63a98e18 100644
--- 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 e8d6b9112..53ac661a4 100644
--- 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.