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

7 files changed, 133 insertions, 6 deletions

diff --git a/doc/build/changelog/changelog_12.rst b/doc/build/changelog/changelog_12.rst
index 10219e2bf..1797a14ad 100644
--- a/doc/build/changelog/changelog_12.rst
+++ b/doc/build/changelog/changelog_12.rst
@@ -436,6 +436,19 @@
         assuming it would match the dialect-level paramstyle, causing
         mismatches to occur.
 
+    .. change:: 3303
+        :tags: feature, orm
+        :tickets: 3303
+
+        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.
+
+        .. seealso::
+
+            :ref:`change_3303`
+
     .. change:: 3918
         :tags: bug, ext
         :tickets: 3918
diff --git a/doc/build/changelog/migration_12.rst b/doc/build/changelog/migration_12.rst
index d321af871..bb863ccca 100644
--- a/doc/build/changelog/migration_12.rst
+++ b/doc/build/changelog/migration_12.rst
@@ -305,7 +305,35 @@ if this "append" event is the second part of a bulk replace::
 
 :ticket:`3896`
 
+.. _change_3303:
 
+New "modified" event handler for sqlalchemy.ext.mutable
+-------------------------------------------------------
+
+A new event handler :meth:`.AttributeEvents.modified` is added, which is
+triggered corresponding to calls to the :func:`.attributes.flag_modified`
+method, which is normally called from the :mod:`sqlalchemy.ext.mutable`
+extension::
+
+    from sqlalchemy.ext.declarative import declarative_base
+    from sqlalchemy.ext.mutable import MutableDict
+    from sqlalchemy import event
+
+    Base = declarative_base()
+
+    class MyDataClass(Base):
+        __tablename__ = 'my_data'
+        id = Column(Integer, primary_key=True)
+        data = Column(MutableDict.as_mutable(JSONEncodedDict))
+
+    @event.listens_for(MyDataClass.data, "modified")
+    def modified_json(instance):
+        print("json value modified:", instance.data)
+
+Above, the event handler will be triggered when an in-place change to the
+``.data`` dictionary occurs.
+
+:ticket:`3303`
 
 New Features and Improvements - Core
 ====================================
diff --git a/lib/sqlalchemy/ext/mutable.py b/lib/sqlalchemy/ext/mutable.py
index e721397b3..ccaeb6aa3 100644
--- a/lib/sqlalchemy/ext/mutable.py
+++ b/lib/sqlalchemy/ext/mutable.py
@@ -204,6 +204,28 @@ or more parent objects that are also part of the pickle, the :class:`.Mutable`
 mixin will re-establish the :attr:`.Mutable._parents` collection on each value
 object as the owning parents themselves are unpickled.
 
+Receiving Events
+----------------
+
+The :meth:`.AttributeEvents.modified` event handler may be used to receive
+an event when a mutable scalar emits a change event.  This event handler
+is called when the :func:`.attributes.flag_modified` function is called
+from within the mutable extension::
+
+    from sqlalchemy.ext.declarative import declarative_base
+    from sqlalchemy import event
+
+    Base = declarative_base()
+
+    class MyDataClass(Base):
+        __tablename__ = 'my_data'
+        id = Column(Integer, primary_key=True)
+        data = Column(MutableDict.as_mutable(JSONEncodedDict))
+
+    @event.listens_for(MyDataClass.data, "modified")
+    def modified_json(instance):
+        print("json value modified:", instance.data)
+
 .. _mutable_composites:
 
 Establishing Mutability on Composites
diff --git a/lib/sqlalchemy/orm/attributes.py b/lib/sqlalchemy/orm/attributes.py
index 23a9f1a8c..f3a5c4735 100644
--- a/lib/sqlalchemy/orm/attributes.py
+++ b/lib/sqlalchemy/orm/attributes.py
@@ -330,6 +330,7 @@ OP_REMOVE = util.symbol("REMOVE")
 OP_APPEND = util.symbol("APPEND")
 OP_REPLACE = util.symbol("REPLACE")
 OP_BULK_REPLACE = util.symbol("BULK_REPLACE")
+OP_MODIFIED = util.symbol("MODIFIED")
 
 
 class Event(object):
@@ -341,9 +342,9 @@ class Event(object):
     operations.
 
     The :class:`.Event` object is sent as the ``initiator`` argument
