- 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 b4f185ac281f86bdf8b6477b0c26f7e24f206641..cc2a976253867162db80fb6ae2795bc8c43eb4a3 100644 (file)
--- a/doc/build/core/tutorial.rst
+++ b/doc/build/core/tutorial.rst
@@ -364,6 +364,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
@@ -1754,7 +1758,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 a2a5646908237a15162b6db2b63b0ceff03ae1f2..6756f1554598fd721bdeb87793bd48f5d964f55d 100644 (file)
--- a/lib/sqlalchemy/sql/dml.py
+++ b/lib/sqlalchemy/sql/dml.py
@@ -262,10 +262,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.