diff options
| -rw-r--r-- | doc/build/changelog/changelog_11.rst | 8 | ||||
| -rw-r--r-- | doc/build/changelog/migration_11.rst | 9 | ||||
| -rw-r--r-- | doc/build/orm/extensions/mutable.rst | 7 | ||||
| -rw-r--r-- | lib/sqlalchemy/ext/mutable.py | 42 |
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): |