-    when dealing with the :meth:`.AttributeEvents.append`,
+    when dealing with events such as :meth:`.AttributeEvents.append`,
     :meth:`.AttributeEvents.set`,
-    and :meth:`.AttributeEvents.remove` events.
+    and :meth:`.AttributeEvents.remove`.
 
     The :class:`.Event` object is currently interpreted by the backref
     event handlers, and is used to control the propagation of operations
@@ -459,12 +460,18 @@ class AttributeImpl(object):
             self.dispatch._active_history = True
 
         self.expire_missing = expire_missing
+        self._modified_token = None
 
     __slots__ = (
         'class_', 'key', 'callable_', 'dispatch', 'trackparent',
-        'parent_token', 'send_modified_events', 'is_equal', 'expire_missing'
+        'parent_token', 'send_modified_events', 'is_equal', 'expire_missing',
+        '_modified_token'
     )
 
+    def _init_modified_token(self):
+        self._modified_token = Event(self, OP_MODIFIED)
+        return self._modified_token
+
     def __str__(self):
         return "%s.%s" % (self.class_.__name__, self.key)
 
@@ -1636,6 +1643,8 @@ def flag_modified(instance, key):
     """
     state, dict_ = instance_state(instance), instance_dict(instance)
     impl = state.manager[key].impl
+    impl.dispatch.modified(
+        state, impl._modified_token or impl._init_modified_token())
     state._modified_event(dict_, impl, NO_VALUE, is_userland=True)
 
 
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.
diff --git a/test/ext/test_mutable.py b/test/ext/test_mutable.py
index 23bccafe9..366b2006f 100644
--- a/test/ext/test_mutable.py
+++ b/test/ext/test_mutable.py
@@ -2,6 +2,7 @@ from sqlalchemy import Integer, ForeignKey, String, func
 from sqlalchemy.types import PickleType, TypeDecorator, VARCHAR
 from sqlalchemy.orm import mapper, Session, composite, column_property
 from sqlalchemy.orm.mapper import Mapper
+from sqlalchemy.orm import attributes
 from sqlalchemy.orm.instrumentation import ClassManager
 from sqlalchemy.testing.schema import Table, Column
 from sqlalchemy.testing import eq_, assert_raises_message, assert_raises
@@ -9,6 +10,8 @@ from sqlalchemy.testing.util import picklers
 from sqlalchemy.testing import fixtures
 from sqlalchemy.ext.mutable import MutableComposite
 from sqlalchemy.ext.mutable import MutableDict, MutableList, MutableSet
+from sqlalchemy.testing import mock
+from sqlalchemy import event
 
 
 class Foo(fixtures.BasicEntity):
@@ -112,6 +115,19 @@ class _MutableDictTestBase(_MutableDictTestFixture):
 
         eq_(f1.data, {'a': 'c'})
 
+    def test_modified_event(self):
+        canary = mock.Mock()
+        event.listen(Foo.data, "modified", canary)
+
+        f1 = Foo(data={"a": "b"})
+        f1.data["a"] = "c"
+
+        eq_(
+            canary.mock_calls,
+            [mock.call(
+                f1, attributes.Event(Foo.data.impl, attributes.OP_MODIFIED))]
+        )
+
     def test_clear(self):
         sess = Session()
 
diff --git a/test/orm/test_attributes.py b/test/orm/test_attributes.py
index 6dcba1f3f..4646a010a 100644
--- a/test/orm/test_attributes.py
+++ b/test/orm/test_attributes.py
@@ -2779,6 +2779,23 @@ class ListenerTest(fixtures.ORMTest):
         f1.barlist.remove(None)
         eq_(canary, [(f1, b1), (f1, None), (f1, b2), (f1, None)])
 
+    def test_flag_modified(self):
+        canary = Mock()
+
+        class Foo(object):
+            pass
+        instrumentation.register_class(Foo)
+        attributes.register_attribute(Foo, 'bar')
+
+        event.listen(Foo.bar, "modified", canary)
+        f1 = Foo()
+        f1.bar = 'hi'
+        attributes.flag_modified(f1, "bar")
+        eq_(
+            canary.mock_calls,
+            [call(f1, attributes.Event(Foo.bar.impl, attributes.OP_MODIFIED))]
+        )
+
     def test_none_init_scalar(self):
         canary = Mock()