From: Gord Thompson <gord@gordthompson.com>
Date: Wed, 31 Jan 2024 20:43:46 +0000 (-0700)
Subject: Update docs references to .execute() with string literal
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4bf76624a076964f9d3eed2bdecc68e3956c9d4c;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Update docs references to .execute() with string literal

.execute("… → .execute(text("…

Change-Id: Icc8f2db9cf3e148812d549f08326a0f2eb8cbfe3
---

diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst
index 1de53fdc85..597d317f07 100644
--- a/doc/build/core/connections.rst
+++ b/doc/build/core/connections.rst
@@ -140,15 +140,15 @@ each time the transaction is ended, and a new statement is
 emitted, a new transaction begins implicitly::
 
     with engine.connect() as connection:
-        connection.execute("<some statement>")
+        connection.execute(text("<some statement>"))
         connection.commit()  # commits "some statement"
 
         # new transaction starts
-        connection.execute("<some other statement>")
+        connection.execute(text("<some other statement>"))
         connection.rollback()  # rolls back "some other statement"
 
         # new transaction starts
-        connection.execute("<a third statement>")
+        connection.execute(text("<a third statement>"))
         connection.commit()  # commits "a third statement"
 
 .. versionadded:: 2.0 "commit as you go" style is a new feature of
@@ -321,7 +321,7 @@ begin a transaction::
         isolation_level="REPEATABLE READ"
     ) as connection:
         with connection.begin():
-            connection.execute("<statement>")
+            connection.execute(text("<statement>"))
 
 .. tip::  The return value of
    the :meth:`_engine.Connection.execution_options` method is the same
@@ -443,8 +443,8 @@ If we wanted to check out a :class:`_engine.Connection` object and use it
 
     with engine.connect() as connection:
         connection.execution_options(isolation_level="AUTOCOMMIT")
-        connection.execute("<statement>")
-        connection.execute("<statement>")
+        connection.execute(text("<statement>"))
+        connection.execute(text("<statement>"))
 
 Above illustrates normal usage of "DBAPI autocommit" mode.   There is no
 need to make use of methods such as :meth:`_engine.Connection.begin`
@@ -472,8 +472,8 @@ In the example below, statements remain
 
         # this begin() does not affect the DBAPI connection, isolation stays at AUTOCOMMIT
         with connection.begin() as trans:
-            connection.execute("<statement>")
-            connection.execute("<statement>")
+            connection.execute(text("<statement>"))
+            connection.execute(text("<statement>"))
 
 When we run a block like the above with logging turned on, the logging
 will attempt to indicate that while a DBAPI level ``.commit()`` is called,
@@ -496,11 +496,11 @@ called after autobegin has already occurred::
         connection = connection.execution_options(isolation_level="AUTOCOMMIT")
 
         # "transaction" is autobegin (but has no effect due to autocommit)
-        connection.execute("<statement>")
+        connection.execute(text("<statement>"))
 
         # this will raise; "transaction" is already begun
         with connection.begin() as trans:
-            connection.execute("<statement>")
+            connection.execute(text("<statement>"))
 
 The above example also demonstrates the same theme that the "autocommit"
 isolation level is a configurational detail of the underlying database
@@ -545,7 +545,7 @@ before we call upon :meth:`_engine.Connection.begin`::
         connection.execution_options(isolation_level="AUTOCOMMIT")
 
         # run statement(s) in autocommit mode
-        connection.execute("<statement>")
+        connection.execute(text("<statement>"))
 
         # "commit" the autobegun "transaction"
         connection.commit()
@@ -555,7 +555,7 @@ before we call upon :meth:`_engine.Connection.begin`::
 
         # use a begin block
         with connection.begin() as trans:
-            connection.execute("<statement>")
+            connection.execute(text("<statement>"))
 
 Above, to manually revert the isolation level we made use of
 :attr:`_engine.Connection.default_isolation_level` to restore the default
@@ -568,11 +568,11 @@ use two blocks ::
     # use an autocommit block
     with engine.connect().execution_options(isolation_level="AUTOCOMMIT") as connection:
         # run statement in autocommit mode
-        connection.execute("<statement>")
+        connection.execute(text("<statement>"))
 
     # use a regular block
     with engine.begin() as connection:
-        connection.execute("<statement>")
+        connection.execute(text("<statement>"))
 
 To sum up:
 
diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst
index 3397a65e83..b058fc5b25 100644
--- a/doc/build/core/engines.rst
+++ b/doc/build/core/engines.rst
@@ -616,7 +616,7 @@ tokens::
     >>> from sqlalchemy import create_engine
     >>> e = create_engine("sqlite://", echo="debug")
     >>> with e.connect().execution_options(logging_token="track1") as conn:
-    ...     conn.execute("select 1").all()
+    ...     conn.execute(text("select 1")).all()
     2021-02-03 11:48:45,754 INFO sqlalchemy.engine.Engine [track1] select 1
     2021-02-03 11:48:45,754 INFO sqlalchemy.engine.Engine [track1] [raw sql] ()
     2021-02-03 11:48:45,754 DEBUG sqlalchemy.engine.Engine [track1] Col ('1',)
@@ -633,14 +633,14 @@ of an application without creating new engines::
     >>> e1 = e.execution_options(logging_token="track1")
     >>> e2 = e.execution_options(logging_token="track2")
     >>> with e1.connect() as conn:
-    ...     conn.execute("select 1").all()
+    ...     conn.execute(text("select 1")).all()
     2021-02-03 11:51:08,960 INFO sqlalchemy.engine.Engine [track1] select 1
     2021-02-03 11:51:08,960 INFO sqlalchemy.engine.Engine [track1] [raw sql] ()
     2021-02-03 11:51:08,960 DEBUG sqlalchemy.engine.Engine [track1] Col ('1',)
     2021-02-03 11:51:08,961 DEBUG sqlalchemy.engine.Engine [track1] Row (1,)
 
     >>> with e2.connect() as conn:
-    ...     conn.execute("select 2").all()
+    ...     conn.execute(text("select 2")).all()
     2021-02-03 11:52:05,518 INFO sqlalchemy.engine.Engine [track2] Select 1
     2021-02-03 11:52:05,519 INFO sqlalchemy.engine.Engine [track2] [raw sql] ()
     2021-02-03 11:52:05,520 DEBUG sqlalchemy.engine.Engine [track2] Col ('1',)
diff --git a/doc/build/core/reflection.rst b/doc/build/core/reflection.rst
index 4f3805b7ed..043f6f8ee7 100644
--- a/doc/build/core/reflection.rst
+++ b/doc/build/core/reflection.rst
@@ -123,8 +123,9 @@ object's dictionary of tables::
 
     metadata_obj = MetaData()
     metadata_obj.reflect(bind=someengine)
-    for table in reversed(metadata_obj.sorted_tables):
-        someengine.execute(table.delete())
+    with someengine.begin() as conn:
+        for table in reversed(metadata_obj.sorted_tables):
+            conn.execute(table.delete())
 
 .. _metadata_reflection_schemas:
 
diff --git a/doc/build/orm/persistence_techniques.rst b/doc/build/orm/persistence_techniques.rst
index 69fad33b22..a4cddd5276 100644
--- a/doc/build/orm/persistence_techniques.rst
+++ b/doc/build/orm/persistence_techniques.rst
@@ -90,7 +90,7 @@ This is most easily accomplished using the
     session = Session()
 
     # execute a string statement
-    result = session.execute("select * from table where id=:id", {"id": 7})
+    result = session.execute(text("select * from table where id=:id"), {"id": 7})
 
     # execute a SQL expression construct
     result = session.execute(select(mytable).where(mytable.c.id == 7))
diff --git a/doc/build/orm/session_transaction.rst b/doc/build/orm/session_transaction.rst
index 10da76eda8..55ade3e532 100644
--- a/doc/build/orm/session_transaction.rst
+++ b/doc/build/orm/session_transaction.rst
@@ -60,7 +60,7 @@ or rolled back::
     session.commit()  # commits
 
     # will automatically begin again
-    result = session.execute("< some select statement >")
+    result = session.execute(text("< some select statement >"))
     session.add_all([more_objects, ...])
     session.commit()  # commits
 
@@ -100,7 +100,7 @@ first::
 
         session.commit()  # commits
 
-        result = session.execute("<some SELECT statement>")
+        result = session.execute(text("<some SELECT statement>"))
 
     # remaining transactional state from the .execute() call is
     # discarded
@@ -529,8 +529,8 @@ used in a read-only fashion**, that is::
 
 
     with autocommit_session() as session:
-        some_objects = session.execute("<statement>")
-        some_other_objects = session.execute("<statement>")
+        some_objects = session.execute(text("<statement>"))
+        some_other_objects = session.execute(text("<statement>"))
 
     # closes connection
 
diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index 0dbb62c167..e4126f4105 100644
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -1939,7 +1939,7 @@ class SessionEvents(event.Events[Session]):
             @event.listens_for(Session, "after_soft_rollback")
             def do_something(session, previous_transaction):
                 if session.is_active:
-                    session.execute("select * from some_table")
+                    session.execute(text("select * from some_table"))
 
         :param session: The target :class:`.Session`.
         :param previous_transaction: The :class:`.SessionTransaction`