События ОРМ ¶

SessionEvents.before_commit()

method sqlalchemy.orm.SessionEvents.after_begin(session: Session, transaction: SessionTransaction, connection: Connection) → None¶

Выполняется после начала транзакции на соединении

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_begin')
def receive_after_begin(session, transaction, connection):
    "listen for the 'after_begin' event"

    # ... (event handling logic) ...

Параметры:

session – Цель Session.
transaction – SessionTransaction.
connection – Объект Connection, который будет использоваться для SQL-запросов.

См.также

SessionEvents.after_commit()

QueryEvents.before_compile_delete()

method sqlalchemy.orm.SessionEvents.after_bulk_delete(delete_context: _O) → None¶

Событие после вызова унаследованного метода Query.delete().

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_bulk_delete')
def receive_after_bulk_delete(delete_context):
    "listen for the 'after_bulk_delete' event"

    # ... (event handling logic) ...

# DEPRECATED calling style (pre-0.9, will be removed in a future release)
@event.listens_for(SomeSessionClassOrObject, 'after_bulk_delete')
def receive_after_bulk_delete(session, query, query_context, result):
    "listen for the 'after_bulk_delete' event"

    # ... (event handling logic) ...

Изменено в версии 0.9: Событие SessionEvents.after_bulk_delete() теперь принимает аргументы SessionEvents.after_bulk_delete.delete_context. Поддержка функций слушателя, которые принимают предыдущие сигнатуры аргументов, перечисленные выше как «устаревшие», будет удалена в одном из будущих выпусков.

Legacy Feature

Метод SessionEvents.after_bulk_delete() является унаследованным крючком события по состоянию на SQLAlchemy 2.0. Событие не участвует в вызовах 2.0 style с использованием delete(), документированных в ORM UPDATE и DELETE с пользовательскими критериями WHERE. Для использования в стиле 2.0 хук SessionEvents.do_orm_execute() будет перехватывать эти вызовы.

Параметры:: delete_context – объект «контекст удаления», который содержит подробную информацию об обновлении, включая следующие атрибуты: * session - задействованный Session * query - объект Query, на котором была вызвана эта операция обновления. * result - объект CursorResult, возвращенный в результате операции массового DELETE.

Изменено в версии 1.4: update_context больше не имеет связанного с ним объекта QueryContext.

См.также

SessionEvents.after_bulk_update()

method sqlalchemy.orm.SessionEvents.after_bulk_update(update_context: _O) → None¶

Событие после вызова унаследованного метода Query.update().

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_bulk_update')
def receive_after_bulk_update(update_context):
    "listen for the 'after_bulk_update' event"

    # ... (event handling logic) ...

# DEPRECATED calling style (pre-0.9, will be removed in a future release)
@event.listens_for(SomeSessionClassOrObject, 'after_bulk_update')
def receive_after_bulk_update(session, query, query_context, result):
    "listen for the 'after_bulk_update' event"

    # ... (event handling logic) ...

Изменено в версии 0.9: Событие SessionEvents.after_bulk_update() теперь принимает аргументы SessionEvents.after_bulk_update.update_context. Поддержка функций слушателя, которые принимают предыдущие сигнатуры аргументов, перечисленные выше как «устаревшие», будет удалена в одном из будущих выпусков.

Legacy Feature

Метод SessionEvents.after_bulk_update() является унаследованным крючком события по состоянию на SQLAlchemy 2.0. Событие не участвует в вызовах 2.0 style с использованием update(), документированных в ORM UPDATE и DELETE с пользовательскими критериями WHERE. Для использования в стиле 2.0 хук SessionEvents.do_orm_execute() будет перехватывать эти вызовы.

Параметры:: update_context – объект «контекст обновления», который содержит подробную информацию об обновлении, включая следующие атрибуты: * session - задействованный Session * query - объект Query, для которого была вызвана эта операция обновления. * values - словарь «values», который был передан в Query.update(). * result - словарь CursorResult, возвращенный в результате операции массового UPDATE.

Изменено в версии 1.4: update_context больше не имеет связанного с ним объекта QueryContext.

См.также

QueryEvents.before_compile_update()

SessionEvents.after_bulk_delete()

method sqlalchemy.orm.SessionEvents.after_commit(session: Session) → None¶

Выполняется после того, как произошла фиксация.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_commit')
def receive_after_commit(session):
    "listen for the 'after_commit' event"

    # ... (event handling logic) ...

Примечание

Хук SessionEvents.after_commit() является не per-flush, то есть Session может многократно отправлять SQL в базу данных в рамках транзакции. Для перехвата этих событий используйте события SessionEvents.before_flush(), SessionEvents.after_flush() или SessionEvents.after_flush_postexec().

Примечание

Session не находится в активной транзакции, когда вызывается событие SessionEvents.after_commit(), и поэтому не может испускать SQL. Чтобы выдать SQL, соответствующий каждой транзакции, используйте событие SessionEvents.before_commit().

Параметры:: session – Цель Session.

См.также

SessionEvents.before_commit()

SessionEvents.after_begin()

SessionEvents.before_flush()

method sqlalchemy.orm.SessionEvents.after_flush(session: Session, flush_context: UOWTransaction) → None¶

Выполняется после завершения flush, но до вызова commit.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_flush')
def receive_after_flush(session, flush_context):
    "listen for the 'after_flush' event"

    # ... (event handling logic) ...

Обратите внимание, что состояние сессии все еще находится на стадии предварительной очистки, т.е. списки „new“, „dirty“ и „deleted“ все еще показывают состояние до очистки, а также настройки истории для атрибутов экземпляра.

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

Это событие запускается после того, как Session выполнил SQL для модификации базы данных, но до того, как изменил свое внутреннее состояние, чтобы отразить эти изменения, включая то, что новые вставленные объекты помещаются в карту идентификации. Операции ORM, выполняемые в рамках этого события, такие как загрузка связанных элементов, могут создавать новые записи в карте идентификации, которые будут немедленно заменены, что иногда приводит к запутанным результатам. Начиная с версии 1.3.9 SQLAlchemy будет выдавать предупреждение об этом событии.

Параметры:

session – Цель Session.
flush_context – Внутренний объект UOWTransaction, который обрабатывает детали промывки.

См.также

SessionEvents.after_flush_postexec()

SessionEvents.before_flush()

method sqlalchemy.orm.SessionEvents.after_flush_postexec(session: Session, flush_context: UOWTransaction) → None¶

Выполняется после завершения промывки и после наступления состояния post-exec.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_flush_postexec')
def receive_after_flush_postexec(session, flush_context):
    "listen for the 'after_flush_postexec' event"

    # ... (event handling logic) ...

Это произойдет, когда списки „new“, „dirty“ и „deleted“ будут в окончательном состоянии. Фактический commit() может произойти или не произойти, в зависимости от того, начал ли flush свою собственную транзакцию или участвовал в более крупной транзакции.

Параметры:

session – Цель Session.
flush_context – Внутренний объект UOWTransaction, который обрабатывает детали промывки.

См.также

SessionEvents.after_flush()

method sqlalchemy.orm.SessionEvents.after_rollback(session: Session) → None¶

Выполняется после того, как произошел реальный откат DBAPI.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_rollback')
def receive_after_rollback(session):
    "listen for the 'after_rollback' event"

    # ... (event handling logic) ...

Обратите внимание, что это событие срабатывает только при фактическом откате к базе данных - оно не срабатывает каждый раз при вызове метода Session.rollback(), если транзакция, лежащая в основе DBAPI, уже была откачена. Во многих случаях Session не будет находиться в «активном» состоянии во время этого события, поскольку текущая транзакция недействительна. Чтобы получить Session, который активен после того, как произошел внешний откат, используйте событие SessionEvents.after_soft_rollback(), проверяя флаг Session.is_active.

Параметры:: session – Цель Session.

method sqlalchemy.orm.SessionEvents.after_soft_rollback(session: Session, previous_transaction: SessionTransaction) → None¶

Выполняется после любого произошедшего отката, включая «мягкие» откаты, которые фактически не эмитируются на уровне DBAPI.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_soft_rollback')
def receive_after_soft_rollback(session, previous_transaction):
    "listen for the 'after_soft_rollback' event"

    # ... (event handling logic) ...

Это касается как вложенных, так и внешних откатов, т.е. самого внутреннего отката, который вызывает метод DBAPI rollback(), а также окружающих его вызовов отката, которые только вытаскивают себя из стека транзакций.

Данный Session можно использовать для вызова SQL и Session.query() операций после внешнего отката, предварительно проверив флаг Session.is_active:

@event.listens_for(Session, "after_soft_rollback")
def do_something(session, previous_transaction):
    if session.is_active:
        session.execute("select * from some_table")

Параметры:

session – Цель Session.
previous_transaction – Объект транзакционного маркера SessionTransaction, который был только что закрыт. Текущий SessionTransaction для данного Session доступен через атрибут Session.transaction.

method sqlalchemy.orm.SessionEvents.after_transaction_create(session: Session, transaction: SessionTransaction) → None¶

Выполняется при создании нового SessionTransaction.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_transaction_create')
def receive_after_transaction_create(session, transaction):
    "listen for the 'after_transaction_create' event"

    # ... (event handling logic) ...

Это событие отличается от SessionEvents.after_begin() тем, что оно возникает для каждой транзакции SessionTransaction в целом, а не при начале транзакций на отдельных соединениях базы данных. Оно также вызывается для вложенных транзакций и субтранзакций и всегда сопровождается соответствующим событием SessionEvents.after_transaction_end() (при условии нормальной работы Session).

Параметры:

session – цель Session.
transaction – цель SessionTransaction. Чтобы определить, что это внешняя SessionTransaction, а не «субтранзакция» или SAVEPOINT, проверьте, что атрибут SessionTransaction.parent имеет значение None:: @event.listens_for(session, «after_transaction_create») def after_transaction_create(session, transaction): if transaction.parent is None: # работаем с транзакцией верхнего уровня Чтобы определить, что SessionTransaction является SAVEPOINT, используйте атрибут SessionTransaction.nested:: @event.listens_for(session, «after_transaction_create») def after_transaction_create(session, transaction): if transaction.nested: # работать с SAVEPOINT транзакцией

См.также

SessionTransaction

method sqlalchemy.orm.SessionEvents.after_transaction_end(session: Session, transaction: SessionTransaction) → None¶

Выполняется, когда заканчивается интервал SessionTransaction.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'after_transaction_end')
def receive_after_transaction_end(session, transaction):
    "listen for the 'after_transaction_end' event"

    # ... (event handling logic) ...

Это событие отличается от SessionEvents.after_commit() тем, что оно соответствует всем используемым объектам SessionTransaction, включая объекты для вложенных транзакций и субтранзакций, и всегда сопровождается соответствующим событием SessionEvents.after_transaction_create().

Параметры:

