- add changelog, migration, version flags and some extra notes

to the new MutableList and MutableSet classes, fixes #3297

4 files changed, 65 insertions, 1 deletions

diff --git a/doc/build/changelog/changelog_11.rst b/doc/build/changelog/changelog_11.rst
index 273bffb83..95a127579 100644
--- a/doc/build/changelog/changelog_11.rst
+++ b/doc/build/changelog/changelog_11.rst
@@ -22,6 +22,14 @@
     :version: 1.1.0b1
 
     .. change::
+        :tags: feature, ext
+        :tickets: 3297
+
+        Added :class:`.MutableSet` and :class:`.MutableList` helper classes
+        to the :ref:`mutable_toplevel` extension.  Pull request courtesy
+        Jeong YunWon.
+
+    .. change::
         :tags: feature, sql
         :tickets: 2551
 
diff --git a/doc/build/changelog/migration_11.rst b/doc/build/changelog/migration_11.rst
index 7eb8e800f..9ad99ae9f 100644
--- a/doc/build/changelog/migration_11.rst
+++ b/doc/build/changelog/migration_11.rst
@@ -526,6 +526,15 @@ remains unchanged.
 
 :ticket:`3641`
 
+New MutableList and MutableSet helpers added to the mutation tracking extension
+-------------------------------------------------------------------------------
+
+New helper classes :class:`.MutableList` and :class:`.MutableSet` have been
+added to the :ref:`mutable_toplevel` extension, to complement the existing
+:class:`.MutableDict` helper.
+
+:ticket:`3297`
+
 New Features and Improvements - Core
 ====================================
 
diff --git a/doc/build/orm/extensions/mutable.rst b/doc/build/orm/extensions/mutable.rst
index 969411481..2ef0a5adb 100644
--- a/doc/build/orm/extensions/mutable.rst
+++ b/doc/build/orm/extensions/mutable.rst
@@ -23,5 +23,12 @@ API Reference
 	:members:
 	:undoc-members:
 
+.. autoclass:: MutableList
+	:members:
+	:undoc-members:
+
+.. autoclass:: MutableSet
+	:members:
+	:undoc-members:
 
 
diff --git a/lib/sqlalchemy/ext/mutable.py b/lib/sqlalchemy/ext/mutable.py
index aa5be57ff..571bbbda3 100644
--- a/lib/sqlalchemy/ext/mutable.py
+++ b/lib/sqlalchemy/ext/mutable.py
@@ -649,6 +649,12 @@ class MutableDict(Mutable, dict):
 
     .. versionadded:: 0.8
 
+    .. seealso::
+
+        :class:`.MutableList`
+
+        :class:`.MutableSet`
+
     """
 
     def __setitem__(self, key, value):
@@ -708,6 +714,22 @@ class MutableList(Mutable, list):
     emit change events to the underlying mapping when the contents of
     the list are altered, including when values are added or removed.
 
+    Note that :class:`.MutableList` does **not** apply mutable tracking to  the
+    *values themselves* inside the list. Therefore it is not a sufficient
+    solution for the use case of tracking deep changes to a *recursive*
+    mutable structure, such as a JSON structure.  To support this use case,
+    build a subclass of  :class:`.MutableList` 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:: 1.1
+
+    .. seealso::
+
+        :class:`.MutableDict`
+
+        :class:`.MutableSet`
+
     """
 
     def __setitem__(self, index, value):
@@ -783,9 +805,27 @@ class MutableList(Mutable, list):
 class MutableSet(Mutable, set):
     """A set type that implements :class:`.Mutable`.
 
-    The :class:`.MutableSet` object implements a list that will
+    The :class:`.MutableSet` object implements a set that will
     emit change events to the underlying mapping when the contents of
     the set are altered, including when values are added or removed.
+
+    Note that :class:`.MutableSet` does **not** apply mutable tracking to  the
+    *values themselves* inside the set. Therefore it is not a sufficient
+    solution for the use case of tracking deep changes to a *recursive*
+    mutable structure.  To support this use case,
+    build a subclass of  :class:`.MutableSet` 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:: 1.1
+
+    .. seealso::
+
+        :class:`.MutableDict`
+
+        :class:`.MutableList`
+
+
     """
 
     def update(self, *arg):