Events

A module can register events: a deferred function call will be made after defined delay or when some kind of user-defined event occurs (like a change on a webpage, ...).

Create an event

Remember that you have to register the event through the context after creating one.

This is all existing argument that can be use to create an event:

call: function to call when the event is realized;
call_data: argument(s) (single, list or dict) to pass as argument to the call function;
func: function called to retrieve new data;
func_data: argument(s) (single, list or dict) to pass as argument OR if no func, initial data to watch;
cmp: boolean function called to check if there are some changes;
cmp_data: argument(s) (single, list or dict) to pass as argument OR if no cmp, data compared to previous;
interval: time in seconds between each check (default: 60);
offset: time in seconds added to interval before the first check (default: 0);
times: number of times the event has to be realized before being removed; -1 for no limit (default: 1).

In details: use cmp function is datas returns by func isn't a string.

Samples

Call my function once, after 60 seconds

def action():
    print("Action!")

evt = Event(call=action)

Call my function twice, after 60 seconds and 90 seconds

def action():
    print("Action!")

evt = Event(call=action, offset=30, interval=30, times=2)

First call is made after offset+interval, second is made after interval.

Call my function once, when a webpage is modified

from urllib.request import urlopen

def modified():
    print("Page modified!")

evt = Event(func=lambda url: urlopen(url, timeout=10).read().decode(), func_data="http://duckduckgo.com/", call=modified)

At event creation, as cmp_data is not defined, a first call is made to func to get initial page state.

Best practices

%TODO

Event's life

Registration

After creating the event, register it by adding it to context though:

eid = context.register_event(my_event)

If the event is correctly registered, the function returns an event id that you can easily store for further action on the event.

Retrieve a previously registered event

If you want to access or modify the event after its launch, you can retrieve it by its event id:

evt = context.retrieve_event(my_eid)

Cancel an event

You can cancel an event by calling the cancel_event of the context, with the event or just the event id:

context.cancel_event(my_evt)
context.cancel_event(my_eid)

Internal usage