docs: document Cursor.results() and add rease note

diff --git a/docs/api/cursors.rst b/docs/api/cursors.rst
index 826b568f0c9b75aae5d8fed75743479f022892ba..bcf03a8943260f1376f42ed0a9aa5c0bfe5cc64b 100644 (file)
--- a/docs/api/cursors.rst
+++ b/docs/api/cursors.rst
@@ -122,17 +122,13 @@ The `!Cursor` class
             using a pattern such as::
 
                 cur.executemany(query, records)
-                ids = []
-                while True:
-                    ids.append(cur.fetchone()[0])
-                    if not cur.nextset():
-                        break
+                ids = [cur.fetchone()[0] for _ in cur.results()]
 
         .. warning::
 
             More explicitly, `!fetchall()` alone will not return all the
             values returned! You must iterate on the results using
-            `!nextset()`.
+            `!results()`.
 
         If `!returning=False`, the value of `rowcount` is set to the cumulated
         number of rows affected by queries. If `!returning=True`, `!rowcount`
@@ -266,6 +262,26 @@ The `!Cursor` class
     .. automethod:: fetchmany
     .. automethod:: fetchall
     .. automethod:: nextset
+    .. automethod:: results
+
+        The iterator yields the cursor itself upon iteration, but the cursor
+        state changes, in a way equivalent to calling `nextset()` in a loop.
+        Therefore you can ignore the result of the iteration if you are consuming
+        `!results()` in a loop::
+
+                for _ in cursor.results():
+                    for row in cursor:
+                        ...
+
+        or make use of it for example using `map()` to consume the iterator::
+
+                def cursor_consumer(cur: Cursor) -> Any:
+                    ...
+
+                map(cursor_consumer, cursor.results())
+
+        .. versionadded:: 3.3
+
     .. automethod:: scroll
 
     .. attribute:: pgresult
@@ -538,6 +554,7 @@ semantic with an `!async` interface. The main interface is described in
     .. automethod:: fetchone
     .. automethod:: fetchmany
     .. automethod:: fetchall
+    .. automethod:: results
     .. automethod:: scroll
 
     .. note::

diff --git a/docs/news.rst b/docs/news.rst
index 121d3b9edc25acadc5b47a24741ab76d91c08436..ea4e65df982e3bdcdea238234ad87a454db1510e 100644 (file)
--- a/docs/news.rst
+++ b/docs/news.rst
@@ -16,6 +16,9 @@ Psycopg 3.3.0 (unreleased)
 - Cursors are now iterators, not only iterables. This means you can call
   ``next(cur)`` to fetch the next row (:ticket:`#1064`).
 - Drop support for Python 3.8 (:ticket:`#976`) and 3.9 (:ticket:`#1056`).
+- Add `Cursor.results()` to iterate over the result sets of the queries
+  executed though `~Cursor.executemany()` or `~Cursor.execute()`
+  (:ticket:`#1080`).
 
 
 Psycopg 3.2.10 (unreleased)