From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Tue, 6 Dec 2011 17:15:06 +0000 (-0500)
Subject: update delete-orphan cascade docs per [ticket:2332]
X-Git-Tag: rel_0_7_4~20
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e63117159f2c5c52cdefec9a79457b799ab1c08a;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

update delete-orphan cascade docs per [ticket:2332]
---

diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst
index 1e77a2cecd..a41d514f2b 100644
--- a/doc/build/orm/session.rst
+++ b/doc/build/orm/session.rst
@@ -523,8 +523,8 @@ is extremely convenient.  The solution here would usually be to not assign
 ``a1.user`` to an object already persistent in the target
 session.
 
-Note that a new :func:`.relationship` option introduced in 0.6.5, 
-``cascade_backrefs=False``, will also prevent the ``Address`` from
+The ``cascade_backrefs=False`` option of :func:`.relationship`
+will also prevent the ``Address`` from
 being added to the session via the ``a1.user = u1`` assignment.
 
 Further detail on cascade operation is at :ref:`unitofwork_cascades`.
@@ -942,7 +942,7 @@ is already present in a session will also be added to that same session.
 relationship()-based attribute, meaning that objects which were removed from a
 scalar or collection attribute whose changes have not yet been flushed are
 also placed into the new session - this so that foreign key clear operations
-and deletions will take place (new in 0.6).
+and deletions will take place.
 
 Note that the ``delete-orphan`` cascade only functions for relationships where
 the target object can have a single parent at a time, meaning it is only
@@ -957,7 +957,10 @@ objects to allow attachment to only one parent at a time.
 The default value for ``cascade`` on :func:`~sqlalchemy.orm.relationship` is
 ``save-update, merge``.
 
-``save-update`` cascade also takes place on backrefs by default.   This means
+Controlling Cascade on Backrefs
+-------------------------------
+
+The ``save-update`` cascade takes place on backrefs by default.   This means
 that, given a mapping such as this::
 
     mapper(Order, order_table, properties={
@@ -981,7 +984,7 @@ place::
     >>> i1 in session
     True
 
-This behavior can be disabled as of 0.6.5 using the ``cascade_backrefs`` flag::
+This behavior can be disabled using the ``cascade_backrefs`` flag::
 
     mapper(Order, order_table, properties={
         'items' : relationship(Item, backref='order', 
diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index ec4f39fdf8..afb64d4918 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -295,10 +295,13 @@ def relationship(argument, secondary=None, **kwargs):
       * ``delete`` - cascade the :meth:`.Session.delete`
         operation
 
-      * ``delete-orphan`` - if an item of the child's type with no
-        parent is detected, mark it for deletion.  Note that this
-        option prevents a pending item of the child's class from being
-        persisted without a parent present.
+      * ``delete-orphan`` - if an item of the child's type is 
+        detached from its parent, mark it for deletion.  
+        As of version 0.7, this option does not prevent
+        a new instance of the child object from being persisted
+        without a parent to start with; to constrain against
+        that case, ensure the child's foreign key column(s)
+        is configured as NOT NULL
 
       * ``refresh-expire`` - cascade the :meth:`.Session.expire` 
         and :meth:`~sqlalchemy.orm.session.Session.refresh` operations
@@ -306,6 +309,9 @@ def relationship(argument, secondary=None, **kwargs):
       * ``all`` - shorthand for "save-update,merge, refresh-expire,
         expunge, delete"
 
+     See the section :ref:`unitofwork_cascades` for more background
+     on configuring cascades.
+     
     :param cascade_backrefs=True:
       a boolean value indicating if the ``save-update`` cascade should
       operate along an assignment event intercepted by a backref.   
@@ -332,7 +338,8 @@ def relationship(argument, secondary=None, **kwargs):
                 )
         })
       
-      ``cascade_backrefs`` is new in 0.6.5.
+      See the section :ref:`unitofwork_cascades` for more background
+      on configuring cascades.
 
     :param collection_class:
       a class or callable that returns a new list-holding object. will