session – цель Session.
transaction – цель SessionTransaction. Чтобы определить, что это самая внешняя SessionTransaction, а не «субтранзакция» или SAVEPOINT, проверьте, что атрибут SessionTransaction.parent имеет значение None:: @event.listens_for(session, «after_transaction_create») def after_transaction_end(session, transaction): if transaction.parent is None: # работаем с транзакцией верхнего уровня Чтобы определить, является ли SessionTransaction SAVEPOINT, используйте атрибут SessionTransaction.nested:: @event.listens_for(session, «after_transaction_create») def after_transaction_end(session, transaction): if transaction.nested: # работать с SAVEPOINT транзакцией

См.также

SessionTransaction

SessionEvents.after_attach()

method sqlalchemy.orm.SessionEvents.before_attach(session: Session, instance: _O) → None¶

Выполняется перед присоединением экземпляра к сессии.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'before_attach')
def receive_before_attach(session, instance):
    "listen for the 'before_attach' event"

    # ... (event handling logic) ...

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

См.также

SessionEvents.after_commit()

method sqlalchemy.orm.SessionEvents.before_commit(session: Session) → None¶

Выполняется до вызова commit.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'before_commit')
def receive_before_commit(session):
    "listen for the 'before_commit' event"

    # ... (event handling logic) ...

Примечание

Хук SessionEvents.before_commit() является не per-flush, то есть Session может многократно отправлять SQL в базу данных в рамках транзакции. Для перехвата этих событий используйте события SessionEvents.before_flush(), SessionEvents.after_flush() или SessionEvents.after_flush_postexec().

Параметры:: session – Цель Session.

См.также

SessionEvents.after_begin()

SessionEvents.after_flush()

method sqlalchemy.orm.SessionEvents.before_flush(session: Session, flush_context: UOWTransaction, instances: Optional[Sequence[_O]]) → None¶

Выполняется до начала процесса смыва.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'before_flush')
def receive_before_flush(session, flush_context, instances):
    "listen for the 'before_flush' event"

    # ... (event handling logic) ...

Параметры:

session – Цель Session.
flush_context – Внутренний объект UOWTransaction, который обрабатывает детали промывки.
instances – Обычно None - это коллекция объектов, которые могут быть переданы методу Session.flush() (обратите внимание, что это использование устарело).

См.также

SessionEvents.after_flush_postexec()

method sqlalchemy.orm.SessionEvents.deleted_to_detached(session: Session, instance: _O) → None¶

Перехват перехода «удален - отсоединен» для определенного объекта.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'deleted_to_detached')
def receive_deleted_to_detached(session, instance):
    "listen for the 'deleted_to_detached' event"

    # ... (event handling logic) ...

Это событие вызывается, когда удаленный объект выселяется из сессии. Типичный случай, когда это происходит, это когда транзакция для Session, в которой объект был удален, фиксируется; объект переходит из состояния deleted в состояние detached.

Он также вызывается для объектов, которые были удалены в результате флеша при вызове событий Session.expunge_all() или Session.close(), а также если объект индивидуально выводится из удаленного состояния с помощью Session.expunge().

См.также

method sqlalchemy.orm.SessionEvents.deleted_to_persistent(session: Session, instance: _O) → None¶

Перехват перехода «deleted to persistent» для определенного объекта.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'deleted_to_persistent')
def receive_deleted_to_persistent(session, instance):
    "listen for the 'deleted_to_persistent' event"

    # ... (event handling logic) ...

Этот переход происходит только тогда, когда объект, который был успешно удален при флеше, восстанавливается благодаря вызову Session.rollback(). Событие не вызывается ни при каких других обстоятельствах.

См.также

method sqlalchemy.orm.SessionEvents.detached_to_persistent(session: Session, instance: _O) → None¶

Перехват перехода «detached to persistent» для определенного объекта.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'detached_to_persistent')
def receive_detached_to_persistent(session, instance):
    "listen for the 'detached_to_persistent' event"

    # ... (event handling logic) ...

Это событие является специализацией события SessionEvents.after_attach(), которое вызывается только для этого конкретного перехода. Оно вызывается обычно во время вызова Session.add(), а также во время вызова Session.delete(), если объект не был ранее связан с Session (обратите внимание, что объект, помеченный как «удаленный», остается в состоянии «persistent» до тех пор, пока не будет выполнен flush).

Примечание

Если объект становится постоянным в результате вызова Session.delete(), то при вызове этого события объект еще не помечен как удаленный. Чтобы обнаружить удаленные объекты, проверьте флаг deleted, отправленный в событие SessionEvents.persistent_to_detached() to после выполнения flush, или проверьте коллекцию Session.deleted в событии SessionEvents.before_flush(), если удаленные объекты должны быть перехвачены до выполнения flush.

Параметры:

session – цель Session
instance – экземпляр ORM-сопоставления, с которым выполняется операция.

См.также

attribute sqlalchemy.orm.SessionEvents.dispatch: _Dispatch[_ET] = <sqlalchemy.event.base.SessionEventsDispatch object>¶

ссылку обратно на класс _Dispatch.

Двунаправленный против _Dispatch._events

method sqlalchemy.orm.SessionEvents.do_orm_execute(orm_execute_state: ORMExecuteState) → None¶

Перехватывать выполнение операторов, которые происходят от имени объекта ORM Session.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'do_orm_execute')
def receive_do_orm_execute(orm_execute_state):
    "listen for the 'do_orm_execute' event"

    # ... (event handling logic) ...

Это событие вызывается для всех SQL-запросов верхнего уровня, вызываемых из метода Session.execute(), а также связанных с ним методов, таких как Session.scalars() и Session.scalar(). Начиная с версии SQLAlchemy 1.4, все ORM-запросы, выполняемые через метод Session.execute(), а также связанные с ним методы Session.scalars(), Session.scalar() и т.д. будут участвовать в этом событии. Этот крючок события не применяется к запросам, которые выполняются внутри процесса ORM flush, т.е. к процессу, описанному в Промывка.

