Mutation Tracking

A typical example of a “mutable” structure is a Python dictionary. Following the example introduced in , we begin with a custom type that marshals Python dictionaries into JSON strings before being persisted:

The usage of is only for the purposes of example. The sqlalchemy.ext.mutable extension can be used with any type whose target Python type may be mutable, including , ARRAY, etc.

When using the extension, the value itself tracks all parents which reference it. Below, we illustrate a simple version of the MutableDict dictionary object, which applies the mixin to a plain Python dictionary:

from sqlalchemy.ext.mutable import Mutable
class MutableDict(Mutable, dict):
    @classmethod
    def coerce(cls, key, value):
        "Convert plain dictionaries to MutableDict."
        if not isinstance(value, MutableDict):
            if isinstance(value, dict):
                return MutableDict(value)
            # this call will raise ValueError
            return Mutable.coerce(key, value)
        else:
            return value
    def __setitem__(self, key, value):
        "Detect dictionary set events and emit change events."
        dict.__setitem__(self, key, value)
        self.changed()
    def __delitem__(self, key):
        "Detect dictionary del events and emit change events."
        dict.__delitem__(self, key)
        self.changed()

The above dictionary class takes the approach of subclassing the Python built-in dict to produce a dict subclass which routes all mutation events through __setitem__. There are variants on this approach, such as subclassing UserDict.UserDict or collections.MutableMapping; the part that’s important to this example is that the Mutable.changed() method is called whenever an in-place change to the datastructure takes place.

We also redefine the method which will be used to convert any values that are not instances of MutableDict, such as the plain dictionaries returned by the json module, into the appropriate type. Defining this method is optional; we could just as well created our JSONEncodedDict such that it always returns an instance of MutableDict, and additionally ensured that all calling code uses MutableDict explicitly. When Mutable.coerce() is not overridden, any values applied to a parent object which are not instances of the mutable type will raise a ValueError.

Our new MutableDict type offers a class method which we can use within column metadata to associate with types. This method grabs the given type object or class and associates a listener that will detect all future mappings of this type, applying event listening instrumentation to the mapped attribute. Such as, with classical table metadata:

from sqlalchemy import Table, Column, Integer
my_data = Table('my_data', metadata,
    Column('id', Integer, primary_key=True),
    Column('data', MutableDict.as_mutable(JSONEncodedDict))
)

Above, Mutable.as_mutable() returns an instance of JSONEncodedDict (if the type object was not an instance already), which will intercept any attributes which are mapped against this type. Below we establish a simple mapping against the my_data table:

from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
class Base(DeclarativeBase):
    pass
class MyDataClass(Base):
    __tablename__ = 'my_data'
    id: Mapped[int] = mapped_column(primary_key=True)
    data: Mapped[dict[str, str]] = mapped_column(MutableDict.as_mutable(JSONEncodedDict))

The MyDataClass.data member will now be notified of in place changes to its value.

Any in-place changes to the MyDataClass.data member will flag the attribute as “dirty” on the parent object:

>>> from sqlalchemy.orm import Session
>>> sess = Session(some_engine)
>>> m1 = MyDataClass(data={'value1':'foo'})
>>> sess.add(m1)
>>> sess.commit()
>>> m1.data['value1'] = 'bar'
>>> assert m1 in sess.dirty
True

The MutableDict can be associated with all future instances of JSONEncodedDict in one step, using . This is similar to Mutable.as_mutable() except it will intercept all occurrences of MutableDict in all mappings unconditionally, without the need to declare it individually:

The key to the sqlalchemy.ext.mutable extension relies upon the placement of a weakref.WeakKeyDictionary upon the value object, which stores a mapping of parent mapped objects keyed to the attribute name under which they are associated with this value. WeakKeyDictionary objects are not picklable, due to the fact that they contain weakrefs and function callbacks. In our case, this is a good thing, since if this dictionary were picklable, it could lead to an excessively large pickle size for our value objects that are pickled by themselves outside of the context of the parent. The developer responsibility here is only to provide a __getstate__ method that excludes the collection from the pickle stream:

class MyMutableType(Mutable):
        d = self.__dict__.copy()
        d.pop('_parents', None)
        return d

With our dictionary example, we need to return the contents of the dict itself (and also restore them on __setstate__):

class MutableDict(Mutable, dict):
    # ....
    def __getstate__(self):
        return dict(self)
    def __setstate__(self, state):
        self.update(state)

In the case that our mutable value object is pickled as it is attached to one or more parent objects that are also part of the pickle, the Mutable mixin will re-establish the collection on each value object as the owning parents themselves are unpickled.

