hold renamed to withhold for server side cursors

diff --git a/docs/api/connections.rst b/docs/api/connections.rst
index c30f10350c668e782cc8a3055feab3f57cd3b659..c257a7b849dbbde037eac7cdbc27c68151ed3be0 100644 (file)
--- a/docs/api/connections.rst
+++ b/docs/api/connections.rst
@@ -78,6 +78,10 @@ The `!Connection` class
                        loader. See :ref:`binary-data` for details.
         :param row_factory: If specified override the `row_factory` set on the
                             connection. See :ref:`row-factories` for details.
+        :param scrollable: Specify the `~ServerCursor.scrollable` property of
+                           the server-side cursor created.
+        :param withhold: Specify the `~ServerCursor.withhold` property of
+                         the server-side cursor created.
         :return: A cursor of the class specified by `cursor_factory` (or
                  `server_cursor_factory` if *name* is specified).
 

diff --git a/docs/api/cursors.rst b/docs/api/cursors.rst
index 990c62e3eecf7c72f270b4a50bf3f24ac06dabfe..8221bf2f894f79da51c2ba1abae5fcb4c9c80f5e 100644 (file)
--- a/docs/api/cursors.rst
+++ b/docs/api/cursors.rst
@@ -196,7 +196,7 @@ The `!ServerCursor` class
             ...` pattern is especially useful so that the cursor is closed at
             the end of the block.
 
-    .. automethod:: execute(query, params=None, *, scrollable=None, hold=False) -> ServerCursor
+    .. automethod:: execute(query, params=None, *, scrollable=None, withhold=False) -> ServerCursor
 
         :param query: The query to execute.
         :type query: `!str`, `!bytes`, or `sql.Composable`
@@ -205,9 +205,9 @@ The `!ServerCursor` class
         :param scrollable: if `!True` make the cursor scrollable, if `!False`
                            not. if `!None` leave the choice to the server.
         :type scrollable: `!Optional[bool]`
-        :param hold: if `!True` allow the cursor to be used after the
-                     transaction creating it has committed.
-        :type hold: `!bool`
+        :param withhold: if `!True` allow the cursor to be used after the
+                         transaction creating it has committed.
+        :type withhold: `!bool`
 
         Create a server cursor with given `name` and the *query* in argument.
         If using :sql:`DECLARE` is not appropriate you can avoid to use
@@ -314,7 +314,7 @@ The `!AsyncServerCursor` class
         .. note:: You can close the cursor automatically using :samp:`async
             with conn.cursor({name}): ...`
 
-    .. automethod:: execute(query, params=None, *, scrollable=None, hold=False) -> AsyncServerCursor
+    .. automethod:: execute(query, params=None, *, scrollable=None, withhold=False) -> AsyncServerCursor
     .. automethod:: executemany(query: Query, params_seq: Sequence[Args])
     .. automethod:: fetchone
     .. automethod:: fetchmany

diff --git a/psycopg/psycopg/server_cursor.py b/psycopg/psycopg/server_cursor.py
index 636a8aeb097278f22a232327aab21729f217ed25..6638ec1fc85dfe3b95536b5a9e75f2f15b1bc522 100644 (file)
--- a/psycopg/psycopg/server_cursor.py
+++ b/psycopg/psycopg/server_cursor.py
@@ -144,7 +144,7 @@ class ServerCursorHelper(Generic[ConnectionType, Row]):
         cur: BaseCursor[ConnectionType, Row],
         query: Query,
         scrollable: Optional[bool],
-        hold: bool,
+        withhold: bool,
     ) -> sql.Composable:
 
         if isinstance(query, bytes):
@@ -159,7 +159,7 @@ class ServerCursorHelper(Generic[ConnectionType, Row]):
         if scrollable is not None:
             parts.append(sql.SQL("scroll" if scrollable else "no scroll"))
         parts.append(sql.SQL("cursor"))
-        if hold:
+        if withhold:
             parts.append(sql.SQL("with hold"))
         parts.append(sql.SQL("for"))
         parts.append(query)
@@ -224,13 +224,13 @@ class ServerCursor(BaseCursor["Connection[Any]", Row]):
         params: Optional[Params] = None,
         *,
         scrollable: Optional[bool] = None,
-        hold: bool = False,
+        withhold: bool = False,
     ) -> "ServerCursor[Row]":
         """
         Open a cursor to execute a query to the database.
         """
         query = self._helper._make_declare_statement(
-            self, query, scrollable=scrollable, hold=hold
+            self, query, scrollable=scrollable, withhold=withhold
         )
         with self._conn.lock:
             self._conn.wait(self._helper._declare_gen(self, query, params))
@@ -340,10 +340,10 @@ class AsyncServerCursor(BaseCursor["AsyncConnection[Any]", Row]):
         params: Optional[Params] = None,
         *,
         scrollable: Optional[bool] = None,
-        hold: bool = False,
+        withhold: bool = False,
     ) -> "AsyncServerCursor[Row]":
         query = self._helper._make_declare_statement(
-            self, query, scrollable=scrollable, hold=hold
+            self, query, scrollable=scrollable, withhold=withhold
         )
         async with self._conn.lock:
             await self._conn.wait(

diff --git a/tests/test_server_cursor.py b/tests/test_server_cursor.py
index 9f008e7b48b4830ca55f7fe618536a80788e9473..50fa3b4249e39f1243b814f9984f70ef99467702 100644 (file)
--- a/tests/test_server_cursor.py
+++ b/tests/test_server_cursor.py
@@ -284,7 +284,7 @@ def test_non_scrollable(conn):
         curs.scroll(-1)
 
 
-@pytest.mark.parametrize("kwargs", [{}, {"hold": False}])
+@pytest.mark.parametrize("kwargs", [{}, {"withhold": False}])
 def test_no_hold(conn, kwargs):
     with pytest.raises(e.InvalidCursorName):
         with conn.cursor("foo") as curs:
@@ -296,7 +296,7 @@ def test_no_hold(conn, kwargs):
 
 def test_hold(conn):
     with conn.cursor("foo") as curs:
-        curs.execute("select generate_series(0, 5)", hold=True)
+        curs.execute("select generate_series(0, 5)", withhold=True)
         assert curs.fetchone() == (0,)
         conn.commit()
         assert curs.fetchone() == (1,)

diff --git a/tests/test_server_cursor_async.py b/tests/test_server_cursor_async.py
index c3ac472ec8f8118b4628575b66d72132ca1e6148..b0e4127bccf648506537c8166931c6d702601914 100644 (file)
--- a/tests/test_server_cursor_async.py
+++ b/tests/test_server_cursor_async.py
@@ -295,7 +295,7 @@ async def test_non_scrollable(aconn):
         await curs.scroll(-1)
 
 
-@pytest.mark.parametrize("kwargs", [{}, {"hold": False}])
+@pytest.mark.parametrize("kwargs", [{}, {"withhold": False}])
 async def test_no_hold(aconn, kwargs):
     with pytest.raises(e.InvalidCursorName):
         async with aconn.cursor("foo") as curs:
@@ -307,7 +307,7 @@ async def test_no_hold(aconn, kwargs):
 
 async def test_hold(aconn):
     async with aconn.cursor("foo") as curs:
-        await curs.execute("select generate_series(0, 5)", hold=True)
+        await curs.execute("select generate_series(0, 5)", withhold=True)
         assert await curs.fetchone() == (0,)
         await aconn.commit()
         assert await curs.fetchone() == (1,)