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)

As func is not defined here, the event is realized at its first check (made after interval so 60 seconds).

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 check 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.

The check is made each interval, so here: each 60 seconds.

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)

An error is raised if the event is not found.

Internal usage