- try to note under insert.values(), if you need

"multiple parameter sets" there is a much more common case
which works equally well for INSERT/UPDATE/DELETE e.g.
executemany().   reference #3476

diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst
index 8b9bca562b816f376f76fdc32777810dc8015b1b..f3cffbba1f21c40625869a144c8d193b73541370 100644 (file)
--- a/doc/build/core/tutorial.rst
+++ b/doc/build/core/tutorial.rst
@@ -362,6 +362,10 @@ statement is compiled against the **first** dictionary in the list, and it's
 assumed that all subsequent argument dictionaries are compatible with that
 statement.
 
+The "executemany" style of invocation is available for each of the
+:func:`.insert`, :func:`.update` and :func:`.delete` constructs.
+
+
 .. _coretutorial_selecting:
 
 Selecting
@@ -1747,7 +1751,7 @@ that can be specified:
     COMMIT
     {stop}<sqlalchemy.engine.result.ResultProxy object at 0x...>
 
-When using :meth:`~.TableClause.update` in an "execute many" context,
+When using :meth:`~.TableClause.update` in an "executemany" context,
 we may wish to also use explicitly named bound parameters in the
 WHERE clause.  Again, :func:`~.expression.bindparam` is the construct
 used to achieve this:

diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py
index 319534703356832f5104c72240f00831507d4817..f9e734b6327e29e30fae5444dfc37b635f80fbaa 100644 (file)
--- a/lib/sqlalchemy/sql/dml.py
+++ b/lib/sqlalchemy/sql/dml.py
@@ -261,10 +261,14 @@ class ValuesBase(UpdateBase):
              has the effect of using the DBAPI
              `executemany() <http://www.python.org/dev/peps/pep-0249/#id18>`_
              method, which provides a high-performance system of invoking
-             a single-row INSERT statement many times against a series
+             a single-row INSERT or single-criteria UPDATE or DELETE statement
+             many times against a series
              of parameter sets.   The "executemany" style is supported by
-             all database backends, as it does not depend on a special SQL
-             syntax.
+             all database backends, and works equally well for INSERT,
+             UPDATE, and DELETE, as it does not depend on a special SQL
+             syntax.  See :ref:`execute_multiple` for an introduction to
+             the traditional Core method of multiple parameter set invocation
+             using this system.
 
          .. versionadded:: 0.8
              Support for multiple-VALUES INSERT statements.