From: Federico Caselli <cfederico87@gmail.com>
Date: Mon, 11 Mar 2024 20:58:46 +0000 (+0100)
Subject: fix usage of kwargs to execute in docs
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=af4df5e2a2405cfef3aa26bbb8f48e24d954a370;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

fix usage of kwargs to execute in docs

Change-Id: I033cba49ba6c12113643b88e48c5917f2b70a307
---

diff --git a/doc/build/core/custom_types.rst b/doc/build/core/custom_types.rst
index b9d8953b4e..f9c0205249 100644
--- a/doc/build/core/custom_types.rst
+++ b/doc/build/core/custom_types.rst
@@ -527,7 +527,10 @@ transparently::
     with engine.begin() as conn:
         metadata_obj.create_all(conn)
 
-        conn.execute(message.insert(), username="some user", message="this is my message")
+        conn.execute(
+            message.insert(),
+            {"username": "some user", "message": "this is my message"},
+        )
 
         print(
             conn.scalar(select(message.c.message).where(message.c.username == "some user"))
diff --git a/doc/build/errors.rst b/doc/build/errors.rst
index d664512315..4c12e0fb17 100644
--- a/doc/build/errors.rst
+++ b/doc/build/errors.rst
@@ -572,7 +572,7 @@ is executed::
 Above, no value has been provided for the parameter "my_param".  The correct
 approach is to provide a value::
 
-    result = conn.execute(stmt, my_param=12)
+    result = conn.execute(stmt, {"my_param": 12})
 
 When the message takes the form "a value is required for bind parameter <x>
 in parameter group <y>", the message is referring to the "executemany" style
diff --git a/lib/sqlalchemy/dialects/postgresql/json.py b/lib/sqlalchemy/dialects/postgresql/json.py
index dff12e7f49..3790fa359b 100644
--- a/lib/sqlalchemy/dialects/postgresql/json.py
+++ b/lib/sqlalchemy/dialects/postgresql/json.py
@@ -155,7 +155,7 @@ class JSON(sqltypes.JSON):
          be used to persist a NULL value::
 
              from sqlalchemy import null
-             conn.execute(table.insert(), data=null())
+             conn.execute(table.insert(), {"data": null()})
 
          .. seealso::
 
diff --git a/lib/sqlalchemy/sql/_elements_constructors.py b/lib/sqlalchemy/sql/_elements_constructors.py
index 27bac59e12..77cc2a8021 100644
--- a/lib/sqlalchemy/sql/_elements_constructors.py
+++ b/lib/sqlalchemy/sql/_elements_constructors.py
@@ -493,8 +493,9 @@ def bindparam(
 
         from sqlalchemy import bindparam
 
-        stmt = select(users_table).\
-                    where(users_table.c.name == bindparam('username'))
+        stmt = select(users_table).where(
+            users_table.c.name == bindparam("username")
+        )
 
     The above statement, when rendered, will produce SQL similar to::
 
@@ -504,22 +505,25 @@ def bindparam(
     would typically be applied at execution time to a method
     like :meth:`_engine.Connection.execute`::
 
-        result = connection.execute(stmt, username='wendy')
+        result = connection.execute(stmt, {"username": "wendy"})
 
     Explicit use of :func:`.bindparam` is also common when producing
     UPDATE or DELETE statements that are to be invoked multiple times,
     where the WHERE criterion of the statement is to change on each
     invocation, such as::
 
-        stmt = (users_table.update().
-                where(user_table.c.name == bindparam('username')).
-                values(fullname=bindparam('fullname'))
-                )
+        stmt = (
+            users_table.update()
+            .where(user_table.c.name == bindparam("username"))
+            .values(fullname=bindparam("fullname"))
+        )
 
         connection.execute(
-            stmt, [{"username": "wendy", "fullname": "Wendy Smith"},
-                   {"username": "jack", "fullname": "Jack Jones"},
-                   ]
+            stmt,
+            [
+                {"username": "wendy", "fullname": "Wendy Smith"},
+                {"username": "jack", "fullname": "Jack Jones"},
+            ],
         )
 
     SQLAlchemy's Core expression system makes wide use of
@@ -568,7 +572,7 @@ def bindparam(
     bound placeholders based on the arguments passed, as in::
 
         stmt = users_table.insert()
-        result = connection.execute(stmt, name='Wendy')
+        result = connection.execute(stmt, {"name": "Wendy"})
 
     The above will produce SQL output as::
 
@@ -1589,7 +1593,7 @@ def text(text: str) -> TextClause:
     E.g.::
 
         t = text("SELECT * FROM users WHERE id=:user_id")
-        result = connection.execute(t, user_id=12)
+        result = connection.execute(t, {"user_id": 12})
 
     For SQL statements where a colon is required verbatim, as within
     an inline string, use a backslash to escape::
@@ -1619,7 +1623,7 @@ def text(text: str) -> TextClause:
     such as for the WHERE clause of a SELECT statement::
 
         s = select(users.c.id, users.c.name).where(text("id=:user_id"))
-        result = connection.execute(s, user_id=12)
+        result = connection.execute(s, {"user_id": 12})
 
     :func:`_expression.text` is also used for the construction
     of a full, standalone statement using plain text.
diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py
index 98f45d9dbf..271647829f 100644
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -1915,8 +1915,9 @@ class BindParameter(roles.InElementRole, KeyedColumnElement[_T]):
 
         from sqlalchemy import bindparam
 
-        stmt = select(users_table).\
-                    where(users_table.c.name == bindparam('username'))
+        stmt = select(users_table).where(
+            users_table.c.name == bindparam("username")
+        )
 
     Detailed discussion of how :class:`.BindParameter` is used is
     at :func:`.bindparam`.