sqlalchemy.engine.events.DialectEvents

class documentation

class DialectEvents(event.Events):

View In Hierarchy

event interface for execution-replacement functions.

These events allow direct instrumentation and replacement of key dialect functions which interact with the DBAPI.

Note

.DialectEvents hooks should be considered semi-public and experimental. These hooks are not for general use and are only for those situations where intricate re-statement of DBAPI mechanics must be injected onto an existing dialect. For general-use statement-interception events, please use the _events.ConnectionEvents interface.

See Also

_events.ConnectionEvents.before_cursor_execute

_events.ConnectionEvents.before_execute

_events.ConnectionEvents.after_cursor_execute

_events.ConnectionEvents.after_execute

New in version 0.9.4.
Class Method ​_accept​_with Undocumented
Class Method ​_listen Undocumented
Method do​_connect Receive connection arguments before a connection is made.
Method do​_execute Receive a cursor to have execute() called.
Method do​_execute​_no​_params Receive a cursor to have execute() with no parameters called.
Method do​_executemany Receive a cursor to have executemany() called.
Method do​_setinputsizes Receive the setinputsizes dictionary for possible modification.
Class Variable ​_target​_class​_doc Undocumented

Inherited from Events:

Class Method ​_clear Undocumented
Class Method ​_remove Undocumented
Static Method ​_set​_dispatch Undocumented
@classmethod
def _accept_with(cls, target):
overrides sqlalchemy.event.base.Events._accept_with

Undocumented

@classmethod
def _listen(cls, event_key, retval=False):
overrides sqlalchemy.event.base.Events._listen

Undocumented

def do_connect(self, dialect, conn_rec, cargs, cparams):

Receive connection arguments before a connection is made.

This event is useful in that it allows the handler to manipulate the cargs and/or cparams collections that control how the DBAPI connect() function will be called. cargs will always be a Python list that can be mutated in-place, and cparams a Python dictionary that may also be mutated:

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"

The event hook may also be used to override the call to connect() entirely, by returning a non-None DBAPI connection object:

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)
New in version 1.0.3.

See Also

:ref:`custom_dbapi_args`

def do_execute(self, cursor, statement, parameters, context):

Receive a cursor to have execute() called.

Return the value True to halt further events from invoking, and to indicate that the cursor execution has already taken place within the event handler.

def do_execute_no_params(self, cursor, statement, context):

Receive a cursor to have execute() with no parameters called.

Return the value True to halt further events from invoking, and to indicate that the cursor execution has already taken place within the event handler.

def do_executemany(self, cursor, statement, parameters, context):

Receive a cursor to have executemany() called.

Return the value True to halt further events from invoking, and to indicate that the cursor execution has already taken place within the event handler.

def do_setinputsizes(self, inputsizes, cursor, statement, parameters, context):

Receive the setinputsizes dictionary for possible modification.

This event is emitted in the case where the dialect makes use of the DBAPI cursor.setinputsizes() method which passes information about parameter binding for a particular statement. The given inputsizes dictionary will contain .BindParameter objects as keys, linked to DBAPI-specific type objects as values; for parameters that are not bound, they are added to the dictionary with None as the value, which means the parameter will not be included in the ultimate setinputsizes call. The event may be used to inspect and/or log the datatypes that are being bound, as well as to modify the dictionary in place. Parameters can be added, modified, or removed from this dictionary. Callers will typically want to inspect the .BindParameter.type attribute of the given bind objects in order to make decisions about the DBAPI object.

After the event, the inputsizes dictionary is converted into an appropriate datastructure to be passed to cursor.setinputsizes; either a list for a positional bound parameter execution style, or a dictionary of string parameter keys to DBAPI type objects for a named bound parameter execution style.

The setinputsizes hook overall is only used for dialects which include the flag use_setinputsizes=True. Dialects which use this include cx_Oracle, pg8000, asyncpg, and pyodbc dialects.

Note

For use with pyodbc, the use_setinputsizes flag must be passed to the dialect, e.g.:

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

See Also

:ref:`mssql_pyodbc_setinputsizes`

New in version 1.2.9.

See Also

:ref:`cx_oracle_setinputsizes`

_target_class_doc: str =

Undocumented