From c6eca2271770308bac2747f0c32030ffaf8d7747 Mon Sep 17 00:00:00 2001 From: Evan Taylor Yates Date: Sat, 3 Oct 2020 17:04:44 -0700 Subject: [PATCH 1/2] Add parens around unmarked clause I'm not 100% sure what this sentence is saying, but I'm pretty sure it needs either commas or parentheses to break it up a little. I think parens make the most sense in this case assuming I am reading it correctly. Here's the original sentence and proposed edit in plaintext: ORIG "...persistent objects which were removed from a collection or in some cases a scalar attribute may also be pulled into the Session of a parent object;..." EDIT "...persistent objects which were removed from a collection (or in some cases a scalar attribute) may also be pulled into the Session of a parent object;..." --- doc/build/orm/cascades.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/build/orm/cascades.rst b/doc/build/orm/cascades.rst index 3f06b34c2f..8a2a948760 100644 --- a/doc/build/orm/cascades.rst +++ b/doc/build/orm/cascades.rst @@ -95,7 +95,7 @@ becomes part of the state of that :class:`.Session`:: ``save-update`` has the possibly surprising behavior which is that persistent objects which were *removed* from a collection -or in some cases a scalar attribute +(or in some cases a scalar attribute) may also be pulled into the :class:`.Session` of a parent object; this is so that the flush process may handle that related object appropriately. This case can usually only arise if an object is removed from one :class:`.Session` From 7740ce6900ad3e65364660a270cc72458421433a Mon Sep 17 00:00:00 2001 From: Evan Taylor Yates Date: Tue, 13 Oct 2020 12:21:30 -0700 Subject: [PATCH 2/2] Add discussed changes PR link: https://github.com/sqlalchemy/sqlalchemy/pull/5636 --- doc/build/orm/cascades.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/build/orm/cascades.rst b/doc/build/orm/cascades.rst index 8a2a948760..528e69a97b 100644 --- a/doc/build/orm/cascades.rst +++ b/doc/build/orm/cascades.rst @@ -93,12 +93,11 @@ becomes part of the state of that :class:`.Session`:: >>> address3 in sess >>> True -``save-update`` has the possibly surprising behavior which is that -persistent objects which were *removed* from a collection -(or in some cases a scalar attribute) -may also be pulled into the :class:`.Session` of a parent object; this is +A ``save-update`` cascade can exhibit surprising behavior when removing an item from +a collection or de-associating an object from a scalar attribute. In some cases, the +orphaned objects may still be pulled into the ex-parent's :class:`.Session`; this is so that the flush process may handle that related object appropriately. -This case can usually only arise if an object is removed from one :class:`.Session` +This case usually only arises if an object is removed from one :class:`.Session` and added to another:: >>> user1 = sess1.query(User).filter_by(id=1).first()