From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Tue, 8 Dec 2020 08:55:41 +0000 (+0100)
Subject: Added `conection.execute()` method
X-Git-Tag: 3.0.dev0~275
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2547f0a570bb173372644cce058dedf7fc16b4d8;p=thirdparty%2Fpsycopg.git

Added `conection.execute()` method
---

diff --git a/docs/connection.rst b/docs/connection.rst
index b05df06a2..ba95df4f8 100644
--- a/docs/connection.rst
+++ b/docs/connection.rst
@@ -61,6 +61,15 @@ The `!Connection` class
         .. note:: You can use :ref:`with conn.cursor(): ...<usage>`
             to close the cursor automatically when the block is exited.
 
+    .. automethod:: execute(query: Query, params: Optional[Args]=None) -> Cursor
+
+        :param query: The query to execute
+        :type query: `!str`, `!bytes`, or `sql.Composable`
+        :param params: The parameters to pass to the query, if any
+        :type params: Sequence or Mapping
+
+        The cursor is what returned calling `cursor()` without parameters. See
+        :ref:`query-parameters` for all the details about executing queries.
 
     .. rubric:: Transaction management methods
 
@@ -142,6 +151,7 @@ The `!AsyncConnection` class
             automatically when the block is exited, but be careful about
             the async quirkness: see :ref:`async-with` for details.
 
+    .. automethod:: execute(query: Query, params: Optional[Args]=None) -> AsyncCursor
     .. automethod:: commit
     .. automethod:: rollback
 
diff --git a/psycopg3/psycopg3/connection.py b/psycopg3/psycopg3/connection.py
index 7d8adde0c..d801a2238 100644
--- a/psycopg3/psycopg3/connection.py
+++ b/psycopg3/psycopg3/connection.py
@@ -26,7 +26,7 @@ from . import errors as e
 from . import encodings
 from .pq import TransactionStatus, ExecStatus, Format
 from .sql import Composable
-from .proto import DumpersMap, LoadersMap, PQGen, PQGenConn, RV, Query
+from .proto import DumpersMap, LoadersMap, PQGen, PQGenConn, RV, Query, Params
 from .waiting import wait, wait_async
 from .conninfo import make_conninfo
 from .generators import notifies
@@ -294,6 +294,13 @@ class Connection(BaseConnection):
 
         self._exec_command(b"begin")
 
+    def execute(
+        self, query: Query, params: Optional[Params] = None
+    ) -> "Cursor":
+        """Execute a query and return a cursor to read its results."""
+        cur = self.cursor()
+        return cur.execute(query, params)
+
     def commit(self) -> None:
         """Commit any pending transaction to the database."""
         with self.lock:
@@ -463,6 +470,12 @@ class AsyncConnection(BaseConnection):
 
         await self._exec_command(b"begin")
 
+    async def execute(
+        self, query: Query, params: Optional[Params] = None
+    ) -> "AsyncCursor":
+        cur = await self.cursor()
+        return await cur.execute(query, params)
+
     async def commit(self) -> None:
         async with self.lock:
             if self._savepoints:
diff --git a/tests/test_connection.py b/tests/test_connection.py
index 867b3ce34..af938857e 100644
--- a/tests/test_connection.py
+++ b/tests/test_connection.py
@@ -427,3 +427,14 @@ def test_notify_handlers(conn):
 
     with pytest.raises(ValueError):
         conn.remove_notify_handler(cb1)
+
+
+def test_execute(conn):
+    cur = conn.execute("select %s, %s", [10, 20])
+    assert cur.fetchone() == (10, 20)
+
+    cur = conn.execute("select %(a)s, %(b)s", {"a": 11, "b": 21})
+    assert cur.fetchone() == (11, 21)
+
+    cur = conn.execute("select 12, 22")
+    assert cur.fetchone() == (12, 22)
diff --git a/tests/test_connection_async.py b/tests/test_connection_async.py
index b21d77179..de1879e9c 100644
--- a/tests/test_connection_async.py
+++ b/tests/test_connection_async.py
@@ -445,3 +445,14 @@ async def test_notify_handlers(aconn):
 
     with pytest.raises(ValueError):
         aconn.remove_notify_handler(cb1)
+
+
+async def test_execute(aconn):
+    cur = await aconn.execute("select %s, %s", [10, 20])
+    assert await cur.fetchone() == (10, 20)
+
+    cur = await aconn.execute("select %(a)s, %(b)s", {"a": 11, "b": 21})
+    assert await cur.fetchone() == (11, 21)
+
+    cur = await aconn.execute("select 12, 22")
+    assert await cur.fetchone() == (12, 22)