Call the params params, not vars

diff --git a/docs/cursor.rst b/docs/cursor.rst
index 0aaecf1c9566d43d235c42ee4f1aa4b9bc2e5149..92d43bc481f961b9072014390357e55896ceda2e 100644 (file)
--- a/docs/cursor.rst
+++ b/docs/cursor.rst
@@ -46,12 +46,12 @@ The `!Cursor` class
 
     .. rubric:: Methods to send commands
 
-    .. automethod:: execute(query: Query, vars: Optional[Args]=None) -> Cursor
+    .. automethod:: execute(query: Query, params: Optional[Args]=None) -> Cursor
 
         :param query: The query to execute
         :type query: `!str`, `!bytes`, or `sql.Composable`
-        :param vars: The parameters to pass to the query, if any
-        :type vars: Mapping, Sequence
+        :param params: The parameters to pass to the query, if any
+        :type params: Sequence or Mapping
 
         Return the cursor itself, so that it will be possible to chain a fetch
         operation after the call.
@@ -59,12 +59,12 @@ The `!Cursor` class
         See :ref:`query-parameters` for all the details about executing
         queries.
 
-    .. automethod:: executemany(query: Query, vars_seq: Sequence[Args]) -> Cursor
+    .. automethod:: executemany(query: Query, params_seq: Sequence[Args])
 
         :param query: The query to execute
         :type query: `!str`, `!bytes`, or `sql.Composable`
-        :param vars_seq: The parameters to pass to the query
-        :type vars_seq: Sequence of Mapping or Sequence
+        :param params_seq: The parameters to pass to the query
+        :type params_seq: Sequence of Sequences or Mappings
 
         This is more efficient than performing separate queries, but in case of
         several :sql:`INSERT` (and with some SQL creativity for massive
@@ -144,8 +144,8 @@ The `!AsyncCursor` class
             automatically when the block is exited, but be careful about
             the async quirkness: see :ref:`with-statement` for details.
 
-    .. automethod:: execute(query: Query, vars: Optional[Args]=None) -> AsyncCursor
-    .. automethod:: executemany(query: Query, vars_seq: Sequence[Args]) -> AsyncCursor
+    .. automethod:: execute(query: Query, params: Optional[Args]=None) -> AsyncCursor
+    .. automethod:: executemany(query: Query, params_seq: Sequence[Args])
     .. automethod:: copy(statement: Query) -> AsyncCopy
 
         .. note:: it must be called as ``async with cur.copy() as copy: ...``

diff --git a/psycopg3/psycopg3/cursor.py b/psycopg3/psycopg3/cursor.py
index 9ab116234517af87b3fa2e42b04e29e15760b960..3a713edd4edbe84a3f8a4c5a51e8ae8b4be07d61 100644 (file)
--- a/psycopg3/psycopg3/cursor.py
+++ b/psycopg3/psycopg3/cursor.py
@@ -284,13 +284,13 @@ class BaseCursor(Generic[ConnectionType]):
         self._transformer = adapt.Transformer(self)
 
     def _execute_send(
-        self, query: Query, vars: Optional[Params], no_pqexec: bool = False
+        self, query: Query, params: Optional[Params], no_pqexec: bool = False
     ) -> None:
         """
         Implement part of execute() before waiting common to sync and async
         """
         pgq = PostgresQuery(self._transformer)
-        pgq.convert(query, vars)
+        pgq.convert(query, params)
 
         if pgq.params or no_pqexec or self.format == pq.Format.BINARY:
             self._query = pgq.query
@@ -347,13 +347,13 @@ class BaseCursor(Generic[ConnectionType]):
             )
 
     def _send_prepare(
-        self, name: bytes, query: Query, vars: Optional[Params]
+        self, name: bytes, query: Query, params: Optional[Params]
     ) -> PostgresQuery:
         """
         Implement part of execute() before waiting common to sync and async
         """
         pgq = PostgresQuery(self._transformer)