Примечание

Крючок события SessionEvents.do_orm_execute() срабатывает только для выполнения операторов ORM, то есть тех, которые вызываются с помощью Session.execute() и подобных методов на объекте Session. Он не срабатывает для операторов, вызываемых только SQLAlchemy Core, т.е. операторов, вызываемых напрямую с помощью Connection.execute() или иным образом исходящих из объекта Engine без участия каких-либо Session. Для перехвата всех SQL-исполнений, независимо от того, используются ли API Core или ORM, смотрите крючки событий ConnectionEvents, такие как ConnectionEvents.before_execute() и ConnectionEvents.before_cursor_execute().

Кроме того, этот крючок событий не применяется к запросам, которые создаются внутри процесса ORM flush, т.е. процесса, описанного в Промывка; чтобы перехватить шаги внутри процесса flush, смотрите крючки событий, описанные в События постоянства, а также События смыва на уровне картографа.

Это событие является событием do_, то есть оно способно заменить операцию, которую обычно выполняет метод Session.execute(). Предполагаемое использование этого события включает схемы шардинга и кэширования результатов, которые могут стремиться вызвать один и тот же оператор через несколько соединений с базой данных, возвращая результат, объединенный из каждого из них, или вообще не вызывать оператор, возвращая данные из кэша.

Хук призван заменить использование метода Query._execute_and_instances, который можно было подклассифицировать до версии SQLAlchemy 1.4.

Параметры:: orm_execute_state – экземпляр ORMExecuteState, который содержит всю информацию о текущем выполнении, а также вспомогательные функции, используемые для получения другой часто необходимой информации. Подробности см. в этом объекте.

См.также

Выполнение событий - документация верхнего уровня о том, как использовать SessionEvents.do_orm_execute()

ORMExecuteState - объект, передаваемый событию SessionEvents.do_orm_execute(), который содержит всю информацию о вызываемом утверждении. Он также предоставляет интерфейс для расширения текущего оператора, опций и параметров, а также опцию, позволяющую программно вызывать оператор в любой момент.

События запросов ORM - включает примеры использования SessionEvents.do_orm_execute()

Кэширование Dogpile - пример интеграции кэширования Dogpile с ORM Session с использованием крючка событий SessionEvents.do_orm_execute().

Горизонтальное разделение - пример/расширение Horizontal Sharding полагается на крючок события SessionEvents.do_orm_execute() для вызова SQL-запроса на нескольких бэкендах и возврата объединенного результата.

Добавлено в версии 1.4.

method sqlalchemy.orm.SessionEvents.loaded_as_persistent(session: Session, instance: _O) → None¶

Перехват перехода «загружен как постоянный» для определенного объекта.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'loaded_as_persistent')
def receive_loaded_as_persistent(session, instance):
    "listen for the 'loaded_as_persistent' event"

    # ... (event handling logic) ...

Это событие вызывается в процессе загрузки ORM, и вызывается очень похоже на событие InstanceEvents.load(). Однако здесь событие связано с классом или экземпляром Session, а не с маппером или иерархией классов, и легко интегрируется с другими событиями жизненного цикла сессии. Объект гарантированно присутствует в карте идентификации сессии, когда вызывается это событие.

Примечание

Это событие вызывается в процессе загрузчика до того, как может быть завершена работа жаждущих загрузчиков, и состояние объекта может быть неполным. Кроме того, вызов операций обновления на уровне строк для объекта поместит объект в новый контекст загрузчика, вмешиваясь в существующий контекст загрузки. См. примечание к InstanceEvents.load() для получения информации об использовании параметра SessionEvents.restore_load_context, который работает так же, как и InstanceEvents.restore_load_context, для решения этого сценария.

Параметры:

session – цель Session
instance – экземпляр ORM-сопоставления, с которым выполняется операция.

См.также

method sqlalchemy.orm.SessionEvents.pending_to_persistent(session: Session, instance: _O) → None¶

Перехват перехода «pending to persistent» для определенного объекта.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'pending_to_persistent')
def receive_pending_to_persistent(session, instance):
    "listen for the 'pending_to_persistent' event"

    # ... (event handling logic) ...

Это событие вызывается в рамках процесса flush и аналогично сканированию коллекции Session.new в рамках события SessionEvents.after_flush(). Однако в данном случае объект уже был переведен в постоянное состояние на момент вызова события.

Параметры:

session – цель Session
instance – экземпляр ORM-сопоставления, с которым выполняется операция.

См.также

method sqlalchemy.orm.SessionEvents.pending_to_transient(session: Session, instance: _O) → None¶

Перехват перехода «ожидание - переход» для определенного объекта.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'pending_to_transient')
def receive_pending_to_transient(session, instance):
    "listen for the 'pending_to_transient' event"

    # ... (event handling logic) ...

Этот менее распространенный переход происходит, когда ожидающий объект, который не был удален, вытесняется из сессии; это может произойти, когда метод Session.rollback() откатывает транзакцию, или когда используется метод Session.expunge().

Параметры:

session – цель Session
instance – экземпляр ORM-сопоставления, с которым выполняется операция.

См.также

method sqlalchemy.orm.SessionEvents.persistent_to_deleted(session: Session, instance: _O) → None¶

Перехват перехода «persistent to deleted» для определенного объекта.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'persistent_to_deleted')
def receive_persistent_to_deleted(session, instance):
    "listen for the 'persistent_to_deleted' event"

    # ... (event handling logic) ...

Это событие вызывается, когда идентификатор постоянного объекта удаляется из базы данных в рамках флеша, однако объект остается связанным с Session до завершения транзакции.

