Add AttributeEvents.modified

Added new event handler :meth:`.AttributeEvents.modified` which is
triggered when the func:`.attributes.flag_modified` function is
invoked, which is common when using the :mod:`sqlalchemy.ext.mutable`
extension module.

Change-Id: Ic152f1d5c53087d780b24ed7f1f1571527b9e8fc
Fixes: #3303

1 files changed, 25 insertions, 3 deletions

diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py
index 1ec898f8c..1d1c347b1 100644
--- a/lib/sqlalchemy/orm/events.py
+++ b/lib/sqlalchemy/orm/events.py
@@ -1877,14 +1877,18 @@ class AttributeEvents(event.Events):
             target.dispatch._active_history = True
 
         if not raw or not retval:
-            def wrap(target, value, *arg):
+            def wrap(target, *arg):
                 if not raw:
                     target = target.obj()
                 if not retval:
-                    fn(target, value, *arg)
+                    if arg:
+                        value = arg[0]
+                    else:
+                        value = None
+                    fn(target, *arg)
                     return value
                 else:
-                    return fn(target, value, *arg)
+                    return fn(target, *arg)
             event_key = event_key.with_wrapper(wrap)
 
         event_key.base_listen(propagate=propagate)
@@ -2188,6 +2192,24 @@ class AttributeEvents(event.Events):
 
         """
 
+    def modified(self, target, initiator):
+        """Receive a 'modified' event.
+
+        This event is triggered when the :func:`.attributes.flag_modified`
+        function is used to trigger a modify event on an attribute without
+        any specific value being set.
+
+        .. versionadded:: 1.2
+
+        :param target: the object instance receiving the event.
+          If the listener is registered with ``raw=True``, this will
+          be the :class:`.InstanceState` object.
+
+        :param initiator: An instance of :class:`.attributes.Event`
+          representing the initiation of the event.
+
+        """
+
 
 class QueryEvents(event.Events):
     """Represent events within the construction of a :class:`.Query` object.