The event handler may be used to receive an event when a mutable scalar emits a change event. This event handler is called when the flag_modified() function is called from within the mutable extension:

from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy import event
class Base(DeclarativeBase):
    pass
class MyDataClass(Base):
    __tablename__ = 'my_data'
    id: Mapped[int] = mapped_column(primary_key=True)
    data: Mapped[dict[str, str]] = mapped_column(MutableDict.as_mutable(JSONEncodedDict))
@event.listens_for(MyDataClass.data, "modified")
def modified_json(instance, initiator):
    print("json value modified:", instance.data)

Composites are a special ORM feature which allow a single scalar attribute to be assigned an object value which represents information “composed” from one or more columns from the underlying mapped table. The usual example is that of a geometric “point”, and is introduced in Composite Column Types.

As is the case with , the user-defined composite class subclasses MutableComposite as a mixin, and detects and delivers change events to its parents via the method. In the case of a composite class, the detection is usually via the usage of the special Python method __setattr__(). In the example below, we expand upon the Point class introduced in Composite Column Types to include in its bases and to route attribute set events via __setattr__ to the MutableComposite.changed() method:

import dataclasses
from sqlalchemy.ext.mutable import MutableComposite
@dataclasses.dataclass
class Point(MutableComposite):
    x: int
    y: int
    def __setattr__(self, key, value):
        "Intercept set events"
        # set the attribute
        object.__setattr__(self, key, value)
        # alert all parents to the change
        self.changed()

The class makes use of class mapping events to automatically establish listeners for any usage of composite() that specifies our Point type. Below, when Point is mapped to the Vertex class, listeners are established which will route change events from Point objects to each of the Vertex.start and Vertex.end attributes:

Any in-place changes to the Vertex.start or Vertex.end members will flag the attribute as “dirty” on the parent object:


>>> sess = Session(engine)
>>> v1 = Vertex(start=Point(3, 4), end=Point(12, 15))
>>> sess.add(v1)
sql>>> sess.flush()
BEGIN (implicit)
INSERT INTO vertices (x1, y1, x2, y2) VALUES (?, ?, ?, ?)
[...] (3, 4, 12, 15)
>>> v1.end.x = 8
>>> assert v1 in sess.dirty
True
sql>>> sess.commit()
UPDATE vertices SET x2=? WHERE vertices.id = ?
[...] (8, 1)
COMMIT

The MutableBase.coerce() method is also supported on composite types. In the case of , the MutableBase.coerce() method is only called for attribute set operations, not load operations. Overriding the method is essentially equivalent to using a validates() validation routine for all attributes which make use of the custom composite type:

@dataclasses.dataclass
class Point(MutableComposite):
    # other Point methods
    # ...
    def coerce(cls, key, value):
        if isinstance(value, tuple):
            value = Point(*value)
        elif not isinstance(value, Point):
            raise ValueError("tuple or Point expected")
        return value

As is the case with Mutable, the helper class uses a weakref.WeakKeyDictionary available via the MutableBase._parents() attribute which isn’t picklable. If we need to pickle instances of Point or its owning class Vertex, we at least need to define a __getstate__ that doesn’t include the _parents dictionary. Below we define both a __getstate__ and a __setstate__ that package up the minimal form of our Point class:

@dataclasses.dataclass
class Point(MutableComposite):
    # ...
    def __getstate__(self):
        return self.x, self.y
    def __setstate__(self, state):
        self.x, self.y = state

As with , the MutableComposite augments the pickling process of the parent’s object-relational state so that the collection is restored to all Point objects.

class sqlalchemy.ext.mutable.MutableBase

Members

, coerce()

Common base class to and MutableComposite.

attribute _parents

Dictionary of parent object’s InstanceState->attribute name on the parent.

This attribute is a so-called “memoized” property. It initializes itself with a new weakref.WeakKeyDictionary the first time it is accessed, returning the same object upon subsequent access.

Changed in version 1.4: the is now used as the key in the weak dictionary rather than the instance itself.
classmethod sqlalchemy.ext.mutable.MutableBase.coerce(key: str, value: Any) → Optional[Any]

Given a value, coerce it into the target type.

Can be overridden by custom subclasses to coerce incoming data into a particular type.

By default, raises ValueError.

This method is called in different scenarios depending on if the parent class is of type or of type MutableComposite. In the case of the former, it is called for both attribute-set operations as well as during ORM loading operations. For the latter, it is only called during attribute-set operations; the mechanics of the construct handle coercion during load operations.
- Parameters:
  - key – string name of the ORM-mapped attribute being set.
  - value – the incoming value.
  Returns:
  
  the method should return the coerced value, or raise ValueError if the coercion cannot be completed.

class sqlalchemy.ext.mutable.Mutable

Mixin that defines transparent propagation of change events to a parent object.

See the example in Establishing Mutability on Scalar Column Values for usage information.

Members

, _listen_on_attribute(), , as_mutable(), , associate_with_attribute(), , coerce()

Class signature

class (sqlalchemy.ext.mutable.MutableBase)

classmethod _get_listen_keys(attribute: QueryableAttribute[Any]) → Set[str]

inherited from the sqlalchemy.ext.mutable.MutableBase._get_listen_keys method of

Given a descriptor attribute, return a set() of the attribute keys which indicate a change in the state of this attribute.

This is normally just set([attribute.key]), but can be overridden to provide for additional keys. E.g. a MutableComposite augments this set with the attribute keys associated with the columns that comprise the composite value.

This collection is consulted in the case of intercepting the and InstanceEvents.refresh_flush() events, which pass along a list of attribute names that have been refreshed; the list is compared against this set to determine if action needs to be taken.

New in version 1.0.5.
classmethod _listen_on_attribute(attribute: QueryableAttribute[Any], coerce: bool, parent_cls: _ExternalEntityType[Any]) → None

inherited from the sqlalchemy.ext.mutable.MutableBase._listen_on_attribute method of

Establish this type as a mutation listener for the given mapped descriptor.
inherited from the sqlalchemy.ext.mutable.MutableBase._parents attribute of MutableBase

Dictionary of parent object’s ->attribute name on the parent.

This attribute is a so-called “memoized” property. It initializes itself with a new weakref.WeakKeyDictionary the first time it is accessed, returning the same object upon subsequent access.

Changed in version 1.4: the InstanceState is now used as the key in the weak dictionary rather than the instance itself.
classmethod as_mutable(sqltype: TypeEngine) →

Associate a SQL type with this mutable Python type.

This establishes listeners that will detect ORM mappings against the given type, adding mutation event trackers to those mappings.

The type is returned, unconditionally as an instance, so that as_mutable() can be used inline:
```
Table('mytable', metadata,
    Column('id', Integer, primary_key=True),
    Column('data', MyMutableType.as_mutable(PickleType))
)
```
Note that the returned type is always an instance, even if a class is given, and that only columns which are declared specifically with that type instance receive additional instrumentation.

To associate a particular mutable type with all occurrences of a particular type, use the classmethod of the particular Mutable subclass to establish a global association.

Warning

The listeners established by this method are global to all mappers, and are not garbage collected. Only use for types that are permanent to an application, not with ad-hoc types else this will cause unbounded growth in memory usage.
classmethod sqlalchemy.ext.mutable.Mutable.associate_with(sqltype: type) → None

Associate this wrapper with all future mapped columns of the given type.

This is a convenience method that calls associate_with_attribute automatically.

Warning

The listeners established by this method are global to all mappers, and are not garbage collected. Only use for types that are permanent to an application, not with ad-hoc types else this will cause unbounded growth in memory usage.
classmethod sqlalchemy.ext.mutable.Mutable.associate_with_attribute(attribute: [_O]) → None

Establish this type as a mutation listener for the given mapped descriptor.
method sqlalchemy.ext.mutable.Mutable.changed() → None

Subclasses should call this method whenever change events occur.
classmethod coerce(key: str, value: Any) → Optional[Any]

inherited from the MutableBase.coerce() method of

Given a value, coerce it into the target type.

Can be overridden by custom subclasses to coerce incoming data into a particular type.

By default, raises ValueError.

This method is called in different scenarios depending on if the parent class is of type Mutable or of type . In the case of the former, it is called for both attribute-set operations as well as during ORM loading operations. For the latter, it is only called during attribute-set operations; the mechanics of the composite() construct handle coercion during load operations.
- Parameters:
  - key – string name of the ORM-mapped attribute being set.
  - value – the incoming value.
  Returns:
  
  the method should return the coerced value, or raise ValueError if the coercion cannot be completed.

class sqlalchemy.ext.mutable.MutableComposite

Mixin that defines transparent propagation of change events on a SQLAlchemy “composite” object to its owning parent or parents.

See the example in for usage information.

Members

changed()

Class signature

class (sqlalchemy.ext.mutable.MutableBase)

method changed() → None

Subclasses should call this method whenever change events occur.

class sqlalchemy.ext.mutable.MutableDict

A dictionary type that implements Mutable.

The 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 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 that provides appropriate coercion to the values placed in the dictionary so that they too are “mutable”, and emit events up to their parent structure.