Add bulk_replace event, integrate with @validates

Added new attribute event :meth:`.AttributeEvents.bulk_replace`.
This event is triggered when a collection is assigned to a
relationship, before the incoming collection is compared with the
existing one.  This early event allows for conversion of incoming
non-ORM objects as well.  The event is integrated with the
``@validates`` decorator.

The ``@validates`` decorator now allows the decorated method to receive
objects from a "bulk collection set" operation that have not yet
been compared to the existing collection.  This allows incoming values
to be converted to compatible ORM objects as is already allowed
from an "append" event.   Note that this means that the
``@validates`` method is called for **all** values during a collection
assignment, rather than just the ones that are new.

Change-Id: I27f59db008d9e521d31a3e30143d7cd997e4b7b3
Fixes: #3896

1 files changed, 21 insertions, 2 deletions

diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py
index fc0dba5ee..73b0be99c 100644
--- a/lib/sqlalchemy/orm/util.py
+++ b/lib/sqlalchemy/orm/util.py
@@ -91,11 +91,20 @@ def _validator_events(
 
     if include_removes:
         def append(state, value, initiator):
-            if include_backrefs or not detect_is_backref(state, initiator):
+            if (
+                initiator.op is not attributes.OP_BULK_REPLACE and
+                (include_backrefs or not detect_is_backref(state, initiator))
+            ):
                 return validator(state.obj(), key, value, False)
             else:
                 return value
 
+        def bulk_set(state, values, initiator):
+            if include_backrefs or not detect_is_backref(state, initiator):
+                obj = state.obj()
+                values[:] = [
+                    validator(obj, key, value, False) for value in values]
+
         def set_(state, value, oldvalue, initiator):
             if include_backrefs or not detect_is_backref(state, initiator):
                 return validator(state.obj(), key, value, False)
@@ -108,11 +117,20 @@ def _validator_events(
 
     else:
         def append(state, value, initiator):
-            if include_backrefs or not detect_is_backref(state, initiator):
+            if (
+                initiator.op is not attributes.OP_BULK_REPLACE and
+                (include_backrefs or not detect_is_backref(state, initiator))
+            ):
                 return validator(state.obj(), key, value)
             else:
                 return value
 
+        def bulk_set(state, values, initiator):
+            if include_backrefs or not detect_is_backref(state, initiator):
+                obj = state.obj()
+                values[:] = [
+                    validator(obj, key, value) for value in values]
+
         def set_(state, value, oldvalue, initiator):
             if include_backrefs or not detect_is_backref(state, initiator):
                 return validator(state.obj(), key, value)
@@ -120,6 +138,7 @@ def _validator_events(
                 return value
 
     event.listen(desc, 'append', append, raw=True, retval=True)
+    event.listen(desc, 'bulk_replace', bulk_set, raw=True)
     event.listen(desc, 'set', set_, raw=True, retval=True)
     if include_removes:
         event.listen(desc, "remove", remove, raw=True, retval=True)