Если транзакция откатывается, объект снова переходит в постоянное состояние, и вызывается событие SessionEvents.deleted_to_persistent(). Если транзакция зафиксирована, объект становится отсоединенным, что вызовет событие SessionEvents.deleted_to_detached().

Обратите внимание, что хотя метод Session.delete() является основным публичным интерфейсом для пометки объекта как удаленного, многие объекты удаляются по каскадным правилам, которые не всегда определяются до момента flush. Поэтому не существует способа поймать каждый объект, который будет удален до тех пор, пока не начнется flush. Поэтому событие SessionEvents.persistent_to_deleted() вызывается в конце flush.

См.также

method sqlalchemy.orm.SessionEvents.persistent_to_detached(session: Session, instance: _O) → None¶

Перехват перехода «persistent to detached» для определенного объекта.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'persistent_to_detached')
def receive_persistent_to_detached(session, instance):
    "listen for the 'persistent_to_detached' event"

    # ... (event handling logic) ...

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

используя такой метод, как Session.expunge() или Session.close()
Вызов метода Session.rollback(), когда объект был частью оператора INSERT для транзакции этой сессии

Параметры:

session – цель Session
instance – экземпляр ORM-сопоставления, с которым выполняется операция.
deleted – булево. Если True, указывает, что этот объект перешел в состояние detached, поскольку был помечен как удаленный и смыт.

См.также

method sqlalchemy.orm.SessionEvents.persistent_to_transient(session: Session, instance: _O) → None¶

Перехват перехода «от постоянного к переходному» для определенного объекта.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'persistent_to_transient')
def receive_persistent_to_transient(session, instance):
    "listen for the 'persistent_to_transient' event"

    # ... (event handling logic) ...

Этот менее распространенный переход происходит, когда отложенный объект, который был удален, вытесняется из сессии; это может произойти, когда метод Session.rollback() откатывает транзакцию.

Параметры:

session – цель Session
instance – экземпляр ORM-сопоставления, с которым выполняется операция.

См.также

method sqlalchemy.orm.SessionEvents.transient_to_pending(session: Session, instance: _O) → None¶

Перехват перехода «переходный в ожидающий» для определенного объекта.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeSessionClassOrObject, 'transient_to_pending')
def receive_transient_to_pending(session, instance):
    "listen for the 'transient_to_pending' event"

    # ... (event handling logic) ...

Это событие является специализацией события SessionEvents.after_attach(), которое вызывается только для данного конкретного перехода. Обычно оно вызывается во время вызова Session.add().

Параметры:

session – цель Session
instance – экземпляр ORM-сопоставления, с которым выполняется операция.

См.также

after_configured(), after_delete(), after_insert(), after_mapper_constructed(), after_update(), before_configured(), before_delete(), before_insert(), before_mapper_configured(), before_update(), dispatch, instrument_class(), mapper_configured()

События картографа¶

Крючки событий маппера охватывают события, происходящие с отдельными или несколькими объектами Mapper, которые являются центральным конфигурационным объектом, отображающим определенный пользователем класс на объект Table. Типы событий, которые происходят на уровне Mapper, включают:

Операции персистентности для каждого объекта - наиболее популярными крючками маппера являются крючки для единицы работы, такие как MapperEvents.before_insert(), MapperEvents.after_update() и т.д. Эти события отличаются от более крупнозернистых событий уровня сессии, таких как SessionEvents.before_flush(), тем, что они происходят внутри процесса flush на основе каждого объекта; в то время как более мелкозернистая деятельность над объектом более проста, доступность функций Session ограничена.
События конфигурации маппера - другой основной класс крючков маппера - это те, которые происходят при отображении класса, при завершении работы маппера и при настройке наборов мапперов для обращения друг к другу. Эти события включают MapperEvents.instrument_class(), MapperEvents.before_mapper_configured() и MapperEvents.mapper_configured() на уровне отдельных Mapper и MapperEvents.before_configured() и MapperEvents.after_configured() на уровне коллекций Mapper объектов.

Object Name	Description
MapperEvents	Определите события, характерные для сопоставлений.

class sqlalchemy.orm.MapperEvents¶

Определите события, характерные для сопоставлений.

например:

from sqlalchemy import event

def my_before_insert_listener(mapper, connection, target):
    # execute a stored procedure upon INSERT,
    # apply the value to the row to be inserted
    target.calculated_value = connection.execute(
        text("select my_special_function(%d)" % target.special_number)
    ).scalar()

# associate the listener function with SomeClass,
# to execute during the "before_insert" hook
event.listen(
    SomeClass, 'before_insert', my_before_insert_listener)

Доступные цели включают:

сопоставленные классы
несопоставленные суперклассы сопоставленных или подлежащих сопоставлению классов (с использованием флага propagate=True)
Mapper объекты
сам класс Mapper указывает на прослушивание всех картографов.

События маппера обеспечивают доступ к критическим секциям маппера, включая те, которые связаны с инструментарием объектов, загрузкой объектов и сохранением объектов. В частности, методы персистенции MapperEvents.before_insert() и MapperEvents.before_update() являются популярными местами для дополнения сохраняемого состояния - однако, эти методы работают с несколькими существенными ограничениями. Пользователю предлагается оценить методы SessionEvents.before_flush() и SessionEvents.after_flush() как более гибкие и удобные крючки для применения дополнительного состояния базы данных во время флеша.

При использовании MapperEvents для функции listen() доступны несколько модификаторов.

Параметры:

propagate=False – Когда True, слушатель событий должен быть применен ко всем наследующим мапперам и/или мапперам наследующих классов, а также к любому мапперу, который является целью этого слушателя.
raw=False – При значении True аргументом «target», передаваемым соответствующим функциям слушателя событий, будет объект управления экземпляра InstanceState, а не сам сопоставленный экземпляр.
retval=False – когда True, функция события, определенная пользователем, должна иметь возвращаемое значение, целью которого является либо управление последующим распространением события, либо иное изменение операции, выполняемой картографом. Возможными значениями возврата являются: * sqlalchemy.orm.interfaces.EXT_CONTINUE - продолжить обработку события в нормальном режиме. * sqlalchemy.orm.interfaces.EXT_STOP - отмена всех последующих обработчиков событий в цепочке. * другие значения - возвращаемое значение, заданное конкретными слушателями.

Members

Классная подпись

класс sqlalchemy.orm.MapperEvents (sqlalchemy.event.Events)

method sqlalchemy.orm.MapperEvents.after_configured() → None¶

Вызывается после того, как серия картографов была настроена.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeClass, 'after_configured')
def receive_after_configured():
    "listen for the 'after_configured' event"

    # ... (event handling logic) ...

Событие MapperEvents.after_configured() вызывается каждый раз, когда вызывается функция configure_mappers(), после того, как она выполнила свою работу. configure_mappers() обычно вызывается автоматически при первом использовании отображений, а также каждый раз, когда новые отображения становятся доступными и обнаруживается новое использование отображений.

Противопоставьте это событие событию MapperEvents.mapper_configured(), которое вызывается на основе каждого маппера во время выполнения операции конфигурирования; в отличие от этого события, когда вызывается это событие, все кросс-конфигурации (например, обратные ссылки) также будут доступны для всех мапперов, которые были в ожидании. Также в отличие от MapperEvents.before_configured(), которое вызывается до того, как серия картографов была сконфигурирована.

Это событие может только быть применено к классу Mapper, а не к отдельным отображениям или отображенным классам. Оно вызывается только для всех отображений в целом:

from sqlalchemy.orm import Mapper

@event.listens_for(Mapper, "after_configured")
def go():
    # ...

Теоретически это событие вызывается один раз для каждого приложения, но фактически оно вызывается каждый раз, когда новые отображения были затронуты вызовом configure_mappers(). Если новые отображения создаются после того, как существующие уже были использованы, это событие, скорее всего, будет вызвано снова. Чтобы гарантировать, что конкретное событие будет вызвано только один раз и не более, можно применить аргумент once=True (новый в 0.9.4):

from sqlalchemy.orm import mapper

@event.listens_for(mapper, "after_configured", once=True)
def go():
    # ...

См.также

MapperEvents.before_mapper_configured()

MapperEvents.mapper_configured()

MapperEvents.before_configured()

method sqlalchemy.orm.MapperEvents.after_delete(mapper: Mapper[_O], connection: Connection, target: _O) → None¶

Получение экземпляра объекта после того, как был выпущен оператор DELETE, соответствующий этому экземпляру.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeClass, 'after_delete')
def receive_after_delete(mapper, connection, target):
    "listen for the 'after_delete' event"

    # ... (event handling logic) ...

Примечание

это событие только относится к session flush operation и не относится к операциям ORM DML, описанным в Операции INSERT, UPDATE и DELETE с поддержкой ORM. Чтобы перехватить события ORM DML, используйте SessionEvents.do_orm_execute().

Это событие используется для выполнения дополнительных SQL-запросов на данном соединении, а также для выполнения специфических для приложения бухгалтерских операций, связанных с событием удаления.

Это событие часто вызывается для партии объектов одного класса после того, как их заявления DELETE были выпущены одновременно на предыдущем шаге.

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

События flush на уровне маппера допускают только очень ограниченные операции, только над атрибутами, локальными для обрабатываемой строки, а также позволяют выдавать любой SQL на данном Connection. Пожалуйста, прочитайте полностью примечания в События смыва на уровне картографа для рекомендаций по использованию этих методов; в целом, метод SessionEvents.before_flush() должен быть предпочтительным для общих изменений на уровне flush.

Параметры:

mapper – Mapper, который является целью этого события.
connection – Connection, используемый для выполнения операторов DELETE для данного экземпляра. Это позволяет получить доступ к текущей транзакции в целевой базе данных, специфичной для данного экземпляра.
target – удаляемый сопоставленный экземпляр. Если событие настроено с параметром raw=True, вместо него будет объект управления состоянием InstanceState, связанный с экземпляром.

Результат:

Данное событие не поддерживает никаких возвращаемых значений.

См.также

method sqlalchemy.orm.MapperEvents.after_insert(mapper: Mapper[_O], connection: Connection, target: _O) → None¶

Получение экземпляра объекта после выполнения оператора INSERT, соответствующего этому экземпляру.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeClass, 'after_insert')
def receive_after_insert(mapper, connection, target):
    "listen for the 'after_insert' event"

    # ... (event handling logic) ...

Примечание

Это событие используется для изменения состояния экземпляра только на языке Python после выполнения INSERT, а также для выполнения дополнительных SQL-запросов на данном соединении.

Это событие часто вызывается для партии объектов одного класса после того, как их операторы INSERT были выпущены одновременно на предыдущем шаге. В крайне редких случаях, когда это нежелательно, объект Mapper может быть настроен на batch=False, что приведет к тому, что партии экземпляров будут разбиты на отдельные (и более низкопроизводительные) шаги event->persist->event.

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

Параметры:

mapper – Mapper, который является целью этого события.
connection – Connection, используемый для выполнения операторов INSERT для данного экземпляра. Это позволяет получить доступ к текущей транзакции в целевой базе данных, специфичной для данного экземпляра.
target – сопоставленный экземпляр, который сохраняется. Если событие настроено с параметром raw=True, то вместо него будет объект управления состоянием InstanceState, связанный с экземпляром.

Результат:

Данное событие не поддерживает никаких возвращаемых значений.

См.также

method sqlalchemy.orm.MapperEvents.after_mapper_constructed(mapper: Mapper[_O], class_: Type[_O]) → None¶

Получите класс и маппер, когда Mapper будет полностью построен.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeClass, 'after_mapper_constructed')
def receive_after_mapper_constructed(mapper, class_):
    "listen for the 'after_mapper_constructed' event"

    # ... (event handling logic) ...

Это событие вызывается после завершения работы начального конструктора для Mapper. Это происходит после события MapperEvents.instrument_class() и после того, как Mapper выполнил начальный проход по своим аргументам для создания своей коллекции объектов MapperProperty, которые доступны через метод Mapper.get_property() и атрибут Mapper.iterate_properties.

Это событие отличается от события MapperEvents.before_mapper_configured() тем, что оно вызывается в конструкторе для Mapper, а не в процессе registry.configure(). В настоящее время только это событие подходит для обработчиков, которые хотят создать дополнительные сопоставленные классы в ответ на построение этого Mapper, которые будут частью того же шага configure при следующем запуске registry.configure().

Добавлено в версии 2.0.2.

См.также

Версионирование объектов - пример, иллюстрирующий использование события MapperEvents.before_mapper_configured() для создания новых мапперов для записи истории изменений-аудита объектов.

method sqlalchemy.orm.MapperEvents.after_update(mapper: Mapper[_O], connection: Connection, target: _O) → None¶

Получение экземпляра объекта после того, как был выпущен оператор UPDATE, соответствующий этому экземпляру.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeClass, 'after_update')
def receive_after_update(mapper, connection, target):
    "listen for the 'after_update' event"

    # ... (event handling logic) ...

Примечание

Это событие используется для изменения состояния экземпляра только на языке Python после выполнения UPDATE, а также для выполнения дополнительных SQL-запросов на данном соединении.

Этот метод вызывается для всех экземпляров, которые помечены как «грязные», даже для тех, которые не имеют чистых изменений в своих атрибутах на основе столбцов, и для которых не выполнялся оператор UPDATE. Объект помечается как «грязный», когда для любого из его атрибутов, основанных на столбцах, вызывается операция «set attribute» или когда изменяется любая из его коллекций. Если во время обновления ни один атрибут на основе столбцов не имеет чистых изменений, оператор UPDATE не будет выпущен. Это означает, что отправка экземпляра в MapperEvents.after_update() не является не гарантией того, что был выпущен оператор UPDATE.

Чтобы определить, изменились ли атрибуты объекта на основе столбцов в чистом виде, что привело к появлению оператора UPDATE, используйте object_session(instance).is_modified(instance, include_collections=False).

Это событие часто вызывается для партии объектов одного класса после того, как их заявления UPDATE были выпущены одновременно на предыдущем шаге. В крайне редких случаях, когда это нежелательно, Mapper можно настроить batch=False, что приведет к тому, что партии экземпляров будут разбиты на отдельные (и более низкопроизводительные) шаги event->persist->event.

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

Параметры:

mapper – Mapper, который является целью этого события.
connection – Connection, используемый для выпуска UPDATE-запросов для данного экземпляра. Это позволяет получить доступ к текущей транзакции в целевой базе данных, специфичной для данного экземпляра.
target – сопоставленный экземпляр, который сохраняется. Если событие настроено с параметром raw=True, то вместо него будет объект управления состоянием InstanceState, связанный с экземпляром.

Результат:

Данное событие не поддерживает никаких возвращаемых значений.

См.также

MapperEvents.before_mapper_configured()

method sqlalchemy.orm.MapperEvents.before_configured() → None¶

Вызывается перед конфигурированием ряда картографов.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeClass, 'before_configured')
def receive_before_configured():
    "listen for the 'before_configured' event"

    # ... (event handling logic) ...

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

from sqlalchemy.orm import Mapper

@event.listens_for(Mapper, "before_configured")
def go():
    ...

В отличие от MapperEvents.after_configured(), которое вызывается после настройки серии мапперов, а также MapperEvents.before_mapper_configured() и MapperEvents.mapper_configured(), которые вызываются по каждому мапперу.

Теоретически это событие вызывается один раз для каждого приложения, но на самом деле оно вызывается каждый раз, когда новые отображения должны быть затронуты вызовом configure_mappers(). Если новые отображения создаются после того, как существующие уже были использованы, это событие, скорее всего, будет вызвано снова. Чтобы гарантировать, что конкретное событие будет вызвано только один раз и не более, можно применить аргумент once=True (новый в 0.9.4):

from sqlalchemy.orm import mapper

@event.listens_for(mapper, "before_configured", once=True)
def go():
    ...

См.также

MapperEvents.mapper_configured()

MapperEvents.after_configured()

method sqlalchemy.orm.MapperEvents.before_delete(mapper: Mapper[_O], connection: Connection, target: _O) → None¶

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

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeClass, 'before_delete')
def receive_before_delete(mapper, connection, target):
    "listen for the 'before_delete' event"

    # ... (event handling logic) ...

Примечание

Это событие часто вызывается для партии объектов одного класса, прежде чем их заявления DELETE будут выпущены одновременно на следующем шаге.

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

Параметры:

