# `events`

The events module is accessible via the `sqlobject` module.

## Attributes

#### a `__package__`

    'sqlobject'

## Functions

#### f `listen(receiver, soClass, signal, alsoSubclasses=True, weak=True)` ...

Listen for the given `signal` on the SQLObject subclass `soClass`, calling `receiver()` when `send(soClass, signal, ...)` is called.

If `alsoSubclasses` is true, receiver will also be called when an event is fired on any subclass.

#### f `send(signal=_Any, sender=_Anonymous, *arguments, **named)` ...

Send signal from sender to all connected receivers.

signal -- (hashable) signal value, see connect for details

sender -- the sender of the signal

> if Any, only receivers registered for Any will receive the message.

> if Anonymous, only receivers registered to receive messages from Anonymous or Any will receive the message

> Otherwise can be any python object (normally one registered with a connect if you actually want something to occur).

arguments -- positional arguments which will be passed to
  all receivers. Note that this may raise TypeErrors if the receivers do not allow the particular arguments. Note also that arguments are applied before named arguments, so they should be used with care.
named -- named arguments which will be filtered according
  to the parameters of the receivers to only provide those acceptable to the receiver.

Return a list of tuple pairs [(receiver, response), ... ]

if any receiver raises an error, the error propagates back through send, terminating the dispatch loop, so it is quite possible to not have all receivers called if a raises an error.

## Classes

#### C `Signal(...)` ...

Base event for all SQLObject events.

In general the sender for these methods is the class, not the instance.

This class contains 4 members.

#### C `ClassCreateSignal(...)` ...

Signal raised after class creation. The sender is the superclass (in case of multiple superclasses, the first superclass). The arguments are `(new_class_name, bases, new_attrs, post_funcs, early_funcs)`. `new_attrs` is a dictionary and may be modified (but `new_class_name` and `bases` are immutable). `post_funcs` is an initially-empty list that can have callbacks appended to it.

Note: at the time this event is called, the new class has not yet been created. The functions in `post_funcs` will be called after the class is created, with the single arguments of `(new_class)`. Also, `early_funcs` will be called at the soonest possible time after class creation (`post_funcs` is called after the class's `__classinit__`).

This class contains 4 members.

#### C `RowCreateSignal(...)` ...

Called before an instance is created, with the class as the sender. Called with the arguments `(instance, kwargs, post_funcs)`. There may be a `connection` argument. `kwargs``may be usefully modified. ``post_funcs` is a list of callbacks, intended to have functions appended to it, and are called with the arguments `(new_instance)`.

Note: this is not called when an instance is created from an existing database row.

This class contains 4 members.

#### C `RowCreatedSignal(...)` ...

Called after an instance is created, with the class as the sender. Called with the arguments `(instance, kwargs, post_funcs)`. There may be a `connection` argument. `kwargs``may be usefully modified. ``post_funcs` is a list of callbacks, intended to have functions appended to it, and are called with the arguments `(new_instance)`.

Note: this is not called when an instance is created from an existing database row.

This class contains 4 members.

#### C `RowDestroySignal(...)` ...

Called before an instance is deleted. Sender is the instance's class. Arguments are `(instance, post_funcs)`.

`post_funcs` is a list of callbacks, intended to have functions appended to it, and are called with arguments `(instance)`. If any of the post_funcs raises an exception, the deletion is only affected if this will prevent a commit.

You cannot cancel the delete, but you can raise an exception (which will probably cancel the delete, but also cause an uncaught exception if not expected).

Note: this is not called when an instance is destroyed through garbage collection.

@@: Should this allow `instance` to be a primary key, so that a row can be deleted without first fetching it?

This class contains 4 members.

#### C `RowDestroyedSignal(...)` ...

Called after an instance is deleted. Sender is the instance's class. Arguments are `(instance)`.

This is called before the post_funcs of RowDestroySignal

Note: this is not called when an instance is destroyed through garbage collection.

This class contains 4 members.

#### C `RowUpdateSignal(...)` ...

Called when an instance is updated through a call to `.set()` (or a column attribute assignment). The arguments are `(instance, kwargs)`. `kwargs` can be modified. This is run before the instance is updated; if you want to look at the current values, simply look at `instance`.

This class contains 4 members.

#### C `RowUpdatedSignal(...)` ...

Called when an instance is updated through a call to `.set()` (or a column attribute assignment). The arguments are `(instance, post_funcs)`. `post_funcs` is a list of callbacks, intended to have functions appended to it, and are called with the arguments `(new_instance)`. This is run after the instance is updated; Works better with lazyUpdate = True.

This class contains 4 members.

#### C `AddColumnSignal(...)` ...

Called when a column is added to a class, with arguments `(cls, connection, column_name, column_definition, changeSchema, post_funcs)`. This is called after the column has been added, and is called for each column after class creation.

post_funcs are called with `(cls, so_column_obj)`

This class contains 4 members.

#### C `DeleteColumnSignal(...)` ...

Called when a column is removed from a class, with the arguments `(cls, connection, column_name, so_column_obj, post_funcs)`. Like `AddColumnSignal` this is called after the action has been performed, and is called for subclassing (when a column is implicitly removed by setting it to `None`).

post_funcs are called with `(cls, so_column_obj)`

This class contains 4 members.

#### C `CreateTableSignal(...)` ...

Called when a table is created. If `ifNotExists==True` and the table exists, this event is not called.

Called with `(cls, connection, extra_sql, post_funcs)`. `extra_sql` is a list (which can be appended to) of extra SQL statements to be run after the table is created. `post_funcs` functions are called with `(cls, connection)` after the table has been created. Those functions are not called simply when constructing the SQL.

This class contains 4 members.

#### C `DropTableSignal(...)` ...

Called when a table is dropped. If `ifExists==True` and the table doesn't exist, this event is not called.

Called with `(cls, connection, extra_sql, post_funcs)`. `post_funcs` functions are called with `(cls, connection)` after the table has been dropped.

This class contains 4 members.

See the source for more information.