From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sat, 17 Sep 2022 14:18:56 +0000 (-0400)
Subject: remove obtuse section about "bundled bind parameters"
X-Git-Tag: rel_2_0_0b1~57
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f0bcd57f9ed76ba8d871448d821a85089f490b6c;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

remove obtuse section about "bundled bind parameters"

Just looking for basics on insert in the first pages
of the tutorial I see this weird detour into something that
nobody ever uses and definitely isn't going to make sense
to the people I see complaining about our docs on twitter,
remove this.   the tutorial probably needs a big sweep
for wordy obtuse things.  the userbase is changing and
we really have a lot of brand-new-to-programming types coming
in.

Change-Id: I3bb11f0399e55edbb8f874e7eb63c40616b04e8b
---

diff --git a/doc/build/tutorial/dbapi_transactions.rst b/doc/build/tutorial/dbapi_transactions.rst
index 545a0d1291..6914104eed 100644
--- a/doc/build/tutorial/dbapi_transactions.rst
+++ b/doc/build/tutorial/dbapi_transactions.rst
@@ -398,48 +398,6 @@ for this use case.
    however again when using the ORM, there is a different technique
    generally used for updating or deleting many individual rows separately.
 
-.. rst-class:: orm-addin
-
-.. _tutorial_bundling_parameters:
-
-Bundling Parameters with a Statement
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The two previous cases illustrate a series of parameters being passed to
-accompany a SQL statement.    For single-parameter statement executions,
-SQLAlchemy's use of parameters is in fact more often than not done by
-**bundling** the parameters with the statement itself, which is a primary
-feature of the SQL Expression Language and makes for queries that can be
-composed naturally while still making use of parameterization in all cases.
-This concept will be discussed in much more detail in the sections that follow;
-for a brief preview, the :func:`_sql.text` construct itself being part of the
-SQL Expression Language supports this feature by using the
-:meth:`_sql.TextClause.bindparams` method; this is a :term:`generative` method that
-returns a new copy of the SQL construct with additional state added, in this
-case the parameter values we want to pass along:
-
-
-.. sourcecode:: pycon+sql
-
-    >>> stmt = text("SELECT x, y FROM some_table WHERE y > :y ORDER BY x, y").bindparams(y=6)
-    >>> with engine.connect() as conn:
-    ...     result = conn.execute(stmt)
-    ...     for row in result:
-    ...        print(f"x: {row.x}  y: {row.y}")
-    {opensql}BEGIN (implicit)
-    SELECT x, y FROM some_table WHERE y > ? ORDER BY x, y
-    [...] (6,)
-    {stop}x: 6  y: 8
-    x: 9  y: 10
-    x: 11  y: 12
-    x: 13  y: 14
-    {opensql}ROLLBACK{stop}
-
-
-The interesting thing to note above is that even though we passed only a single
-argument, ``stmt``, to the :meth:`_future.Connection.execute` method, the
-execution of the statement illustrated both the SQL string as well as the
-separate parameter tuple.
 
 .. rst-class:: orm-addin
 
@@ -474,9 +432,9 @@ a context manager:
 
     >>> from sqlalchemy.orm import Session
 
-    >>> stmt = text("SELECT x, y FROM some_table WHERE y > :y ORDER BY x, y").bindparams(y=6)
+    >>> stmt = text("SELECT x, y FROM some_table WHERE y > :y ORDER BY x, y")
     >>> with Session(engine) as session:
-    ...     result = session.execute(stmt)
+    ...     result = session.execute(stmt, {"y": 6})
     ...     for row in result:
     ...        print(f"x: {row.x}  y: {row.y}")
     {opensql}BEGIN (implicit)
@@ -489,7 +447,7 @@ a context manager:
     {opensql}ROLLBACK{stop}
 
 The example above can be compared to the example in the preceding section
-in :ref:`tutorial_bundling_parameters` - we directly replace the call to
+in :ref:`tutorial_sending_parameters` - we directly replace the call to
 ``with engine.connect() as conn`` with ``with Session(engine) as session``,
 and then make use of the :meth:`_orm.Session.execute` method just like we
 do with the :meth:`_future.Connection.execute` method.