From 287aaa9d416b4f72179da320af0624b9ebc43846 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Wed, 10 Feb 2016 10:17:45 -0500 Subject: [PATCH] - 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. --- lib/sqlalchemy/ext/mutable.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) 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 """ -- 2.47.2