mapper – Mapper, который является целью этого события.
connection – Connection, используемый для выполнения операторов DELETE для данного экземпляра. Это позволяет получить доступ к текущей транзакции в целевой базе данных, специфичной для данного экземпляра.
target – удаляемый сопоставленный экземпляр. Если событие настроено с параметром raw=True, вместо него будет объект управления состоянием InstanceState, связанный с экземпляром.

Результат:

Данное событие не поддерживает никаких возвращаемых значений.

См.также

method sqlalchemy.orm.MapperEvents.before_insert(mapper: Mapper[_O], connection: Connection, target: _O) → None¶

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

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeClass, 'before_insert')
def receive_before_insert(mapper, connection, target):
    "listen for the 'before_insert' event"

    # ... (event handling logic) ...

Примечание

Это событие используется для изменения локальных, не связанных с объектом атрибутов экземпляра перед выполнением INSERT, а также для выполнения дополнительных SQL-запросов на данном соединении.

Это событие часто вызывается для партии объектов одного класса перед тем, как их INSERT-запросы будут выданы одновременно на более позднем этапе. В крайне редких случаях, когда это нежелательно, объект Mapper может быть настроен на batch=False, что приведет к тому, что партии экземпляров будут разбиты на отдельные (и более низкопроизводительные) шаги event->persist->event.

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

Параметры:

mapper – Mapper, который является целью этого события.
connection – Connection, используемый для выполнения операторов INSERT для данного экземпляра. Это позволяет получить доступ к текущей транзакции в целевой базе данных, специфичной для данного экземпляра.
target – сопоставленный экземпляр, который сохраняется. Если событие настроено с параметром raw=True, то вместо него будет объект управления состоянием InstanceState, связанный с экземпляром.

Результат:

Данное событие не поддерживает никаких возвращаемых значений.

См.также

MapperEvents.before_configured()

method sqlalchemy.orm.MapperEvents.before_mapper_configured(mapper: Mapper[_O], class_: Type[_O]) → None¶

Вызывается непосредственно перед конфигурированием определенного картографа.

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeClass, 'before_mapper_configured')
def receive_before_mapper_configured(mapper, class_):
    "listen for the 'before_mapper_configured' event"

    # ... (event handling logic) ...

Это событие предназначено для того, чтобы позволить пропустить определенный маппер на этапе конфигурирования, возвращая символ interfaces.EXT_SKIP, который указывает вызову configure_mappers(), что этот конкретный маппер (или иерархия мапперов, если используется propagate=True) должен быть пропущен в текущем запуске конфигурации. Когда один или несколько картографов пропущены, флаг «new mappers» останется установленным, что означает, что функция configure_mappers() будет по-прежнему вызываться при использовании картографов, чтобы продолжить попытки конфигурирования всех доступных картографов.

По сравнению с другими событиями уровня configure, MapperEvents.before_configured(), MapperEvents.after_configured() и MapperEvents.mapper_configured(), событие :meth;`.MapperEvents.before_mapper_configured` обеспечивает значимое возвращаемое значение, когда оно зарегистрировано с параметром retval=True.

Добавлено в версии 1.3.

например:

from sqlalchemy.orm import EXT_SKIP

Base = declarative_base()

DontConfigureBase = declarative_base()

@event.listens_for(
    DontConfigureBase,
    "before_mapper_configured", retval=True, propagate=True)
def dont_configure(mapper, cls):
    return EXT_SKIP

См.также

MapperEvents.after_configured()

MapperEvents.mapper_configured()

method sqlalchemy.orm.MapperEvents.before_update(mapper: Mapper[_O], connection: Connection, target: _O) → None¶

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

Примерные формы аргументов:

from sqlalchemy import event


@event.listens_for(SomeClass, 'before_update')
def receive_before_update(mapper, connection, target):
    "listen for the 'before_update' event"

    # ... (event handling logic) ...

Примечание

Это событие используется для изменения локальных, не связанных с объектом, атрибутов экземпляра до того, как произойдет UPDATE, а также для запуска дополнительных SQL-запросов на данном соединении.

Этот метод вызывается для всех экземпляров, которые помечены как «грязные», даже для тех, которые не имеют чистых изменений в своих атрибутах на основе столбцов. Объект помечается как «грязный», когда для любого из его атрибутов на основе столбцов вызывается операция «set attribute» или когда изменяется любая из его коллекций. Если во время обновления ни один атрибут на основе столбцов не имеет чистых изменений, оператор UPDATE не будет выдан. Это означает, что отправка экземпляра в MapperEvents.before_update() не является не гарантией того, что будет выпущен оператор UPDATE, хотя вы можете повлиять на результат, изменив атрибуты так, чтобы чистое изменение значения действительно существовало.

Чтобы определить, есть ли в атрибутах объекта на основе столбцов чистые изменения, и поэтому будет сгенерирован оператор UPDATE, используйте object_session(instance).is_modified(instance, include_collections=False).

Это событие часто вызывается для партии объектов одного класса, прежде чем их заявления UPDATE будут выпущены одновременно на более позднем шаге. В крайне редких случаях, когда это нежелательно, Mapper можно настроить batch=False, что приведет к тому, что партии экземпляров будут разбиты на отдельные (и более низкопроизводительные) шаги event->persist->event.

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

Параметры:

mapper – Mapper, который является целью этого события.
connection – Connection, используемый для выпуска UPDATE-запросов для данного экземпляра. Это позволяет получить доступ к текущей транзакции в целевой базе данных, специфичной для данного экземпляра.
target – сопоставленный экземпляр, который сохраняется. Если событие настроено с параметром raw=True, то вместо него будет объект управления состоянием InstanceState, связанный с экземпляром.

Результат:

Данное событие не поддерживает никаких возвращаемых значений.

См.также