Основные мероприятия¶

:class:`_pool.Pool`A

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

например:

from sqlalchemy import event

def my_on_checkout(dbapi_conn, connection_rec, connection_proxy):
    "handle an on checkout event"

event.listen(Pool, 'checkout', my_on_checkout)

Pool Pool PoolEvents Engine Engine .pool Pool I

engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")

# will associate with engine.pool
event.listen(engine, 'checkout', my_on_checkout)

method sqlalchemy.events.PoolEvents.checkin(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None¶

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

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

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'checkin')
def receive_checkin(dbapi_connection, connection_record):
    "listen for the 'checkin' event"

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

``checkin``N

Параметры:

• dbapi_connection – :attr:`.ConnectionPoolEntry.dbapi_connection`a

• connection_record – :class:`.ConnectionPoolEntry`t

method sqlalchemy.events.PoolEvents.checkout(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, connection_proxy: PoolProxiedConnection) → None¶

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

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

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'checkout')
def receive_checkout(dbapi_connection, connection_record, connection_proxy):
    "listen for the 'checkout' event"

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

Параметры:

• dbapi_connection – :attr:`.ConnectionPoolEntry.dbapi_connection`a

• connection_record – :class:`.ConnectionPoolEntry`t

• connection_proxy – :class:`.PoolProxiedConnection`t

:class:`~sqlalchemy.exc.DisconnectionError`I

См.также

ConnectionEvents.engine_connect() Connection <

method sqlalchemy.events.PoolEvents.close(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None¶

Вызывается при закрытии соединения DBAPI.

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

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'close')
def receive_close(dbapi_connection, connection_record):
    "listen for the 'close' event"

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

Событие выдается до того, как произойдет закрытие.

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

close() close_detached() T

Параметры:

• dbapi_connection – :attr:`.ConnectionPoolEntry.dbapi_connection`a

• connection_record – :class:`.ConnectionPoolEntry`t

method sqlalchemy.events.PoolEvents.close_detached(dbapi_connection: DBAPIConnection) → None¶

Вызывается при закрытии отсоединенного DBAPI-соединения.

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

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'close_detached')
def receive_close_detached(dbapi_connection):
    "listen for the 'close_detached' event"

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

Событие выдается до того, как произойдет закрытие.

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

Параметры:

dbapi_connection – :attr:`.ConnectionPoolEntry.dbapi_connection`a

method sqlalchemy.events.PoolEvents.connect(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None¶

:class:`_pool.Pool`C

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

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'connect')
def receive_connect(dbapi_connection, connection_record):
    "listen for the 'connect' event"

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

``.connect()``T

Параметры:

• dbapi_connection – :attr:`.ConnectionPoolEntry.dbapi_connection`a

• connection_record – :class:`.ConnectionPoolEntry`t

method sqlalchemy.events.PoolEvents.detach(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None¶

Вызывается при «отсоединении» DBAPI-соединения от пула.

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

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'detach')
def receive_detach(dbapi_connection, connection_record):
    "listen for the 'detach' event"

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

Это событие выдается после того, как произойдет отсоединение. Соединение больше не ассоциируется с данной записью соединения.

Параметры:

• dbapi_connection – :attr:`.ConnectionPoolEntry.dbapi_connection`a

• connection_record – :class:`.ConnectionPoolEntry`t

attribute sqlalchemy.events.PoolEvents.dispatch: _Dispatch[_ET] = <sqlalchemy.event.base.PoolEventsDispatch object>¶

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

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

method sqlalchemy.events.PoolEvents.first_connect(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry) → None¶

:class:`_pool.Pool`C

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

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'first_connect')
def receive_first_connect(dbapi_connection, connection_record):
    "listen for the 'first_connect' event"

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

PoolEvents.first_connect() Pool Engine T

Параметры:

• dbapi_connection – :attr:`.ConnectionPoolEntry.dbapi_connection`a

• connection_record – :class:`.ConnectionPoolEntry`t

method sqlalchemy.events.PoolEvents.invalidate(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, exception: Optional[BaseException]) → None¶

Вызывается, когда соединение DBAPI должно быть «аннулировано».

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

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'invalidate')
def receive_invalidate(dbapi_connection, connection_record, exception):
    "listen for the 'invalidate' event"

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

ConnectionPoolEntry.invalidate() soft T

``.close()``T

Параметры:

• dbapi_connection – :attr:`.ConnectionPoolEntry.dbapi_connection`a

• connection_record – :class:`.ConnectionPoolEntry`t

• exception – ``None``t

См.также

Подробнее об инвалидизации

method sqlalchemy.events.PoolEvents.reset(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, reset_state: PoolResetState) → None¶

Вызывается перед выполнением действия «сброс» для соединения с пулом.

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

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'reset')
def receive_reset(dbapi_connection, connection_record, reset_state):
    "listen for the 'reset' event"

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

# DEPRECATED calling style (pre-2.0, will be removed in a future release)
@event.listens_for(SomeEngineOrPool, 'reset')
def receive_reset(dbapi_connection, connection_record):
    "listen for the 'reset' event"

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

Изменено в версии 2.0: PoolEvents.reset() PoolEvents.reset.dbapi_connection PoolEvents.reset.connection_record PoolEvents.reset.reset_state T

rollback() Pool.reset_on_return T

PoolEvents.reset() PoolEvents.checkin() PoolEvents.reset() Connection.detach() T

Connection.invalidate() PoolEvents.soft_invalidate() PoolEvents.invalidate() PoolEvents.close() N

PoolEvents.reset() PoolEvents.checkin() T

Параметры:

• dbapi_connection – :attr:`.ConnectionPoolEntry.dbapi_connection`a

• connection_record – :class:`.ConnectionPoolEntry`t

• reset_state – :class:`.PoolResetState`<

См.также

Сброс при возврате

ConnectionEvents.rollback()

ConnectionEvents.commit()

method sqlalchemy.events.PoolEvents.soft_invalidate(dbapi_connection: DBAPIConnection, connection_record: ConnectionPoolEntry, exception: Optional[BaseException]) → None¶

Вызывается, когда соединение DBAPI должно быть «мягко аннулировано».

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

from sqlalchemy import event


@event.listens_for(SomeEngineOrPool, 'soft_invalidate')
def receive_soft_invalidate(dbapi_connection, connection_record, exception):
    "listen for the 'soft_invalidate' event"

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

ConnectionPoolEntry.invalidate() soft T

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

Параметры:

• dbapi_connection – :attr:`.ConnectionPoolEntry.dbapi_connection`a

• connection_record – :class:`.ConnectionPoolEntry`t

• exception – ``None``t

:meth:`.PoolEvents.reset`d

attribute sqlalchemy.events.PoolResetState.asyncio_safe: bool¶

Указывает, происходит ли операция сброса в области, где ожидается наличие вложенного цикла событий для приложений asyncio.

Будет иметь значение False в случае, если соединение собирается в мусор.

attribute sqlalchemy.events.PoolResetState.terminate_only: bool¶

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

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

attribute sqlalchemy.events.PoolResetState.transaction_was_reset: bool¶

:class:`.Connection`I

Connection Connection.rollback() Connection.commit() Connection.close() T

Connection Engine A

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

Connection Engine Engine A

from sqlalchemy import event, create_engine

def before_cursor_execute(conn, cursor, statement, parameters, context,
                                                executemany):
    log.info("Received statement: %s", statement)

engine = create_engine('postgresql+psycopg2://scott:tiger@localhost/test')
event.listen(engine, "before_cursor_execute", before_cursor_execute)

:class:`_engine.Connection`o

with engine.begin() as conn:
    @event.listens_for(conn, 'before_cursor_execute')
    def before_cursor_execute(conn, cursor, statement, parameters,
                                    context, executemany):
        log.info("Received statement: %s", statement)

after_cursor_execute() before_cursor_execute() cursor Dialect W

before_execute() before_cursor_execute() retval=True before_cursor_execute() T

from sqlalchemy.engine import Engine
from sqlalchemy import event

@event.listens_for(Engine, "before_cursor_execute", retval=True)
def comment_sql_calls(conn, cursor, statement, parameters,
                                    context, executemany):
    statement = statement + " -- some comment"
    return statement, parameters

Параметры:

retval=False – before_execute() before_cursor_execute() A

method sqlalchemy.events.ConnectionEvents.after_cursor_execute(conn: Connection, cursor: DBAPICursor, statement: str, parameters: _DBAPIAnyExecuteParams, context: Optional[ExecutionContext], executemany: bool) → None¶

Перехват низкоуровневых событий курсора execute() после его выполнения.

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'after_cursor_execute')
def receive_after_cursor_execute(conn, cursor, statement, parameters, context, executemany):
    "listen for the 'after_cursor_execute' event"

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

Параметры:

• conn – :class:`_engine.Connection`<

• cursor – :class:`_engine.CursorResult`D

• statement – строковый SQL-оператор, передаваемый в DBAPI

• parameters – execute() executemany() cursor None D

• context – ExecutionContext None <

• executemany – True executemany() False execute() b

method sqlalchemy.events.ConnectionEvents.after_execute(conn: Connection, clauseelement: Executable, multiparams: _CoreMultiExecuteParams, params: _CoreSingleExecuteParams, execution_options: _ExecuteOptions, result: Result[Any]) → None¶

Перехват событий высокого уровня execute() после выполнения.

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'after_execute')
def receive_after_execute(conn, clauseelement, multiparams, params, execution_options, result):
    "listen for the 'after_execute' event"

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

# DEPRECATED calling style (pre-1.4, will be removed in a future release)
@event.listens_for(SomeEngine, 'after_execute')
def receive_after_execute(conn, clauseelement, multiparams, params, result):
    "listen for the 'after_execute' event"

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

Изменено в версии 1.4: ConnectionEvents.after_execute() ConnectionEvents.after_execute.conn ConnectionEvents.after_execute.clauseelement ConnectionEvents.after_execute.multiparams ConnectionEvents.after_execute.params ConnectionEvents.after_execute.execution_options ConnectionEvents.after_execute.result T

Параметры:

• conn – :class:`_engine.Connection`<

• clauseelement – Compiled Connection.execute() S

• multiparams – Множество наборов параметров, список словарей.

• params – Один набор параметров, один словарь.

• execution_options – словарь опций выполнения, переданных вместе с оператором, если таковые имеются. Это объединение всех опций, которые будут использоваться, включая опции оператора, соединения и опции, передаваемые в сам метод для стиля выполнения 2.0. … версия добавлена: 1.4

• result – :class:`_engine.CursorResult`<

method sqlalchemy.events.ConnectionEvents.before_cursor_execute(conn: Connection, cursor: DBAPICursor, statement: str, parameters: _DBAPIAnyExecuteParams, context: Optional[ExecutionContext], executemany: bool) → Optional[Tuple[str, _DBAPIAnyExecuteParams]]¶

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

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'before_cursor_execute')
def receive_before_cursor_execute(conn, cursor, statement, parameters, context, executemany):
    "listen for the 'before_cursor_execute' event"

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

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

retval=True statement parameters T

@event.listens_for(Engine, "before_cursor_execute", retval=True)
def before_cursor_execute(conn, cursor, statement,
                parameters, context, executemany):
    # do something with statement, parameters
    return statement, parameters

:class:`_events.ConnectionEvents`S

Параметры:

• conn – :class:`_engine.Connection`<

• cursor – Объект курсора DBAPI

• statement – строковый SQL-оператор, который должен быть передан в DBAPI

• parameters – execute() executemany() cursor None D

• context – ExecutionContext None <

• executemany – True executemany() False execute() b

См.также

before_execute()

after_cursor_execute()

method sqlalchemy.events.ConnectionEvents.before_execute(conn: Connection, clauseelement: Executable, multiparams: _CoreMultiExecuteParams, params: _CoreSingleExecuteParams, execution_options: _ExecuteOptions) → Optional[Tuple[Executable, _CoreMultiExecuteParams, _CoreSingleExecuteParams]]¶

Перехват событий высокого уровня execute(), получение некомпилированных конструкций SQL и других объектов до их преобразования в SQL.

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'before_execute')
def receive_before_execute(conn, clauseelement, multiparams, params, execution_options):
    "listen for the 'before_execute' event"

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

# DEPRECATED calling style (pre-1.4, will be removed in a future release)
@event.listens_for(SomeEngine, 'before_execute')
def receive_before_execute(conn, clauseelement, multiparams, params):
    "listen for the 'before_execute' event"

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

Изменено в версии 1.4: Событие ConnectionEvents.before_execute() теперь принимает аргументы ConnectionEvents.before_execute.conn, ConnectionEvents.before_execute.clauseelement, ConnectionEvents.before_execute.multiparams, ConnectionEvents.before_execute.params, ConnectionEvents.before_execute.execution_options. Поддержка функций слушателя, принимающих предыдущие сигнатуры аргументов, перечисленные выше как «устаревшие», будет удалена в одном из будущих выпусков.

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

Это событие может быть опционально установлено с помощью флага retval=True. Аргументы clauseelement, multiparams и params в этом случае должны быть возвращены в виде кортежа:

@event.listens_for(Engine, "before_execute", retval=True)
def before_execute(conn, clauseelement, multiparams, params):
    # do something with clauseelement, multiparams, params
    return clauseelement, multiparams, params

Параметры:

• conn – :class:`_engine.Connection`<

• clauseelement – Compiled Connection.execute() S

• multiparams – Множество наборов параметров, список словарей.

• params – Один набор параметров, один словарь.

• execution_options – словарь опций выполнения, переданных вместе с оператором, если таковые имеются. Это объединение всех опций, которые будут использоваться, включая опции оператора, соединения и опции, передаваемые в сам метод для стиля выполнения 2.0. … версия добавлена: 1.4

См.также

before_cursor_execute()

method sqlalchemy.events.ConnectionEvents.begin(conn: Connection) → None¶

Перехватывайте события begin().

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'begin')
def receive_begin(conn):
    "listen for the 'begin' event"

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

Параметры:

conn – :class:`_engine.Connection`<

method sqlalchemy.events.ConnectionEvents.begin_twophase(conn: Connection, xid: Any) → None¶

Перехват событий begin_twophase().

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'begin_twophase')
def receive_begin_twophase(conn, xid):
    "listen for the 'begin_twophase' event"

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

Параметры:

• conn – :class:`_engine.Connection`<

• xid – двухфазный идентификатор XID

method sqlalchemy.events.ConnectionEvents.commit(conn: Connection) → None¶

Перехват событий commit(), инициированных командой Transaction.

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'commit')
def receive_commit(conn):
    "listen for the 'commit' event"

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

Обратите внимание, что Pool может также «автоматически фиксировать» соединение DBAPI при регистрации, если флаг reset_on_return установлен в значение 'commit'. Чтобы перехватить эту фиксацию, используйте хук PoolEvents.reset().

Параметры:

conn – :class:`_engine.Connection`<

method sqlalchemy.events.ConnectionEvents.commit_twophase(conn: Connection, xid: Any, is_prepared: bool) → None¶

Перехватывайте события commit_twophase().

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'commit_twophase')
def receive_commit_twophase(conn, xid, is_prepared):
    "listen for the 'commit_twophase' event"

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

Параметры:

• conn – :class:`_engine.Connection`<

• xid – двухфазный идентификатор XID

• is_prepared – boolean, указывает, было ли вызвано TwoPhaseTransaction.prepare().

attribute sqlalchemy.events.ConnectionEvents.dispatch: _Dispatch[_ET] = <sqlalchemy.event.base.ConnectionEventsDispatch object>¶

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

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

method sqlalchemy.events.ConnectionEvents.engine_connect(conn: Connection) → None¶

Перехват создания нового Connection.

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'engine_connect')
def receive_engine_connect(conn):
    "listen for the 'engine_connect' event"

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

# DEPRECATED calling style (pre-2.0, will be removed in a future release)
@event.listens_for(SomeEngine, 'engine_connect')
def receive_engine_connect(conn, branch):
    "listen for the 'engine_connect' event"

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

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

Это событие вызывается обычно как прямой результат вызова метода Engine.connect().

Оно отличается от метода PoolEvents.connect(), который относится к фактическому соединению с базой данных на уровне DBAPI; соединение DBAPI может быть объединено и повторно использовано для многих операций. В отличие от этого, данное событие относится только к созданию обертки более высокого уровня Connection вокруг такого DBAPI-соединения.

Оно также отличается от события PoolEvents.checkout() тем, что специфично для объекта Connection, а не для соединения DBAPI, с которым работает PoolEvents.checkout(), хотя это соединение DBAPI доступно здесь через атрибут Connection.connection. Но обратите внимание, что в течение жизни одного объекта Connection может произойти несколько событий PoolEvents.checkout(), если этот объект Connection аннулируется и восстанавливается.

Параметры:

conn – Connection объект.

См.также

PoolEvents.checkout() событие проверки пула нижнего уровня для отдельного соединения DBAPI

method sqlalchemy.events.ConnectionEvents.engine_disposed(engine: Engine) → None¶

Перехват при вызове метода Engine.dispose().

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'engine_disposed')
def receive_engine_disposed(engine):
    "listen for the 'engine_disposed' event"

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

Метод Engine.dispose() дает команду движку «утилизировать» свой пул соединений (например, Pool) и заменяет его новым. Утилизация старого пула приводит к тому, что существующие зарегистрированные соединения закрываются. Новый пул не устанавливает новых соединений до тех пор, пока он не будет впервые использован.

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

method sqlalchemy.events.ConnectionEvents.prepare_twophase(conn: Connection, xid: Any) → None¶

Перехватывайте события prepare_twophase().

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'prepare_twophase')
def receive_prepare_twophase(conn, xid):
    "listen for the 'prepare_twophase' event"

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

Параметры:

• conn – :class:`_engine.Connection`<

• xid – двухфазный идентификатор XID

method sqlalchemy.events.ConnectionEvents.release_savepoint(conn: Connection, name: str, context: None) → None¶

Перехватывайте события release_savepoint().

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'release_savepoint')
def receive_release_savepoint(conn, name, context):
    "listen for the 'release_savepoint' event"

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

Параметры:

• conn – :class:`_engine.Connection`<

• name – указанное имя, используемое для точки сохранения.

• context – не используется

method sqlalchemy.events.ConnectionEvents.rollback(conn: Connection) → None¶

Перехват событий rollback(), инициированных командой Transaction.

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'rollback')
def receive_rollback(conn):
    "listen for the 'rollback' event"

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

Обратите внимание, что Pool также «автоматически откатывает» соединение DBAPI при регистрации, если флаг reset_on_return установлен в значение по умолчанию 'rollback'. Чтобы перехватить этот откат, используйте хук PoolEvents.reset().

Параметры:

conn – :class:`_engine.Connection`<

См.также

PoolEvents.reset()

method sqlalchemy.events.ConnectionEvents.rollback_savepoint(conn: Connection, name: str, context: None) → None¶

Перехватывайте события rollback_savepoint().

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'rollback_savepoint')
def receive_rollback_savepoint(conn, name, context):
    "listen for the 'rollback_savepoint' event"

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

Параметры:

• conn – :class:`_engine.Connection`<

• name – указанное имя, используемое для точки сохранения.

• context – не используется

method sqlalchemy.events.ConnectionEvents.rollback_twophase(conn: Connection, xid: Any, is_prepared: bool) → None¶

Перехватывайте события rollback_twophase().

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'rollback_twophase')
def receive_rollback_twophase(conn, xid, is_prepared):
    "listen for the 'rollback_twophase' event"

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

Параметры:

• conn – :class:`_engine.Connection`<

• xid – двухфазный идентификатор XID

• is_prepared – boolean, указывает, было ли вызвано TwoPhaseTransaction.prepare().

method sqlalchemy.events.ConnectionEvents.savepoint(conn: Connection, name: str) → None¶

Перехват событий savepoint().

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'savepoint')
def receive_savepoint(conn, name):
    "listen for the 'savepoint' event"

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

Параметры:

• conn – :class:`_engine.Connection`<

• name – указанное имя, используемое для точки сохранения.

method sqlalchemy.events.ConnectionEvents.set_connection_execution_options(conn: Connection, opts: Dict[str, Any]) → None¶

Перехват при вызове метода Connection.execution_options().

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'set_connection_execution_options')
def receive_set_connection_execution_options(conn, opts):
    "listen for the 'set_connection_execution_options' event"

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

Этот метод вызывается после создания нового Connection с обновленной коллекцией опций выполнения, но до того, как Dialect начнет действовать в соответствии с этими новыми опциями.

Обратите внимание, что этот метод не вызывается, когда создается новый Connection, который наследует параметры выполнения от своего родителя Engine; чтобы перехватить это условие, используйте событие ConnectionEvents.engine_connect().

Параметры:

• conn – Новый скопированный объект Connection

• opts – словарь опций, которые были переданы методу Connection.execution_options(). Этот словарь может быть изменен на месте, чтобы повлиять на конечные опции, которые вступят в силу. … versionadded:: 2.0 словарь opts может быть изменен на месте.

См.также

ConnectionEvents.set_engine_execution_options() - событие, которое вызывается при вызове Engine.execution_options().

method sqlalchemy.events.ConnectionEvents.set_engine_execution_options(engine: Engine, opts: Dict[str, Any]) → None¶

Перехват при вызове метода Engine.execution_options().

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'set_engine_execution_options')
def receive_set_engine_execution_options(engine, opts):
    "listen for the 'set_engine_execution_options' event"

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

Метод Engine.execution_options() создает неглубокую копию Engine, в которой хранятся новые опции. Этот новый Engine передается сюда. Особым применением этого метода является добавление обработчика события ConnectionEvents.engine_connect() к данному Engine, который будет выполнять некоторую пер- Connection задачу, специфичную для данных опций выполнения.

Параметры:

• conn – Новый скопированный объект Engine

• opts – словарь опций, которые были переданы методу Connection.execution_options(). Этот словарь может быть изменен на месте, чтобы повлиять на конечные опции, которые вступят в силу. … versionadded:: 2.0 словарь opts может быть изменен на месте.

См.также

ConnectionEvents.set_connection_execution_options() - событие, которое вызывается при вызове Connection.execution_options().

событийный интерфейс для функций замещения исполнения.

Эти события позволяют напрямую инструментировать и заменять ключевые функции диалекта, которые взаимодействуют с DBAPI.

