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

to the new MutableList and MutableSet classes, fixes #3297

diff --git a/doc/build/changelog/changelog_11.rst b/doc/build/changelog/changelog_11.rst
index 273bffb83dff99507dd485e69171a984906a6ecb..95a1275793a2e2f7266a7475a539d6c40445a863 100644 (file)
--- a/doc/build/changelog/changelog_11.rst
+++ b/doc/build/changelog/changelog_11.rst
@@ -21,6 +21,14 @@
 .. changelog::
     :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 7eb8e800f33a27cf5b859a9628e16932eab3caa1..9ad99ae9f467a17af59c30a52751f7589b8db8bc 100644 (file)
--- 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 969411481cc10ed950b23c144be0450cc4fc789c..2ef0a5adbc446b72a5da8514aad7bd5ebddd757a 100644 (file)
--- 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 aa5be57ff11433363e1d9e9f5ec8b1ae0347d4bb..571bbbda31fdde0482786015c398ef57cf8b68ec 100644 (file)
--- 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):