- add more documentation to MutableDict explaining

that this structure is only intended to track additions
and removals from the dictionary, not recursive tracking
of embedded changes.  fixes #3646.

(cherry picked from commit 5497b1086f9fe44e0594079b036ea939fbc3c479)

diff --git a/lib/sqlalchemy/ext/mutable.py b/lib/sqlalchemy/ext/mutable.py
index 24fc37a42111465bde0473ba1fc5a4e624a2e313..ca604b1207a928e5f09f9359d9686ed4b55a7153 100644 (file)
--- a/lib/sqlalchemy/ext/mutable.py
+++ b/lib/sqlalchemy/ext/mutable.py
@@ -602,6 +602,18 @@ _setup_composite_listener()
 class MutableDict(Mutable, dict):
     """A dictionary type that implements :class:`.Mutable`.
 
+    The :class:`.MutableDict` object implements a dictionary that will
+    emit change events to the underlying mapping when the contents of
+    the dictionary are altered, including when values are added or removed.
+
+    Note that :class:`.MutableDict` does **not** apply mutable tracking to  the
+    *values themselves* inside the dictionary. Therefore it is not a sufficient
+    solution for the use case of tracking deep changes to a *recursive*
+    dictionary structure, such as a JSON structure.  To support this use case,
+    build a subclass of  :class:`.MutableDict` that provides appropriate
+    coersion to the values placed in the dictionary so that they too are
+    "mutable", and emit events up to their parent structure.
+
     .. versionadded:: 0.8
 
     """