attribute sqlalchemy.events.DialectEvents.dispatch: _Dispatch[_ET] = <sqlalchemy.event.base.DialectEventsDispatch object>¶

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

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

method sqlalchemy.events.DialectEvents.do_connect(dialect: Dialect, conn_rec: ConnectionPoolEntry, cargs: Tuple[Any, ...], cparams: Dict[str, Any]) → Optional[DBAPIConnection]¶

Получение аргументов подключения до установления соединения.

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'do_connect')
def receive_do_connect(dialect, conn_rec, cargs, cparams):
    "listen for the 'do_connect' event"

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

Это событие полезно тем, что позволяет обработчику манипулировать коллекциями cargs и/или cparams, которые управляют тем, как будет вызвана функция DBAPI connect(). cargs всегда будет списком Python, который может быть изменен на месте, а cparams - словарем Python, который также может быть изменен:

e = create_engine("postgresql+psycopg2://user@host/dbname")

@event.listens_for(e, 'do_connect')
def receive_do_connect(dialect, conn_rec, cargs, cparams):
    cparams["password"] = "some_password"

Крючок событий можно также использовать для полной отмены вызова connect(), возвращая не``None`` объект соединения DBAPI:

e = create_engine("postgresql+psycopg2://user@host/dbname")

@event.listens_for(e, 'do_connect')
def receive_do_connect(dialect, conn_rec, cargs, cparams):
    return psycopg2.connect(*cargs, **cparams)

См.также

Пользовательские аргументы DBAPI connect() / процедуры включения соединения

method sqlalchemy.events.DialectEvents.do_execute(cursor: DBAPICursor, statement: str, parameters: _DBAPISingleExecuteParams, context: ExecutionContext) → Optional[Literal[True]]¶

Получите курсор для вызова execute().

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'do_execute')
def receive_do_execute(cursor, statement, parameters, context):
    "listen for the 'do_execute' event"

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

Возвращает значение True, чтобы остановить дальнейшие вызовы событий и указать, что выполнение курсора уже произошло в обработчике события.

method sqlalchemy.events.DialectEvents.do_execute_no_params(cursor: DBAPICursor, statement: str, context: ExecutionContext) → Optional[Literal[True]]¶

Получите курсор, чтобы вызвать execute() без параметров.

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'do_execute_no_params')
def receive_do_execute_no_params(cursor, statement, context):
    "listen for the 'do_execute_no_params' event"

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

Возвращает значение True, чтобы остановить дальнейшие вызовы событий и указать, что выполнение курсора уже произошло в обработчике события.

method sqlalchemy.events.DialectEvents.do_executemany(cursor: DBAPICursor, statement: str, parameters: _DBAPIMultiExecuteParams, context: ExecutionContext) → Optional[Literal[True]]¶

Получите курсор для вызова функции executemany().

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'do_executemany')
def receive_do_executemany(cursor, statement, parameters, context):
    "listen for the 'do_executemany' event"

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

Возвращает значение True, чтобы остановить дальнейшие вызовы событий и указать, что выполнение курсора уже произошло в обработчике события.

method sqlalchemy.events.DialectEvents.do_setinputsizes(inputsizes: Dict[BindParameter[Any], Any], cursor: DBAPICursor, statement: str, parameters: _DBAPIAnyExecuteParams, context: ExecutionContext) → None¶

Получите словарь setinputsizes для возможной модификации.

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'do_setinputsizes')
def receive_do_setinputsizes(inputsizes, cursor, statement, parameters, context):
    "listen for the 'do_setinputsizes' event"

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

Это событие возникает в том случае, если диалект использует метод DBAPI cursor.setinputsizes(), который передает информацию о привязке параметров для конкретного оператора. Данный словарь inputsizes будет содержать объекты BindParameter в качестве ключей, связанные с объектами типов, специфичных для DBAPI, в качестве значений; для параметров, которые не связаны, они добавляются в словарь с None в качестве значения, что означает, что параметр не будет включен в конечный вызов setinputsizes. Это событие может быть использовано для проверки и/или регистрации типов данных, которые связываются, а также для изменения словаря на месте. Параметры могут быть добавлены, изменены или удалены из этого словаря. Вызывающие обычно хотят проверить атрибут BindParameter.type данных объектов bind, чтобы принять решение об объекте DBAPI.

После события словарь inputsizes преобразуется в соответствующую структуру данных для передачи в cursor.setinputsizes; либо список для позиционного стиля выполнения связанных параметров, либо словарь строковых ключей параметров к объектам типа DBAPI для именованного стиля выполнения связанных параметров.

Хук setinputsizes в целом используется только для диалектов, которые включают флаг use_setinputsizes=True. Диалекты, использующие этот флаг, включают диалекты cx_Oracle, pg8000, asyncpg и pyodbc.

Примечание

Для использования с pyodbc необходимо передать диалекту флаг use_setinputsizes, например:

create_engine("mssql+pyodbc://...", use_setinputsizes=True)

См.также

Setinputsizes Support

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

См.также

Тонкий контроль над производительностью привязки данных cx_Oracle с помощью setinputsizes

method sqlalchemy.events.DialectEvents.handle_error(exception_context: ExceptionContext) → Optional[BaseException]¶

Перехватывать все исключения, обрабатываемые Dialect, обычно, но не ограничиваясь теми, которые испускаются в пределах области действия Connection.

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

from sqlalchemy import event


@event.listens_for(SomeEngine, 'handle_error')
def receive_handle_error(exception_context):
    "listen for the 'handle_error' event"

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

