EventHandler

• full name: tenpy.tools.events.EventHandler

• parent module: tenpy.tools.events

• type: class

Inheritance Diagram

Methods

EventHandler.__init__([arg_descr])
EventHandler.connect([callback, priority, ...])	Register a callback function as a listener to the event.
EventHandler.connect_by_name(module_name, ...)	Connect to a function given by the name in a module, optionally inserting arguments.
EventHandler.copy()	Make a (shallow) copy.
EventHandler.disconnect(listener_id)	De-register a listener.
EventHandler.emit(*args, **kwargs)	Call the callback functions of all listeners.
EventHandler.emit_until_result(*args, **kwargs)	Call the listeners callback until one returns not None.

Class Attributes and Properties

EventHandler.id_of_last_connected

class tenpy.tools.events.EventHandler(arg_descr=None)

Bases: object

Handler for an event represented by an instance of this class.

All in all, events provide a flexible extension mechanism for classes to define “checkpoints” in the code where the user of a class might want to run something else, for example doing some measurements or saving intermediate results.

Parameters:

arg_descr (str) – An informative description how the callback function is called. An empty string indicates no arguments.

arg_descr

An informative description how the callback function is called.

Type:

str

listeners

Entries are tuples (listener_id, callback, priority).

Type:

list of (int, function, int)

Examples

Instances of this class typically get defined during class initialization and define an event. The event “happens” each time emit() or emit_until_result() is called, typically inside a method of the class defining the event. Example:

>>> class MyAlgorithm:
...     def __init__(self):
...         self.checkpoint = EventHandler("algorithm, iteration")
...         self.data = 0
...     def run(self):
...         for i in range(4):
...             self.data += i # do some complicated stuff
...             self.checkpoint.emit(self, i)

Other code with access to the event can then connect a listener to the event, i.e., give a function to the event that should be called each time the event is emit()-ed.

>>> my_alg = MyAlgorithm()
>>> def my_listener(algorithm, iteration):
...     print("my_listener called: iteration", iteration, "with data", algorithm.data)
>>> my_alg.checkpoint.connect(my_listener)  
<function my_listener at 0x...>
>>> my_alg.run()
my_listener called: iteration 0 with data 0
my_listener called: iteration 1 with data 1
my_listener called: iteration 2 with data 3
my_listener called: iteration 3 with data 6

As you can see, the function my_listener has been called during the MyAlgorithm.run() and had full access to the current status of the algorithm class. This is convenient to e.g. perform measurements of the state so far, print a status message of the progress or save intermediate results.

If the EventHandler is already initialized when you define the function, you can also use connect() as a function property like this:

>>> @my_alg.checkpoint.connect
... def another_one(algorithm, iteration):
...     print("another_one called: iteration", iteration)
>>> @my_alg.checkpoint.connect(priority=5)
... def high_priority(algorithm, iteration):
...     print("high_priority call: iteration", iteration)
>>> my_alg.run()
high_priority call: iteration 0
my_listener called: iteration 0 with data 6
another_one called: iteration 0
high_priority call: iteration 1
my_listener called: iteration 1 with data 7
another_one called: iteration 1
high_priority call: iteration 2
my_listener called: iteration 2 with data 9
another_one called: iteration 2
high_priority call: iteration 3
my_listener called: iteration 3 with data 12
another_one called: iteration 3

copy()

Make a (shallow) copy.

connect(callback=None, priority=0, extra_kwargs=None)

Register a callback function as a listener to the event.

You can either call this function directly or use it as a function decorator, see the example in EventHandler.

If you ever plan to disconnect() again, you can read it out with id_of_last_connected right after connecting, i.e., right after calling this method.

Parameters:

• callback (callable) – A function to be called during each emit() of the event.

• priority (int) – Higher priority indicates that the callback function should be called before other possibly registered callback functions.

• extra_kwargs (None | dict) – Optional extra keyword arguments given directly to the function. None is equivalent to {}.

Returns:

callback – The callback function exactly as given.

Return type:

callable

connect_by_name(module_name, func_name, extra_kwargs=None, priority=0)

Connect to a function given by the name in a module, optionally inserting arguments.

Parameters:

• module_name (str) – The name of the module containing the function to be used. Gets imported.

• func_name (str) – The (qualified) name of the function inside the module.

• extra_kwargs (dict) – Optional extra keyword-arguments to be given to the function. None is equivalent to {}.

• priority (int) – Higher priority indicates that the callback function should be called before other possibly registered callback functions.

disconnect(listener_id)

De-register a listener.

Parameters:

listener_id (int) – The id of the listener, as given by id_of_last_connected right after calling connect().

emit(*args, **kwargs)

Call the callback functions of all listeners.

Parameters:

• *args – (Keyword) arguments to give to the callback functions. Recall that there can also be additional extra_kwargs for each callback function.

• **kwargs – (Keyword) arguments to give to the callback functions. Recall that there can also be additional extra_kwargs for each callback function.

Returns:

results – List of results returned by the individual callback functions.

Return type:

list

emit_until_result(*args, **kwargs)

Call the listeners callback until one returns not None.