From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Wed, 10 Feb 2016 15:17:45 +0000 (-0500)
Subject: - add more documentation to MutableDict explaining
X-Git-Tag: rel_1_1_0b1~98^2~28
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=287aaa9d416b4f72179da320af0624b9ebc43846;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- 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.
---

diff --git a/lib/sqlalchemy/ext/mutable.py b/lib/sqlalchemy/ext/mutable.py
index 977fa0d4e6..97f720cb4c 100644
--- a/lib/sqlalchemy/ext/mutable.py
+++ b/lib/sqlalchemy/ext/mutable.py
@@ -635,6 +635,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
 
     """