Timers

The timed decorator

FIXME: this section is not yet written

kaa.timed(interval, timer=None, policy=POLICY_MANY)

Decorator to call the decorated function in a Timer. When calling the function, a timer will be started with the given interval calling that function. The decorated function will be called from the main thread.

The timer parameter optionally specifies which timer class should be used to wrap the function. kaa.Timer (default) or kaa.WeakTimer will repeatedly invoke the decorated function until it returns False. kaa.OneShotTimer or kaa.WeakOneShotTimer will invoke the function once, delaying it by the specified interval. (In this case the return value of the decorated function is irrelevant.)

The policy parameter controls how multiple invocations of the decorated function should be handled. By default (POLICY_MANY), each invocation of the function will create a new timer, each firing at the specified interval. If policy is POLICY_ONCE, subsequent invocations are ignored while the first timer is still active. If the policy is POLICY_RESTART, subsequent invocations will restart the first timer.

Note that in the case of POLICY_ONCE or POLICY_RESTART, if the timer is currently running, any arguments passed to the decorated function on subsequent calls will be discarded.

Timer Callbacks

FIXME: this section is not yet written

class kaa.Timer(callback, *args, **kwargs)

Invokes the supplied callback after the supplied interval (passed to start()) elapses. The Timer is created stopped.

When the timer interval elapses, we say that the timer is “fired” or “triggered,” at which time the given callback is invoked.

If the callback returns False, then the timer is automatically stopped. If it returns any other value (including None), the timer will continue to fire.

Parameters:

• callback – the callable to be invoked
• args – the arguments to be passed to the callable when it’s invoked
• kwargs – the keyword arguments to be passed to the callable when it’s invoked

Synopsis

Class Hierarchy

kaa.Callable
└─ kaa.nf_wrapper.NotifierCallback
     └─ kaa.Timer

Methods

start()	Start the timer, invoking the callback every interval seconds.
stop()	Stop a running timer.

Properties

interval	read-only	Timer interval when the timer is running, None if not. The interval cannot be changed once the timer is started, and it is set via the start() method.

Signals

This class has no signals.

Methods

start(interval, now=False)

Start the timer, invoking the callback every interval seconds.

Parameters:

• interval (float) – interval between invocations of the callback, in seconds
• now (bool) – if True, invoke the callback once immediately before starting the timer.

If the timer is already running, it is stopped and restarted with the given interval. The timer’s precision is at the mercy of other tasks running in the main loop. For example, if another task (a different timer, or I/O callback) blocks the mainloop for longer than the given timer interval, the callback will be invoked late.

This method may safely be called from a thread, however the timer callback will be invoked from the main thread.

stop()

Stop a running timer.

This method is a no-op if the timer is already stopped. It may also be called from a thread, however if the timer callback is currently executing in the main thread, it will of course have to finish, but it will not be called again unless the timer is restarted.

Properties

interval

Timer interval when the timer is running, None if not. The interval cannot be changed once the timer is started, and it is set via the start() method.

class kaa.WeakTimer(func, *args, **kwargs)

Weak variant of the Timer class.

All references to the callback and supplied args/kwargs are weak references. When any of the underlying objects are deleted, the WeakTimer is automatically stopped.

Synopsis

Class Hierarchy

kaa.Callable
└─ kaa.nf_wrapper.NotifierCallback
└─ kaa.WeakCallable
     └─ kaa.Timer
     └─ kaa.nf_wrapper.WeakNotifierCallback
          └─ kaa.WeakTimer

class kaa.OneShotTimer(callback, *args, **kwargs)

A Timer that gets triggered exactly once when it is started. Useful for deferred one-off tasks.

Gotcha: it is possible to restart a OneShotTimer from inside the callback it invokes, however be careful not to return False in this case, otherwise the freshly started OneShotTimer will be implicitly stopped before it gets a chance to fire.

Parameters:

• callback – the callable to be invoked
• args – the arguments to be passed to the callable when it’s invoked
• kwargs – the keyword arguments to be passed to the callable when it’s invoked

Synopsis

Class Hierarchy

kaa.Callable
└─ kaa.nf_wrapper.NotifierCallback
     └─ kaa.Timer
          └─ kaa.OneShotTimer

class kaa.WeakOneShotTimer(func, *args, **kwargs)

Weak variant of the OneshotTimer class.

All references to the callback and supplied args/kwargs are weak references. When any of the underlying objects are deleted, the WeakTimer is automatically stopped.

Synopsis

Class Hierarchy

kaa.Callable
└─ kaa.nf_wrapper.NotifierCallback
└─ kaa.Callable
     └─ kaa.nf_wrapper.NotifierCallback
     └─ kaa.Timer
     └─ kaa.WeakCallable
          └─ kaa.nf_wrapper.WeakNotifierCallback
          └─ kaa.OneShotTimer
               └─ kaa.WeakOneShotTimer

class kaa.OneShotAtTimer(callback, *args, **kwargs)

A timer that is triggered at a specific time of day. Once the timer fires it is stopped.

Parameters:

• callback – the callable to be invoked
• args – the arguments to be passed to the callable when it’s invoked
• kwargs – the keyword arguments to be passed to the callable when it’s invoked

Synopsis

Class Hierarchy

kaa.Callable
└─ kaa.nf_wrapper.NotifierCallback
     └─ kaa.Timer
          └─ kaa.OneShotTimer
               └─ kaa.OneShotAtTimer

Methods

start()	Starts the timer, causing it to be fired at the specified time.

Methods

start(hour=range(24), min=range(60), sec=0)

Starts the timer, causing it to be fired at the specified time.

By default, the timer will fire every minute at 0 seconds. The timer has second precision.

Parameters:

• hours (int or list of ints) – the hour number (0-23) or list of hours
• minutes (int or list of ints) – the minute number (0-59) or list of minutes
• seconds (int or list of ints) – the second number (0-59) or list of seconds

class kaa.AtTimer(callback, *args, **kwargs)

A timer that is triggered at a specific time or times of day.

Parameters:

• callback – the callable to be invoked
• args – the arguments to be passed to the callable when it’s invoked
• kwargs – the keyword arguments to be passed to the callable when it’s invoked

Synopsis

Class Hierarchy

kaa.Callable
└─ kaa.nf_wrapper.NotifierCallback
     └─ kaa.Timer
          └─ kaa.OneShotTimer
               └─ kaa.OneShotAtTimer
                    └─ kaa.AtTimer