EventHandler

  • full name: tenpy.tools.events.EventHandler

  • parent module: tenpy.tools.events

  • type: class

Inheritance Diagram

Inheritance diagram of tenpy.tools.events.EventHandler

Methods

EventHandler.__init__([arg_descr])

Initialize self.

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)[source]

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()[source]

Make a (shallow) copy.

connect(callback=None, priority=0)[source]

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.

Returns

callback – The callback function exactly as given.

Return type

callable

connect_by_name(module_name, func_name, kwargs=None, priority=0)[source]

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.

  • kwargs (dict) – Optional extra keyword-arguments to be given to the function.

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

disconnect(listener_id)[source]

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)[source]

Call the callback functions of all listeners.

Returns

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

Return type

list

emit_until_result(*args, **kwargs)[source]

Call the listeners callback until one returns not None.