-        pgq.convert(query, vars)
+        pgq.convert(query, params)
 
         self._query = pgq.query
         self._conn.pgconn.send_prepare(name, pgq.query, param_types=pgq.types)
@@ -421,22 +421,22 @@ class Cursor(BaseCursor["Connection"]):
         self._closed = True
         self._reset()
 
-    def execute(self, query: Query, vars: Optional[Params] = None) -> "Cursor":
+    def execute(
+        self, query: Query, params: Optional[Params] = None
+    ) -> "Cursor":
         """
         Execute a query or command to the database.
         """
         with self._conn.lock:
             self._start_query()
             self._conn._start_query()
-            self._execute_send(query, vars)
+            self._execute_send(query, params)
             gen = execute(self._conn.pgconn)
             results = self._conn.wait(gen)
             self._execute_results(results)
         return self
 
-    def executemany(
-        self, query: Query, vars_seq: Sequence[Params]
-    ) -> "Cursor":
+    def executemany(self, query: Query, params_seq: Sequence[Params]) -> None:
         """
         Execute the same command with a sequence of input data.
         """
@@ -444,9 +444,9 @@ class Cursor(BaseCursor["Connection"]):
             self._start_query()
             self._conn._start_query()
             first = True
-            for vars in vars_seq:
+            for params in params_seq:
                 if first:
-                    pgq = self._send_prepare(b"", query, vars)
+                    pgq = self._send_prepare(b"", query, params)
                     gen = execute(self._conn.pgconn)
                     (result,) = self._conn.wait(gen)
                     if result.status == self.ExecStatus.FATAL_ERROR:
@@ -454,15 +454,13 @@ class Cursor(BaseCursor["Connection"]):
                             result, encoding=self._conn.client_encoding
                         )
                 else:
-                    pgq.dump(vars)
+                    pgq.dump(params)
 
                 self._send_query_prepared(b"", pgq)
                 gen = execute(self._conn.pgconn)
                 (result,) = self._conn.wait(gen)
                 self._execute_results((result,))
 
-        return self
-
     def fetchone(self) -> Optional[Sequence[Any]]:
         """
         Return the next record from the current recordset.
@@ -557,27 +555,27 @@ class AsyncCursor(BaseCursor["AsyncConnection"]):
         self._reset()
 
     async def execute(
-        self, query: Query, vars: Optional[Params] = None
+        self, query: Query, params: Optional[Params] = None
     ) -> "AsyncCursor":
         async with self._conn.lock:
             self._start_query()
             await self._conn._start_query()
-            self._execute_send(query, vars)
+            self._execute_send(query, params)
             gen = execute(self._conn.pgconn)
             results = await self._conn.wait(gen)
             self._execute_results(results)
         return self
 
     async def executemany(
-        self, query: Query, vars_seq: Sequence[Params]
-    ) -> "AsyncCursor":
+        self, query: Query, params_seq: Sequence[Params]
+    ) -> None:
         async with self._conn.lock:
             self._start_query()
             await self._conn._start_query()
             first = True
-            for vars in vars_seq:
+            for params in params_seq:
                 if first:
-                    pgq = self._send_prepare(b"", query, vars)
+                    pgq = self._send_prepare(b"", query, params)
                     gen = execute(self._conn.pgconn)
                     (result,) = await self._conn.wait(gen)
                     if result.status == self.ExecStatus.FATAL_ERROR:
@@ -585,15 +583,13 @@ class AsyncCursor(BaseCursor["AsyncConnection"]):
                             result, encoding=self._conn.client_encoding
                         )
                 else:
-                    pgq.dump(vars)
+                    pgq.dump(params)
 
                 self._send_query_prepared(b"", pgq)
                 gen = execute(self._conn.pgconn)
                 (result,) = await self._conn.wait(gen)
                 self._execute_results((result,))
 
-        return self
-
     async def fetchone(self) -> Optional[Sequence[Any]]:
         self._check_result()
         rv = self._transformer.load_row(self._pos)