Document and test modification of .values in before_compile_update

Change-Id: I2a694bcf24b06806dc98651015e7c7a8b090ff65

diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index 88d3122371e0640f59ec983e6e4e9224172e3948..9eb321b6b161693290e702bee4a138ec4f628c8b 100644 (file)
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -1592,11 +1592,18 @@ class SessionEvents(event.Events):
             * ``session`` - the :class:`.Session` involved
             * ``query`` -the :class:`.Query` object that this update operation
               was called upon.
+            * ``values`` The "values" dictionary that was passed to
+              :meth:`.Query.update`.
             * ``context`` The :class:`.QueryContext` object, corresponding
               to the invocation of an ORM query.
             * ``result`` the :class:`.ResultProxy` returned as a result of the
               bulk UPDATE operation.
 
+        .. seealso::
+
+            :meth:`.QueryEvents.before_compile_update`
+
+            :meth:`.SessionEvents.after_bulk_delete`
 
         """
 
@@ -1626,6 +1633,11 @@ class SessionEvents(event.Events):
             * ``result`` the :class:`.ResultProxy` returned as a result of the
               bulk DELETE operation.
 
+        .. seealso::
+
+            :meth:`.QueryEvents.before_compile_delete`
+
+            :meth:`.SessionEvents.after_bulk_update`
 
         """
 
@@ -2348,8 +2360,9 @@ class QueryEvents(event.Events):
         """Allow modifications to the :class:`.Query` object within
         :meth:`.Query.update`.
 
-        Like the :meth:`.QueryEvents.before_compile` event, this event
-        should be configured with ``retval=True``, and the modified
+        Like the :meth:`.QueryEvents.before_compile` event, if the event
+        is to be used to alter the :class:`.Query` object, it should
+        be configured with ``retval=True``, and the modified
         :class:`.Query` object returned, as in ::
 
             @event.listens_for(Query, "before_compile_update", retval=True)
@@ -2358,8 +2371,13 @@ class QueryEvents(event.Events):
                     if desc['type'] is User:
                         entity = desc['entity']
                         query = query.filter(entity.deleted == False)
+
+                        update_context.values['timestamp'] = datetime.utcnow()
                 return query
 
+        The ``.values`` dictionary of the "update context" object can also
+        be modified in place as illustrated above.
+
         :param query: a :class:`.Query` instance; this is also
          the ``.query`` attribute of the given "update context"
          object.
@@ -2367,6 +2385,10 @@ class QueryEvents(event.Events):
         :param update_context: an "update context" object which is
          the same kind of object as described in
          :paramref:`.QueryEvents.after_bulk_update.update_context`.
+         The object has a ``.values`` attribute in an UPDATE context which is
+         the dictionary of parameters passed to :meth:`.Query.update`.  This
+         dictionary can be modified to alter the VALUES clause of the
+         resulting UPDATE statement.
 
         .. versionadded:: 1.2.17
 

diff --git a/test/orm/test_events.py b/test/orm/test_events.py
index d913f3c7740563e97f8c2826206f5c17b5c59f4f..029b767e53c5b739f86d49306c4736de4489cc94 100644 (file)
--- a/test/orm/test_events.py
+++ b/test/orm/test_events.py
@@ -2460,6 +2460,10 @@ class QueryEventsTest(
                 if desc["type"] is User:
                     entity = desc["expr"]
                     query = query.filter(entity.id != 10)
+
+                    update_context.values["name"] = (
+                        update_context.values["name"] + "_modified"
+                    )
             return query
 
         User = self.classes.User
@@ -2471,7 +2475,7 @@ class QueryEventsTest(
             CompiledSQL(
                 "UPDATE users SET name=:name WHERE "
                 "users.id = :id_1 AND users.id != :id_2",
-                [{"name": "ed", "id_1": 7, "id_2": 10}],
+                [{"name": "ed_modified", "id_1": 7, "id_2": 10}],
             )
         )