module documentation

Public API functions for the event system.
Constant CANCEL Undocumented
Constant NO​_RETVAL Undocumented
Function ​_event​_key Undocumented
Function contains Return True if the given target/ident/fn is set up to listen.
Function listen Register a listener function for the given target.
Function listens​_for Decorate a function as a listener for the given target + identifier.
Function remove Remove an event listener.
CANCEL =

Undocumented

Value
util.symbol('CANCEL')
NO_RETVAL =

Undocumented

Value
util.symbol('NO_RETVAL')
def _event_key(target, identifier, fn):

Undocumented

def contains(target, identifier, fn):
Return True if the given target/ident/fn is set up to listen.
def listen(target, identifier, fn, *args, **kw):

Register a listener function for the given target.

The .listen function is part of the primary interface for the SQLAlchemy event system, documented at :ref:`event_toplevel`.

e.g.:

from sqlalchemy import event
from sqlalchemy.schema import UniqueConstraint

def unique_constraint_name(const, table):
    const.name = "uq_%s_%s" % (
        table.name,
        list(const.columns)[0].name
    )
event.listen(
        UniqueConstraint,
        "after_parent_attach",
        unique_constraint_name)

Note

The .listen function cannot be called at the same time that the target event is being run. This has implications for thread safety, and also means an event cannot be added from inside the listener function for itself. The list of events to be run are present inside of a mutable collection that can't be changed during iteration.

Event registration and removal is not intended to be a "high velocity" operation; it is a configurational operation. For systems that need to quickly associate and deassociate with events at high scale, use a mutable structure that is handled from inside of a single listener.

See Also

.listens_for

.remove

Parameters
targetUndocumented
identifierUndocumented
fnUndocumented
*argsUndocumented
**kwUndocumented
bool insertThe default behavior for event handlers is to append the decorated user defined function to an internal list of registered event listeners upon discovery. If a user registers a function with insert=True, SQLAlchemy will insert (prepend) the function to the internal list upon discovery. This feature is not typically used or recommended by the SQLAlchemy maintainers, but is provided to ensure certain user defined functions can run before others, such as when :ref:`Changing the sql_mode in MySQL <mysql_sql_mode>`.
bool namedWhen using named argument passing, the names listed in the function argument specification will be used as keys in the dictionary. See :ref:`event_named_argument_styles`.
bool oncePrivate/Internal API usage. Deprecated. This parameter would provide that an event function would run only once per given target. It does not however imply automatic de-registration of the listener function; associating an arbitrarily high number of listeners without explicitly removing them will cause memory to grow unbounded even if once=True is specified.
bool propagateThe propagate kwarg is available when working with ORM instrumentation and mapping events. See _ormevent.MapperEvents and _ormevent.MapperEvents.before_mapper_configured for examples.
bool retval

This flag applies only to specific event listeners, each of which includes documentation explaining when it should be used. By default, no listener ever requires a return value. However, some listeners do support special behaviors for return values, and include in their documentation that the retval=True flag is necessary for a return value to be processed.

Event listener suites that make use of :paramref:`_event.listen.retval` include _events.ConnectionEvents and _ormevent.AttributeEvents.

def listens_for(target, identifier, *args, **kw):

Decorate a function as a listener for the given target + identifier.

The .listens_for decorator is part of the primary interface for the SQLAlchemy event system, documented at :ref:`event_toplevel`.

This function generally shares the same kwargs as .listens.

e.g.:

from sqlalchemy import event
from sqlalchemy.schema import UniqueConstraint

@event.listens_for(UniqueConstraint, "after_parent_attach")
def unique_constraint_name(const, table):
    const.name = "uq_%s_%s" % (
        table.name,
        list(const.columns)[0].name
    )

A given function can also be invoked for only the first invocation of the event using the once argument:

@event.listens_for(Mapper, "before_configure", once=True)
def on_config():
    do_config()

Warning

The once argument does not imply automatic de-registration of the listener function after it has been invoked a first time; a listener entry will remain associated with the target object. Associating an arbitrarily high number of listeners without explicitly removing them will cause memory to grow unbounded even if once=True is specified.

See Also

.listen - general description of event listening

def remove(target, identifier, fn):

Remove an event listener.

The arguments here should match exactly those which were sent to .listen; all the event registration which proceeded as a result of this call will be reverted by calling .remove with the same arguments.

e.g.:

# if a function was registered like this...
@event.listens_for(SomeMappedClass, "before_insert", propagate=True)
def my_listener_function(*arg):
    pass

# ... it's removed like this
event.remove(SomeMappedClass, "before_insert", my_listener_function)

Above, the listener function associated with SomeMappedClass was also propagated to subclasses of SomeMappedClass; the .remove function will revert all of these operations.

Note

The .remove function cannot be called at the same time that the target event is being run. This has implications for thread safety, and also means an event cannot be removed from inside the listener function for itself. The list of events to be run are present inside of a mutable collection that can't be changed during iteration.

Event registration and removal is not intended to be a "high velocity" operation; it is a configurational operation. For systems that need to quickly associate and deassociate with events at high scale, use a mutable structure that is handled from inside of a single listener.

Changed in version 1.0.0: - a collections.deque() object is now used as the container for the list of events, which explicitly disallows collection mutation while the collection is being iterated.

See Also

.listen