Изменено в версии 2.0: событие DialectEvents.handle_error() перемещено в класс DialectEvents из класса ConnectionEvents, чтобы оно также могло участвовать в операции «pre ping», настроенной с помощью параметра create_engine.pool_pre_ping. Событие остается зарегистрированным при использовании Engine в качестве цели события, однако обратите внимание, что использование Connection в качестве цели события для DialectEvents.handle_error() больше не поддерживается.

Сюда входят все исключения, выдаваемые DBAPI, а также в процессе вызова оператора SQLAlchemy, включая ошибки кодирования и другие ошибки проверки оператора. Другие области, в которых вызывается это событие, включают начало и конец транзакции, выборку строк результата, создание курсора.

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

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

Этот крючок поддерживает следующие варианты использования:

• только для чтения, низкоуровневая обработка исключений для ведения журнала и отладки

• Установление того, указывает ли сообщение об ошибке соединения DBAPI на то, что соединение с базой данных должно быть переподключено, в том числе для обработчика «pre_ping», используемого некоторыми диалектами

• Установление или отключение того, что соединение или принадлежащий ему пул соединений аннулируется или истекает в ответ на определенное исключение

• переписывание исключений

Хук вызывается, пока курсор из неудачной операции (если таковой имеется) все еще открыт и доступен. На этом курсоре могут быть вызваны специальные операции очистки; SQLAlchemy попытается закрыть этот курсор после вызова этого хука.

Начиная с версии SQLAlchemy 2.0, обработчик «pre_ping», включенный с помощью параметра create_engine.pool_pre_ping, также будет участвовать в процессе handle_error(), для тех диалектов, которые полагаются на коды разъединения для определения «живости» базы данных. Обратите внимание, что некоторые диалекты, такие как psycopg, psycopg2, и большинство диалектов MySQL используют собственный метод ping(), предоставляемый DBAPI, который не использует коды разъединения.

Изменено в версии 2.0.0: Крючок события DialectEvents.handle_error() участвует в операциях «предварительного пинга» пула соединений. При таком использовании атрибут ExceptionContext.engine будет None, однако используемый Dialect всегда доступен через атрибут ExceptionContext.dialect.

Изменено в версии 2.0.5: Добавлен атрибут ExceptionContext.is_pre_ping, который будет установлен в True при срабатывании крючка события DialectEvents.handle_error() в рамках операции предварительного пинга пула соединений.

Изменено в версии 2.0.5: Устранена проблема, которая позволяет драйверам PostgreSQL psycopg и psycopg2, а также всем драйверам MySQL, правильно участвовать в подключении события DialectEvents.handle_error() во время операций «pre-ping» пула соединений; ранее реализация была нерабочей для этих драйверов.

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

@event.listens_for(Engine, "handle_error")
def handle_exception(context):
    if isinstance(context.original_exception,
        psycopg2.OperationalError) and \
        "failed" in str(context.original_exception):
        raise MySpecialException("failed operation")

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

Поскольку событие DialectEvents.handle_error() специально предусматривает повторное отбрасывание исключений в качестве конечного исключения, вызванного неудачным оператором, трассировка стека будет вводить в заблуждение, если сам пользовательский обработчик события не сработает и выбросит неожиданное исключение; трассировка стека может не показать фактическую строку кода, в которой произошел сбой! В этом случае рекомендуется писать код осторожно и использовать протоколирование и/или встроенную отладку, если возникают неожиданные исключения.

В качестве альтернативы можно использовать «цепной» стиль обработки событий, настроив обработчик с модификатором retval=True и вернув новый экземпляр исключения из функции. В этом случае обработка события будет продолжена следующим обработчиком. «Цепочечное» исключение доступно с помощью ExceptionContext.chained_exception:

@event.listens_for(Engine, "handle_error", retval=True)
def handle_exception(context):
    if context.chained_exception is not None and \
        "special" in context.chained_exception.message:
        return MySpecialException("failed",
            cause=context.chained_exception)

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

Когда пользовательское исключение поднимается или возвращается, SQLAlchemy поднимает это новое исключение как есть, оно не оборачивается никаким объектом SQLAlchemy. Если исключение не является подклассом sqlalchemy.exc.StatementError, некоторые функции могут быть недоступны; в настоящее время это включает функцию ORM по добавлению детальной подсказки об «autoflush» к исключениям, поднятым в процессе autoflush.

Параметры:

context – объект ExceptionContext. Подробную информацию о всех доступных членах смотрите в этом классе.

См.также

Поддержка новых кодов ошибок базы данных для сценариев разъединения

Определите слушателей событий для объектов схемы, то есть SchemaItem и других подклассов SchemaEventTarget, включая MetaData, Table, Column и т.д.

Создание / сброс событий

События, возникающие при передаче в базу данных команд CREATE и DROP. К крючкам событий в этой категории относятся DDLEvents.before_create(), DDLEvents.after_create(), DDLEvents.before_drop() и DDLEvents.after_drop().

Эти события испускаются при использовании методов уровня схемы, таких как MetaData.create_all() и MetaData.drop_all(). Методы создания/удаления каждого объекта, такие как Table.create(), Table.drop(), Index.create(), также включены, как и специфические для диалекта методы, такие как ENUM.create().

Крючки событий могут быть присоединены непосредственно к объекту Table или коллекции MetaData, а также к любому классу или объекту SchemaItem, который может быть индивидуально создан и удален с помощью отдельной команды SQL. К таким классам относятся Index, Sequence и специфические для диалекта классы, такие как ENUM.

Пример использования события DDLEvents.after_create(), где пользовательский крючок события будет выдавать команду ALTER TABLE на текущем соединении, после того как будет выдана команда CREATE TABLE:

from sqlalchemy import create_engine
from sqlalchemy import event
from sqlalchemy import Table, Column, Metadata, Integer

m = MetaData()
some_table = Table('some_table', m, Column('data', Integer))

