implement deferred scalarobject history load

Modified the approach used for history tracking of scalar object
relationships that are not many-to-one, i.e. one-to-one relationships that
would otherwise be one-to-many. When replacing a one-to-one value, the
"old" value that would be replaced is no longer loaded immediately, and is
instead handled during the flush process. This eliminates an historically
troublesome lazy load that otherwise often occurs when assigning to a
one-to-one attribute, and is particularly troublesome when using
"lazy='raise'" as well as asyncio use cases.

This change does cause a behavioral change within the
:meth:`_orm.AttributeEvents.set` event, which is nonetheless currently
documented, which is that the event applied to such a one-to-one attribute
will no longer receive the "old" parameter if it is unloaded and the
:paramref:`_orm.relationship.active_history` flag is not set. As is
documented in :meth:`_orm.AttributeEvents.set`, if the event handler needs
to receive the "old" value when the event fires off, the active_history
flag must be established either with the event listener or with the
relationship. This is already the behavior with other kinds of attributes
such as many-to-one and column value references.

The change additionally will defer updating a backref on the "old" value
in the less common case that the "old" value is locally present in the
session, but isn't loaded on the relationship in question, until the
next flush occurs.  If this causes an issue, again the normal
:paramref:`_orm.relationship.active_history` flag can be set to ``True``
on the relationship.

A private flag which restores the old value is retained for now,
as support within relevant test suites to exercise the old and
new behaviors together.  This is so that if the behavioral change
produces problems we have test harnesses set up to further examine these
behaviors.   The "legacy" style can go away in 2.0 or in a much later
1.4 release.

Fixes: #6708
Change-Id: Id7f72fc39dcbec9119b665e528667a9919bb73b4

1 files changed, 28 insertions, 12 deletions

diff --git a/lib/sqlalchemy/orm/strategies.py b/lib/sqlalchemy/orm/strategies.py
index 2a254f8de..7d7438452 100644
--- a/lib/sqlalchemy/orm/strategies.py
+++ b/lib/sqlalchemy/orm/strategies.py
@@ -695,18 +695,27 @@ class LazyLoader(AbstractRelationshipLoader, util.MemoizedSlots):
     def init_class_attribute(self, mapper):
         self.is_class_level = True
 
-        active_history = (
-            self.parent_property.active_history
-            or self.parent_property.direction is not interfaces.MANYTOONE
-            or not self.use_get
+        _legacy_inactive_history_style = (
+            self.parent_property._legacy_inactive_history_style
         )
 
-        # MANYTOONE currently only needs the
-        # "old" value for delete-orphan
-        # cascades.  the required _SingleParentValidator
-        # will enable active_history
-        # in that case.  otherwise we don't need the
-        # "old" value during backref operations.
+        if self.parent_property.active_history:
+            active_history = True
+            _deferred_history = False
+
+        elif (
+            self.parent_property.direction is not interfaces.MANYTOONE
+            or not self.use_get
+        ):
+            if _legacy_inactive_history_style:
+                active_history = True
+                _deferred_history = False
+            else:
+                active_history = False
+                _deferred_history = True
+        else:
+            active_history = _deferred_history = False
+
         _register_attribute(
             self.parent_property,
             mapper,
@@ -714,6 +723,7 @@ class LazyLoader(AbstractRelationshipLoader, util.MemoizedSlots):
             callable_=self._load_for_state,
             typecallable=self.parent_property.collection_class,
             active_history=active_history,
+            _deferred_history=_deferred_history,
         )
 
     def _memoized_attr__simple_lazy_clause(self):
@@ -850,7 +860,10 @@ class LazyLoader(AbstractRelationshipLoader, util.MemoizedSlots):
             if _none_set.issuperset(primary_key_identity):
                 return None
 
-            if self.key in state.dict:
+            if (
+                self.key in state.dict
+                and not passive & attributes.DEFERRED_HISTORY_LOAD
+            ):
                 return attributes.ATTR_WAS_SET
 
             # look for this identity in the identity map.  Delegate to the
@@ -1016,7 +1029,10 @@ class LazyLoader(AbstractRelationshipLoader, util.MemoizedSlots):
             "_sa_orm_load_options": load_options,
         }
 
-        if self.key in state.dict:
+        if (
+            self.key in state.dict
+            and not passive & attributes.DEFERRED_HISTORY_LOAD
+        ):
             return attributes.ATTR_WAS_SET
 
         if pending: