Отслеживание мутаций¶

Установление изменяемости значений скалярных столбцов¶

Типичным примером «изменяемой» структуры является словарь Python. Следуя примеру, представленному в Объекты типов данных SQL, мы начнем с пользовательского типа, который маршализирует словари Python в строки JSON перед сохранением:

from sqlalchemy.types import TypeDecorator, VARCHAR
import json

class JSONEncodedDict(TypeDecorator):
    "Represents an immutable structure as a json-encoded string."

    impl = VARCHAR

    def process_bind_param(self, value, dialect):
        if value is not None:
            value = json.dumps(value)
        return value

    def process_result_value(self, value, dialect):
        if value is not None:
            value = json.loads(value)
        return value

Использование json приведено только для примера. Расширение sqlalchemy.ext.mutable может использоваться с любым типом, целевой тип которого в Python может быть мутабельным, включая PickleType, ARRAY и т.д.

При использовании расширения sqlalchemy.ext.mutable само значение отслеживает всех родителей, которые на него ссылаются. Ниже мы проиллюстрируем простую версию словарного объекта MutableDict, которая применяет миксин Mutable к обычному словарю Python:

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()

Приведенный выше класс словаря использует подход, заключающийся в подклассификации встроенного в Python dict для создания подкласса dict, который направляет все события мутации через __setitem__. Существуют варианты такого подхода, например, подкласс UserDict.UserDict или collections.MutableMapping; для данного примера важно то, что метод Mutable.changed() вызывается всякий раз, когда происходит изменение структуры данных на месте.

Мы также переопределили метод Mutable.coerce(), который будет использоваться для преобразования в соответствующий тип любых значений, не являющихся экземплярами MutableDict, например, простых словарей, возвращаемых модулем json. Определение этого метода необязательно; с таким же успехом мы могли бы создать наш JSONEncodedDict так, чтобы он всегда возвращал экземпляр MutableDict, и дополнительно убедиться, что весь вызывающий код явно использует MutableDict. Если Mutable.coerce() не переопределен, то любые значения, применяемые к родительскому объекту, не являющиеся экземплярами мутабельного типа, будут вызывать ошибку ValueError.

Наш новый тип MutableDict предлагает метод класса Mutable.as_mutable(), который мы можем использовать в метаданных столбцов для связи с типами. Этот метод берет объект или класс данного типа и создает слушатель, который будет обнаруживать все будущие сопоставления этого типа, применяя инструментарий прослушивания событий к сопоставленному атрибуту. Например, при использовании классических метаданных таблицы:

from sqlalchemy import Table, Column, Integer

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

Выше Mutable.as_mutable() возвращает экземпляр JSONEncodedDict (если объект типа еще не был экземпляром), который перехватывает все атрибуты, сопоставленные с этим типом. Ниже мы создадим простое отображение на таблицу my_data:

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))

Теперь член MyDataClass.data будет уведомляться об изменении его значения на месте.

При любом изменении на месте члена MyDataClass.data атрибут будет помечен как «грязный» на родительском объекте:

>>> 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

С помощью MutableDict можно связать все будущие экземпляры JSONEncodedDict за один шаг, используя Mutable.associate_with(). Это аналогично Mutable.as_mutable(), за исключением того, что он будет перехватывать все вхождения MutableDict во всех отображениях безоговорочно, без необходимости объявлять его отдельно:

from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column

MutableDict.associate_with(JSONEncodedDict)

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(JSONEncodedDict)

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

class MutableDict(Mutable, dict):
    # ....

    def __getstate__(self):
        return dict(self)

    def __setstate__(self, state):
        self.update(state)

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)

Установление мутабельности композитов¶

Композиты - это специальная функция ORM, позволяющая присваивать одному скалярному атрибуту объектное значение, представляющее собой информацию, «составленную» из одного или нескольких столбцов базовой таблицы сопоставления. Обычным примером является геометрическая «точка», которая представлена в Типы составных колонн.

Как и в случае с Mutable, определяемый пользователем составной класс подклассифицирует MutableComposite в качестве миксина и обнаруживает и передает события изменения своим родителям с помощью метода MutableComposite.changed(). В случае составного класса обнаружение обычно осуществляется с помощью специального метода Python __setattr__(). В приведенном ниже примере мы расширяем класс Point, представленный в Типы составных колонн, чтобы включить MutableComposite в его основы и направить события набора атрибутов через __setattr__ в метод MutableComposite.changed():

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()

Класс MutableComposite использует события сопоставления классов для автоматического создания слушателей для любого использования composite(), указывающего на наш тип Point. Ниже, когда Point сопоставляется с классом Vertex, устанавливаются слушатели, которые будут направлять события изменения от объектов Point к каждому из атрибутов Vertex.start и Vertex.end:

from sqlalchemy.orm import DeclarativeBase, Mapped
from sqlalchemy.orm import composite, mapped_column

class Base(DeclarativeBase):
    pass


class Vertex(Base):
    __tablename__ = "vertices"

    id: Mapped[int] = mapped_column(primary_key=True)

    start: Mapped[Point] = composite(mapped_column("x1"), mapped_column("y1"))
    end: Mapped[Point] = composite(mapped_column("x2"), mapped_column("y2"))

    def __repr__(self):
        return f"Vertex(start={self.start}, end={self.end})"

При любом изменении на месте членов Vertex.start или Vertex.end атрибут будет помечен как «грязный» на родительском объекте:

>>> from sqlalchemy.orm import Session
>>> 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

@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

@dataclasses.dataclass
class Point(MutableComposite):
    # ...

    def __getstate__(self):
        return self.x, self.y

    def __setstate__(self, state):
        self.x, self.y = state

Справочник по API¶

class sqlalchemy.ext.mutable.MutableBase¶

Members

_parents, coerce()

Общий базовый класс для Mutable и MutableComposite.

attribute sqlalchemy.ext.mutable.MutableBase._parents¶

Словарь имен атрибутов родительского объекта InstanceState-> на родителе.

Этот атрибут является так называемым «мемоизированным» свойством. При первом обращении к нему он инициализируется новым объектом weakref.WeakKeyDictionary, возвращая при последующих обращениях тот же объект.

Изменено в версии 1.4: В качестве ключа в слабом словаре теперь используется InstanceState, а не сам экземпляр.

classmethod sqlalchemy.ext.mutable.MutableBase.coerce(key: str, value: Any) → Optional[Any]¶

Задав значение, привести его к целевому типу.

Может переопределяться пользовательскими подклассами для принудительного приведения входящих данных к определенному типу.

По умолчанию поднимает ValueError.

Этот метод вызывается в различных сценариях в зависимости от того, является ли родительский класс типом Mutable или типом MutableComposite. В первом случае он вызывается как при операциях с набором атрибутов, так и при загрузке ORM. Во втором случае он вызывается только при операциях набора атрибутов; при загрузке принуждение выполняется механикой конструкции composite().

Параметры:

• key – строковое имя устанавливаемого атрибута ORM-mapped.

• value – входящее значение.

Результат:

метод должен вернуть принудительное значение, либо выдать сообщение ValueError, если принуждение не может быть завершено.

class sqlalchemy.ext.mutable.Mutable¶

Миксин, определяющий прозрачное распространение событий изменения на родительский объект.

Информацию об использовании см. в примере в Установление изменяемости значений скалярных столбцов.

Members

_get_listen_keys(), _listen_on_attribute(), _parents, as_mutable(), associate_with(), associate_with_attribute(), changed(), coerce()

Классическая подпись.

класс sqlalchemy.ext.mutable.Mutable (sqlalchemy.ext.mutable.MutableBase)

classmethod sqlalchemy.ext.mutable.Mutable._get_listen_keys(attribute: QueryableAttribute[Any]) → Set[str]¶

наследуется от sqlalchemy.ext.mutable.MutableBase._get_listen_keys метода MutableBase

Если задан атрибут дескриптора, то возвращается set() ключей атрибута, которые указывают на изменение состояния этого атрибута.

Обычно это просто set([attribute.key]), но может быть переопределено для обеспечения дополнительных ключей. Например, MutableComposite дополняет этот набор ключами атрибутов, связанных со столбцами, составляющими составное значение.

Эта коллекция используется при перехвате событий InstanceEvents.refresh() и InstanceEvents.refresh_flush(), которые передают список имен атрибутов, которые были обновлены; список сравнивается с этим набором, чтобы определить, нужно ли предпринимать какие-либо действия.

classmethod sqlalchemy.ext.mutable.Mutable._listen_on_attribute(attribute: QueryableAttribute[Any], coerce: bool, parent_cls: _ExternalEntityType[Any]) → None¶

наследуется от sqlalchemy.ext.mutable.MutableBase._listen_on_attribute метода MutableBase

Устанавливает данный тип в качестве слушателя мутаций для заданного сопоставленного дескриптора.

attribute sqlalchemy.ext.mutable.Mutable._parents¶

наследуется от sqlalchemy.ext.mutable.MutableBase._parents атрибута MutableBase

Словарь имен атрибутов родительского объекта InstanceState-> на родителе.

Этот атрибут является так называемым «мемоизированным» свойством. При первом обращении к нему он инициализируется новым объектом weakref.WeakKeyDictionary, возвращая при последующих обращениях тот же объект.

Изменено в версии 1.4: В качестве ключа в слабом словаре теперь используется InstanceState, а не сам экземпляр.

classmethod sqlalchemy.ext.mutable.Mutable.as_mutable(sqltype: TypeEngine) → TypeEngine¶

Связать тип SQL с данным мутабельным типом Python.

При этом устанавливаются слушатели, которые будут обнаруживать ORM-сопоставления с заданным типом и добавлять к этим сопоставлениям отслеживатели событий мутации.

Тип возвращается, безусловно, как экземпляр, так что as_mutable() может быть использован inline:

Table('mytable', metadata,
    Column('id', Integer, primary_key=True),
    Column('data', MyMutableType.as_mutable(PickleType))
)

Обратите внимание, что возвращаемый тип всегда является экземпляром, даже если указан класс, и что дополнительное инструментирование получают только те столбцы, которые объявлены именно с этим экземпляром типа.

Чтобы связать конкретный изменяемый тип со всеми вхождениями конкретного типа, используйте метод класса Mutable.associate_with() конкретного подкласса Mutable для установления глобальной ассоциации.

Предупреждение

Слушатели, установленные этим методом, являются глобальными для всех отображателей и не собираются в мусор. Используйте as_mutable() только для типов, которые являются постоянными для приложения, а не для специальных типов, иначе это приведет к неограниченному росту использования памяти.

classmethod sqlalchemy.ext.mutable.Mutable.associate_with(sqltype: type) → None¶

Связывает эту обертку со всеми будущими отображаемыми столбцами заданного типа.

Это удобный метод, который автоматически вызывает associate_with_attribute.

Предупреждение

Слушатели, установленные этим методом, являются глобальными для всех отображателей и не собираются в мусор. Используйте associate_with() только для типов, которые являются постоянными для приложения, а не для специальных типов, иначе это приведет к неограниченному росту использования памяти.

classmethod sqlalchemy.ext.mutable.Mutable.associate_with_attribute(attribute: InstrumentedAttribute[_O]) → None¶

Устанавливает данный тип в качестве слушателя мутаций для заданного сопоставленного дескриптора.

method sqlalchemy.ext.mutable.Mutable.changed() → None¶

Подклассы должны вызывать этот метод каждый раз, когда происходят события изменения.

classmethod sqlalchemy.ext.mutable.Mutable.coerce(key: str, value: Any) → Optional[Any]¶

наследуется от MutableBase.coerce() метода MutableBase

Задав значение, привести его к целевому типу.

Может переопределяться пользовательскими подклассами для принудительного приведения входящих данных к определенному типу.

По умолчанию поднимает ValueError.

Этот метод вызывается в различных сценариях в зависимости от того, является ли родительский класс типом Mutable или типом MutableComposite. В первом случае он вызывается как при операциях с набором атрибутов, так и при загрузке ORM. Во втором случае он вызывается только при операциях набора атрибутов; при загрузке принуждение выполняется механикой конструкции composite().

Параметры:

• key – строковое имя устанавливаемого атрибута ORM-mapped.

• value – входящее значение.

Результат:

метод должен вернуть принудительное значение, либо выдать сообщение ValueError, если принуждение не может быть завершено.

class sqlalchemy.ext.mutable.MutableComposite¶

Миксин, определяющий прозрачное распространение событий изменения «составного» объекта SQLAlchemy на его родителя или родителей.

Информацию об использовании см. в примере в Установление мутабельности композитов.

Members

changed()

Классическая подпись.

класс sqlalchemy.ext.mutable.MutableComposite (sqlalchemy.ext.mutable.MutableBase)

method sqlalchemy.ext.mutable.MutableComposite.changed() → None¶

Подклассы должны вызывать этот метод каждый раз, когда происходят события изменения.

class sqlalchemy.ext.mutable.MutableDict¶

Тип словаря, реализующий Mutable.

Объект MutableDict реализует словарь, который при изменении содержимого словаря, в том числе при добавлении или удалении значений, будет выдавать базовому отображению события изменения.

Обратите внимание, что MutableDict не **** применяет отслеживание изменений к самим значениям внутри словаря. Поэтому он не является достаточным решением для случая отслеживания глубоких изменений в рекурсивной структуре словаря, например, в структуре JSON. Для поддержки этого случая следует создать подкласс MutableDict, обеспечивающий соответствующее принуждение к значениям, помещенным в словарь, чтобы они тоже были «мутабельными» и выдавали события вплоть до родительской структуры.

См.также

MutableList

MutableSet

Members

clear(), coerce(), pop(), popitem(), setdefault(), update()

Классическая подпись.

класс sqlalchemy.ext.mutable.MutableDict (sqlalchemy.ext.mutable.Mutable, builtins.dict, typing.Generic)

method sqlalchemy.ext.mutable.MutableDict.clear() → None.  Remove all items from D.¶

classmethod sqlalchemy.ext.mutable.MutableDict.coerce(key: str, value: Any) → sqlalchemy.ext.mutable.MutableDict[sqlalchemy.ext.mutable._KT, sqlalchemy.ext.mutable._VT] | None¶

Преобразование обычного словаря в экземпляр данного класса.

method sqlalchemy.ext.mutable.MutableDict.pop(k[, d]) → v, remove specified key and return the corresponding value.¶

Если ключ не найден, возвращается значение по умолчанию, если оно задано; в противном случае выдается ошибка KeyError.

method sqlalchemy.ext.mutable.MutableDict.popitem() → Tuple[_KT, _VT]¶

Удалить и вернуть пару (ключ, значение) в виде кортежа.

Пары возвращаются в порядке LIFO (last-in, first-out). Если dict пуст, возникает ошибка KeyError.

method sqlalchemy.ext.mutable.MutableDict.setdefault(*arg)¶

Вставить ключ со значением по умолчанию, если ключ отсутствует в словаре.

Возвращает значение для ключа, если ключ находится в словаре, в противном случае - значение по умолчанию.

method sqlalchemy.ext.mutable.MutableDict.update([E, ]**F) → None.  Update D from dict/iterable E and F.¶

Если E присутствует и имеет метод .keys(), то выполняется: for k in E: D[k] = E[k] Если E присутствует и не имеет метода .keys(), то делается: for k, v in E: D[k] = v В любом случае за этим следует: for k in F: D[k] = F[k]

class sqlalchemy.ext.mutable.MutableList¶

Тип списка, реализующий Mutable.

Объект MutableList реализует список, который будет выдавать события изменения базовому отображению при изменении содержимого списка, в том числе при добавлении или удалении значений.

Обратите внимание, что MutableList не **** применяет отслеживание изменений к самим значениям внутри списка. Поэтому он не является достаточным решением для случая отслеживания глубоких изменений в рекурсивной мутабельной структуре, такой как JSON-структура. Для поддержки этого случая следует создать подкласс MutableList, обеспечивающий соответствующее принуждение к значениям, помещенным в словарь, чтобы они тоже были «мутабельными», и выдающий события вплоть до родительской структуры.

См.также

MutableDict

MutableSet

Members

append(), clear(), coerce(), extend(), insert(), is_iterable(), is_scalar(), pop(), remove(), reverse(), sort()

Классическая подпись.

класс sqlalchemy.ext.mutable.MutableList (sqlalchemy.ext.mutable.Mutable, builtins.list, typing.Generic)

method sqlalchemy.ext.mutable.MutableList.append(x: _T) → None¶

Добавляет объект в конец списка.

method sqlalchemy.ext.mutable.MutableList.clear() → None¶

Удалить все элементы из списка.

classmethod sqlalchemy.ext.mutable.MutableList.coerce(key: str, value: Union[MutableList[_T], _T]) → Optional[MutableList[_T]]¶

Преобразование обычного списка в экземпляр данного класса.

method sqlalchemy.ext.mutable.MutableList.extend(x: Iterable[_T]) → None¶

Расширение списка путем добавления элементов из итерируемой таблицы.

method sqlalchemy.ext.mutable.MutableList.insert(i: SupportsIndex, x: _T) → None¶

Вставить объект перед индексом.

method sqlalchemy.ext.mutable.MutableList.is_iterable(value: Union[_T, Iterable[_T]]) → TypeGuard[Iterable[_T]]¶

method sqlalchemy.ext.mutable.MutableList.is_scalar(value: Union[_T, Iterable[_T]]) → TypeGuard[_T]¶

method sqlalchemy.ext.mutable.MutableList.pop(*arg: SupportsIndex) → _T¶

Удаление и возврат элемента по индексу (по умолчанию последний).

Вызывает ошибку IndexError, если список пуст или индекс выходит за пределы диапазона.

method sqlalchemy.ext.mutable.MutableList.remove(i: _T) → None¶

Удалить первое вхождение значения.

Вызывает ошибку ValueError, если значение отсутствует.

method sqlalchemy.ext.mutable.MutableList.reverse() → None¶

Реверс НА МЕСТЕ.

method sqlalchemy.ext.mutable.MutableList.sort(**kw: Any) → None¶

Отсортировать список по возрастанию и вернуть None.

Сортировка является in-place (т.е. модифицируется сам список) и стабильной (т.е. сохраняется порядок следования двух одинаковых элементов).

Если задана ключевая функция, то применить ее один раз к каждому элементу списка и отсортировать их по возрастанию или убыванию в соответствии со значениями функции.

Флаг reverse может быть установлен для сортировки в порядке убывания.

class sqlalchemy.ext.mutable.MutableSet¶

Тип множества, реализующий Mutable.

Объект MutableSet реализует набор, который будет выдавать события изменения базовому отображению при изменении содержимого набора, в том числе при добавлении или удалении значений.

Заметим, что MutableSet не **** применяет отслеживание изменений к самим значениям внутри множества. Поэтому он не является достаточным решением для случая, когда необходимо отследить глубокие изменения в рекурсивной мутабельной структуре. Для поддержки этого случая следует создать подкласс MutableSet, обеспечивающий соответствующее принуждение к значениям, помещенным в словарь, чтобы они тоже были «мутабельными», и испускающий события вплоть до их родительской структуры.

См.также

MutableDict

MutableList

Members

add(), clear(), coerce(), difference_update(), discard(), intersection_update(), pop(), remove(), symmetric_difference_update(), update()

Классическая подпись.

класс sqlalchemy.ext.mutable.MutableSet (sqlalchemy.ext.mutable.Mutable, builtins.set, typing.Generic)

method sqlalchemy.ext.mutable.MutableSet.add(elem: _T) → None¶

Добавить элемент в набор.

Это не имеет эффекта, если элемент уже присутствует.

method sqlalchemy.ext.mutable.MutableSet.clear() → None¶

Удалить все элементы из данного множества.

classmethod sqlalchemy.ext.mutable.MutableSet.coerce(index: str, value: Any) → Optional[MutableSet[_T]]¶

Преобразование простого набора в экземпляр данного класса.

method sqlalchemy.ext.mutable.MutableSet.difference_update(*arg: Iterable[Any]) → None¶

Удалить из данного множества все элементы другого множества.

method sqlalchemy.ext.mutable.MutableSet.discard(elem: _T) → None¶

Удалить элемент из множества, если он является его членом.

Если элемент не является членом, то ничего не делать.

method sqlalchemy.ext.mutable.MutableSet.intersection_update(*arg: Iterable[Any]) → None¶

Обновить множество пересечением себя и другого множества.

method sqlalchemy.ext.mutable.MutableSet.pop(*arg: Any) → _T¶

Удалить и вернуть произвольный элемент множества. Если набор пуст, то возникает ошибка KeyError.

method sqlalchemy.ext.mutable.MutableSet.remove(elem: _T) → None¶

Удалить элемент из множества; он должен быть его членом.

Если элемент не является членом, возникает ошибка KeyError.

method sqlalchemy.ext.mutable.MutableSet.symmetric_difference_update(*arg: Iterable[_T]) → None¶

Обновление множества симметричной разностью себя и другого множества.

method sqlalchemy.ext.mutable.MutableSet.update(*arg: Iterable[_T]) → None¶

Обновить множество объединением себя и других.