@event.listens_for(some_table, "after_create")
def after_create(target, connection, **kw):
    connection.execute(text(
        "ALTER TABLE %s SET name=foo_%s" % (target.name, target.name)
    ))


some_engine = create_engine("postgresql://scott:tiger@host/test")

# will emit "CREATE TABLE some_table" as well as the above
# "ALTER TABLE" statement afterwards
m.create_all(some_engine)

Объекты ограничений, такие как ForeignKeyConstraint, UniqueConstraint, CheckConstraint, также могут быть подписаны на эти события, однако они не обычно производят события, так как эти объекты обычно отображаются в строку в рамках оператора CREATE TABLE и неявно выпадают из оператора DROP TABLE.

Для конструкции Index событие hook будет выдано для CREATE INDEX, однако SQLAlchemy обычно не выдает DROP INDEX при сбросе таблиц, так как это опять же подразумевается в операторе DROP TABLE.

События

События вложения предоставляются для настройки поведения всякий раз, когда дочерний элемент схемы связан с родительским, например, когда Column связан с его Table, когда ForeignKeyConstraint связан с Table и т.д. К таким событиям относятся DDLEvents.before_parent_attach() и DDLEvents.after_parent_attach().

Мероприятия для размышления

Событие DDLEvents.column_reflect() используется для перехвата и изменения in-Python определения столбцов базы данных, когда происходит reflection таблиц базы данных.

Использование с Generic DDL

События DDL тесно интегрируются с классом DDL и иерархией ExecutableDDLElement конструкций пунктов DDL, которые сами по себе подходят в качестве вызываемых слушателей:

from sqlalchemy import DDL
event.listen(
    some_table,
    "after_create",
    DDL("ALTER TABLE %(table)s SET name=foo_%(table)s")
)

** Распространение событий на копии метаданных**.

Для всех событий DDLEvent аргумент ключевого слова propagate=True обеспечит распространение обработчика данного события на копии объекта, которые создаются при использовании метода Table.to_metadata():

from sqlalchemy import DDL

metadata = MetaData()
some_table = Table("some_table", metadata, Column("data", Integer))

event.listen(
    some_table,
    "after_create",
    DDL("ALTER TABLE %(table)s SET name=foo_%(table)s"),
    propagate=True
)

new_metadata = MetaData()
new_table = some_table.to_metadata(new_metadata)

Указанный выше объект DDL будет связан с событием DDLEvents.after_create() как для объекта some_table, так и для объекта new_table Table.

method sqlalchemy.events.DDLEvents.after_create(target: SchemaEventTarget, connection: Connection, **kw: Any) → None¶

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

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

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'after_create')
def receive_after_create(target, connection, **kw):
    "listen for the 'after_create' event"

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

Параметры:

• target – SchemaObject, например MetaData или Table, но также включая все объекты create/drop, такие как Index, Sequence и т.д., объект, который является целью события. … версия добавлена:: 2.0 Добавлена поддержка всех объектов SchemaItem.

• connection – Connection, где был выпущен оператор или операторы CREATE.

• **kw – дополнительные аргументы ключевых слов, относящиеся к событию. Содержимое этого словаря может отличаться в разных выпусках и включать список таблиц, создаваемых для события на уровне метаданных, флаг checkfirst и другие элементы, используемые внутренними событиями.

listen() также принимает модификатор propagate=True для этого события; при значении True функция слушателя будет установлена для всех копий, созданных для целевого объекта, т.е. тех копий, которые создаются при использовании Table.to_metadata().

method sqlalchemy.events.DDLEvents.after_drop(target: SchemaEventTarget, connection: Connection, **kw: Any) → None¶

Вызывается после испускания операторов DROP.

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

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'after_drop')
def receive_after_drop(target, connection, **kw):
    "listen for the 'after_drop' event"

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

Параметры:

• target – SchemaObject, например MetaData или Table, но также включая все объекты create/drop, такие как Index, Sequence и т.д., объект, который является целью события. … версия добавлена:: 2.0 Добавлена поддержка всех объектов SchemaItem.

• connection – Connection, где был выпущен оператор или операторы DROP.

• **kw – дополнительные аргументы ключевых слов, относящиеся к событию. Содержимое этого словаря может отличаться в разных выпусках и включать список таблиц, создаваемых для события на уровне метаданных, флаг checkfirst и другие элементы, используемые внутренними событиями.

listen() также принимает модификатор propagate=True для этого события; при значении True функция слушателя будет установлена для всех копий, созданных для целевого объекта, т.е. тех копий, которые создаются при использовании Table.to_metadata().

method sqlalchemy.events.DDLEvents.after_parent_attach(target: SchemaEventTarget, parent: SchemaItem) → None¶

Вызывается после того, как SchemaItem ассоциируется с родительским SchemaItem.

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

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'after_parent_attach')
def receive_after_parent_attach(target, parent):
    "listen for the 'after_parent_attach' event"

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

Параметры:

• target – целевой объект

• parent – родитель, к которому присоединяется цель.

listen() также принимает модификатор propagate=True для этого события; при значении True функция слушателя будет установлена для всех копий, созданных для целевого объекта, т.е. тех копий, которые создаются при использовании Table.to_metadata().

method sqlalchemy.events.DDLEvents.before_create(target: SchemaEventTarget, connection: Connection, **kw: Any) → None¶

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

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

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'before_create')
def receive_before_create(target, connection, **kw):
    "listen for the 'before_create' event"

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

Параметры:

• target – SchemaObject, например MetaData или Table, но также включая все объекты create/drop, такие как Index, Sequence и т.д., объект, который является целью события. … версия добавлена:: 2.0 Добавлена поддержка всех объектов SchemaItem.

