Commits

Mike Bayer committed 4eff410

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

  • Participants
  • Parent commits b2c40e2

Comments (0)

Files changed (2)

doc/build/orm/session.rst

 ``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`.
 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
 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={
     >>> 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', 

lib/sqlalchemy/orm/__init__.py

       * ``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
       * ``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.   
                 )
         })
       
-      ``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