From: Stephen Rosen <sirosen@globus.org>
Date: Fri, 9 Apr 2021 23:53:06 +0000 (+0000)
Subject: Document backref() for setting cascade_backrefs
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=464fc979fdd30cce17c56c88638485353bb4e6da;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Document backref() for setting cascade_backrefs

Add a section to the documentation for the cascade_backrefs
parameter to `relationship()` which explains that `cascade_backrefs`
can also be used as a parameter to the `backref()` function when a
relationship is being specified using `relationship.backref`.
---

diff --git a/doc/build/orm/cascades.rst b/doc/build/orm/cascades.rst
index 23fec99eb7..4d664476f5 100644
--- a/doc/build/orm/cascades.rst
+++ b/doc/build/orm/cascades.rst
@@ -603,7 +603,18 @@ option may be helpful for situations where an object needs to be kept out of a
 session until it's construction is completed, but still needs to be given
 associations to objects which are already persistent in the target session.
 
+When relationships are created by the ``backref`` parameter to
+``relationship()``, ``cascade_backrefs=False`` can be set by using the
+``backref()`` function instead of a string. For example, the above relationship
+could be declared::
 
+    mapper_registry.map_imperatively(Order, order_table, properties={
+        'items' : relationship(
+            Item, backref=backref('order', cascade_backrefs=False), cascade_backrefs=False
+        )
+    })
+
+This sets the ``cascade_backrefs=False`` behavior on both relationships.
 
 .. _session_deleting_from_collections: