updated docs for delete()

diff --git a/doc/build/content/unitofwork.txt b/doc/build/content/unitofwork.txt
index a8d76ed7d0a5a4ce866291ea88f88e6e2a2e8bc7..bb943fc648b6278278bb014f240a26f9ed6cef8c 100644 (file)
--- a/doc/build/content/unitofwork.txt
+++ b/doc/build/content/unitofwork.txt
@@ -241,6 +241,9 @@ The delete operation will have an effect on instances that are attached to the d
 
 The `delete()` operation has no relationship to the in-memory status of the instance, including usage of the `del` Python statement.  An instance marked as deleted and flushed will still exist within memory until references to it are freed; similarly, removing an instance from memory via the `del` statement will have no effect, since the persistent instance will still be referenced by its Session.  Obviously, if the instance is removed from the Session and then totally dereferenced, it will no longer exist in memory, but also won't exist in any Session and is therefore not deleted from the database.
 
+Note that the "in-memory status" of an instance also refers to its presence in any other collection.  **SQLAlchemy does not track all collections to which an instance is ia member, will not remove an instance from its parent collections that were not directly involved in a deletion operation**.  The operational and memory overhead implied by this would be too great (such as, if an object belonged to hundreds of collections).  This means if an object `A` is attached to both an object `B` and an object `C`, if you `delete()` `A` and flush, `A` still remains attached to both `B` and `C` in a deleted state and must be removed by the application.  Similarly, if a delete on `B` cascades to `A`, this **does not** affect `A` still being present on `C` - again it must be manually removed.
+
+
 #### clear() {@name=clear}    
 
 This method detaches all instances from the Session, sending them to the detached or transient state as applicable, and replaces the underlying UnitOfWork with a new one.