This feature is experimental.

Flatland can notify your code when events of interest occur during flatland processing. These signals can be used for advanced customization in your application or simply as a means for tracing and logging flatland activity during development.

Using Signals

To receive a signal, all you need is a function that can accept keyword arguments:

>>> def receiver(**kw):
...   print "Look what I got!", kw

Receiving functions are connected to one or more signals you’d like to receive:

>>> from flatland import signals
>>> signals.validator_validated.connect(receiver)

That’s it. Now each time flatland runs a validator, the receiver function will be called and passed some information about the validation that just occured. There is no limit to the number of receivers connected to a signal.

Built-In Signals


Emitted after a validator has processed an element.

  • sender – the validator
  • element – the element being validated
  • state – the state passed to validate()
  • result – the result of validator execution

Signal API

signal(self, name, doc=None)
Return the NamedSignal name, creating it if required.
class Signal(doc=None)

A generic notification emitter.

A symbol for “receive a signal sent by any sender”.
A mapping from internal Signal receiver ids to signal receivers or their weak references if the receiver connected with weak=True.
connect(receiver, sender=ANY, weak=True)

Connect receiver to signal events send by sender.

  • receiver – A callable. Will be invoked by send(). Will be invoked with sender= as a named argument and any **kwargs that were provided to a call to send().
  • sender – Any object or Signal.ANY. Restricts notifications to receiver to only those send() emissions sent by sender. If ANY, the receiver will always be notified. A receiver may be connected to multiple sender on the same Signal. Defaults to ANY.
  • weak – If true, the Signal will hold a weakref to receiver and automatically disconnect when receiver goes out of scope or is garbage collected. Defaults to True.
disconnect(receiver, sender=ANY)
Disconnect receiver from this signal’s events.

True if there is probably a receiver for sender.

Performs an optimistic check for receivers only. Does not guarantee that all weakly referenced receivers are still alive. See receivers_for() for a stronger search.

Iterate all live receivers listening for sender.
send(sender=None, **kwargs)

Emit this signal on behalf of sender, passing on **kwargs.

Returns a list of 2-tuples, pairing receivers with their return value. The ordering of receiver notification is undefined.