Establish future behavior for Session cascade backrefs, bind

The behavior of the :paramref:`_orm.relationship.cascade_backrefs` flag
will be reversed in 2.0 and set to ``False`` unconditionally, such that
backrefs don't cascade save-update operations from a forwards-assignment to
a backwards assignment.   A 2.0 deprecation warning is emitted when the
parameter is left at its default of ``True`` at the point at which such a
cascade operation actually takes place.   The new behavior can be
established as always by setting the flag to ``False`` on a specific
:func:`_orm.relationship`, or more generally can be set up across the board
by setting the the :paramref:`_orm.Session.future` flag to True.

Additionally in the interests of expediency, this commit will also
move Session away from making use of bound metadata if the future=True
flag is set.   An application that sets future=True should ideally
have to change as little else as possible for full 2.0 behavior.

Fixes: #5150
Change-Id: I490d1d61f09c62ffc2de983208aeed25dfe48aec

1 files changed, 23 insertions, 2 deletions

diff --git a/lib/sqlalchemy/orm/unitofwork.py b/lib/sqlalchemy/orm/unitofwork.py
index 97eea4864..9c67130ce 100644
--- a/lib/sqlalchemy/orm/unitofwork.py
+++ b/lib/sqlalchemy/orm/unitofwork.py
@@ -21,6 +21,16 @@ from .. import util
 from ..util import topological
 
 
+def _warn_for_cascade_backrefs(state, prop):
+    util.warn_deprecated_20(
+        '"%s" object is being merged into a Session along the backref '
+        'cascade path for relationship "%s"; in SQLAlchemy 2.0, this '
+        "reverse cascade will not take place.  Set cascade_backrefs to "
+        "False for the 2.0 behavior; or to set globally for the whole "
+        "Session, set the future=True flag" % (state.class_.__name__, prop)
+    )
+
+
 def track_cascade_events(descriptor, prop):
     """Establish event listeners on object attributes which handle
     cascade-on-set/append.
@@ -42,11 +52,17 @@ def track_cascade_events(descriptor, prop):
 
             prop = state.manager.mapper._props[key]
             item_state = attributes.instance_state(item)
+
             if (
                 prop._cascade.save_update
-                and (prop.cascade_backrefs or key == initiator.key)
+                and (
+                    (prop.cascade_backrefs and not sess.future)
+                    or key == initiator.key
+                )
                 and not sess._contains_state(item_state)
             ):
+                if key != initiator.key:
+                    _warn_for_cascade_backrefs(item_state, prop)
                 sess._save_or_update_state(item_state)
         return item
 
@@ -101,9 +117,14 @@ def track_cascade_events(descriptor, prop):
                 newvalue_state = attributes.instance_state(newvalue)
                 if (
                     prop._cascade.save_update
-                    and (prop.cascade_backrefs or key == initiator.key)
+                    and (
+                        (prop.cascade_backrefs and not sess.future)
+                        or key == initiator.key
+                    )
                     and not sess._contains_state(newvalue_state)
                 ):
+                    if key != initiator.key:
+                        _warn_for_cascade_backrefs(newvalue_state, prop)
                     sess._save_or_update_state(newvalue_state)
 
             if (