clarify cascade docstring, [ticket:1716]

diff --git a/doc/build/session.rst b/doc/build/session.rst
index 7bb0ae7e093961ff969fa38a3f7b288ba416cb2b..0731405b5e16b58d6338827cfc761fa7983eedf3 100644 (file)
--- a/doc/build/session.rst
+++ b/doc/build/session.rst
@@ -393,7 +393,7 @@ Cascading is configured by setting the ``cascade`` keyword argument on a :func:`
 
 The above mapper specifies two relationships, ``items`` and ``customer``.  The ``items`` relationship specifies "all, delete-orphan" as its ``cascade`` value, indicating that all  ``add``, ``merge``, ``expunge``, ``refresh`` ``delete`` and ``expire`` operations performed on a parent ``Order`` instance should also be performed on the child ``Item`` instances attached to it.  The ``delete-orphan`` cascade value additionally indicates that if an ``Item`` instance is no longer associated with an ``Order``, it should also be deleted.  The "all, delete-orphan" cascade argument allows a so-called *lifecycle* relationship between an ``Order`` and an ``Item`` object.
 
-The ``customer`` relationship specifies only the "save-update" cascade value, indicating most operations will not be cascaded from a parent ``Order`` instance to a child ``User`` instance except for the :func:`~sqlalchemy.orm.session.Session.add` operation.  "save-update" cascade indicates that an :func:`~sqlalchemy.orm.session.Session.add` on the parent will cascade to all child items, and also that items added to a parent which is already present in the session will also be added.  "save-update" cascade also cascades the *pending history* of a 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).
+The ``customer`` relationship specifies only the "save-update" cascade value, indicating most operations will not be cascaded from a parent ``Order`` instance to a child ``User`` instance except for the :func:`~sqlalchemy.orm.session.Session.add` operation.  "save-update" cascade indicates that an :func:`~sqlalchemy.orm.session.Session.add` on the parent will cascade to all child items, and also that items added to a parent which is already present in a session will also be added to that same session.  "save-update" cascade also cascades the *pending history* of a 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).
 
 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 appropriate for one-to-one or one-to-many relationships.  For a :func:`~sqlalchemy.orm.relationship` which establishes one-to-one via a local foreign key, i.e. a many-to-one that stores only a single parent, or one-to-one/one-to-many via a "secondary" (association) table, a warning will be issued if ``delete-orphan`` is configured.  To disable this warning, also specify the ``single_parent=True`` flag on the relationship, which constrains objects to allow attachment to only one parent at a time.
 

diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index 5d4bc2ee4fc9cf7bad44eaba521cf0bda1ff74cb..2b577db8788a528b1259f91515e6a3bffccdd864 100644 (file)
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -230,25 +230,33 @@ def relationship(argument, secondary=None, **kwargs):
 
       Available cascades are:
 
-        ``save-update`` - cascade the "add()" operation (formerly
-        known as save() and update())
+        * ``save-update`` - cascade the :meth:`~sqlalchemy.orm.session.Session.add` 
+          operation.  This cascade applies both to future and
+          past calls to :meth:`~sqlalchemy.orm.session.Session.add`, 
+          meaning new items added to a collection or scalar relationship
+          get placed into the same session as that of the parent, and 
+          also applies to items which have been removed from this 
+          relationship but are still part of unflushed history.
 
-        ``merge`` - cascade the "merge()" operation
+        * ``merge`` - cascade the :meth:`~sqlalchemy.orm.session.Session.merge`
+          operation
 
-        ``expunge`` - cascade the "expunge()" operation
+        * ``expunge`` - cascade the :meth:`~sqlalchemy.orm.session.Session.expunge`
+          operation
 
-        ``delete`` - cascade the "delete()" operation
+        * ``delete`` - cascade the :meth:`~sqlalchemy.orm.session.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 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.
 
-        ``refresh-expire`` - cascade the expire() and refresh()
-        operations
+        * ``refresh-expire`` - cascade the :meth:`~sqlalchemy.orm.session.Session.expire` 
+          and :meth:`~sqlalchemy.orm.session.Session.refresh` operations
 
-        ``all`` - shorthand for "save-update,merge, refresh-expire,
-        expunge, delete"
+        * ``all`` - shorthand for "save-update,merge, refresh-expire,
+          expunge, delete"
 
     :param collection_class:
       a class or callable that returns a new list-holding object. will