• connection – Connection, где будет выдан оператор или операторы CREATE.

• **kw – дополнительные аргументы ключевых слов, относящиеся к событию. Содержимое этого словаря может отличаться в разных выпусках и включать список таблиц, создаваемых для события на уровне метаданных, флаг checkfirst и другие элементы, используемые внутренними событиями.

listen() принимает модификатор propagate=True для этого события; когда True, функция слушателя будет установлена для всех копий целевого объекта, т.е. тех копий, которые создаются при использовании Table.to_metadata().

listen() принимает модификатор insert=True для этого события; при значении True функция слушателя будет добавлена во внутренний список событий при обнаружении и будет выполняться перед зарегистрированными функциями слушателя, которые не передают этот аргумент.

method sqlalchemy.events.DDLEvents.before_drop(target: SchemaEventTarget, connection: Connection, **kw: Any) → None¶

Вызывается перед выпуском операторов DROP.

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

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'before_drop')
def receive_before_drop(target, connection, **kw):
    "listen for the 'before_drop' event"

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

Параметры:

• target – SchemaObject, например MetaData или Table, но также включая все объекты create/drop, такие как Index, Sequence и т.д., объект, который является целью события. … версия добавлена:: 2.0 Добавлена поддержка всех объектов SchemaItem.

• connection – Connection, где будет выдан оператор или операторы DROP.

• **kw – дополнительные аргументы ключевых слов, относящиеся к событию. Содержимое этого словаря может отличаться в разных выпусках и включать список таблиц, создаваемых для события на уровне метаданных, флаг checkfirst и другие элементы, используемые внутренними событиями.

listen() также принимает модификатор propagate=True для этого события; при значении True функция слушателя будет установлена для всех копий, созданных для целевого объекта, т.е. тех копий, которые создаются при использовании Table.to_metadata().

method sqlalchemy.events.DDLEvents.before_parent_attach(target: SchemaEventTarget, parent: SchemaItem) → None¶

Вызывается перед тем, как SchemaItem ассоциируется с родительским SchemaItem.

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

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'before_parent_attach')
def receive_before_parent_attach(target, parent):
    "listen for the 'before_parent_attach' event"

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

Параметры:

• target – целевой объект

• parent – родитель, к которому присоединяется цель.

listen() также принимает модификатор propagate=True для этого события; при значении True функция слушателя будет установлена для всех копий, созданных для целевого объекта, т.е. тех копий, которые создаются при использовании Table.to_metadata().

method sqlalchemy.events.DDLEvents.column_reflect(inspector: Inspector, table: Table, column_info: ReflectedColumn) → None¶

Вызывается для каждой единицы „column info“, полученной при отражении Table.

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

from sqlalchemy import event


@event.listens_for(SomeSchemaClassOrObject, 'column_reflect')
def receive_column_reflect(inspector, table, column_info):
    "listen for the 'column_reflect' event"

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

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

metadata = MetaData()

@event.listens_for(metadata, 'column_reflect')
def receive_column_reflect(inspector, table, column_info):
    # receives for all Table objects that are reflected
    # under this MetaData


# will use the above event hook
my_table = Table("my_table", metadata, autoload_with=some_engine)

Добавлено в версии 1.4.0b2: Теперь хук DDLEvents.column_reflect() можно применять как к объекту MetaData, так и к самому классу MetaData, где он будет действовать для всех объектов Table, связанных с целевым MetaData.

Его также можно применить к классу Table повсеместно:

from sqlalchemy import Table

@event.listens_for(Table, 'column_reflect')
def receive_column_reflect(inspector, table, column_info):
    # receives for all Table objects that are reflected

Его также можно применить к конкретному Table в тот момент, когда он отражается, используя параметр Table.listeners:

t1 = Table(
    "my_table",
    autoload_with=some_engine,
    listeners=[
        ('column_reflect', receive_column_reflect)
    ]
)

Словарь информации о столбцах, возвращаемый диалектом, передается и может быть изменен. Словарь является тем, что возвращается в каждом элементе списка, возвращаемого командой Inspector.get_columns():

• name - имя колонки, применяется к параметру Column.name

• type - тип этого столбца, который должен быть экземпляром TypeEngine, применяется к параметру Column.type

• nullable - булев флаг, если колонка является NULL или NOT NULL, применяется к параметру Column.nullable

• default - серверное значение столбца по умолчанию. Обычно это значение задается как обычное строковое SQL-выражение, однако событие может передавать и объект FetchedValue, DefaultClause или text(). Применяется к параметру Column.server_default.

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

• key - строковый ключ, который будет использоваться для доступа к данному Column в коллекции .c; будет применен к параметру Column.key. Также используется для отображения ORM. Пример см. в разделе Автоматизация схем именования столбцов из отраженных таблиц.

• quote - принудительное или не принудительное цитирование имени столбца; применяется к параметру Column.quote.

• info - словарь произвольных данных, которые будут следовать вместе с Column, применяется к параметру Column.info.

listen() также принимает модификатор propagate=True для этого события; при значении True функция слушателя будет установлена для всех копий, созданных для целевого объекта, т.е. тех копий, которые создаются при использовании Table.to_metadata().

См.также

Автоматизация схем именования столбцов из отраженных таблиц - в документации по отображению ORM

Определения перехватывающих колонок - в документации Automap

Отражение с помощью типов, не зависящих от базы данных - в документации Отражение объектов базы данных

attribute sqlalchemy.events.DDLEvents.dispatch: _Dispatch[_ET] = <sqlalchemy.event.base.DDLEventsDispatch object>¶

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

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

Базовый класс для элементов, которые являются целями событий DDLEvents.

Это включает в себя SchemaItem, а также SchemaType.