bootstack.scheduling.Schedule#

class bootstack.scheduling.Schedule(owner)#

Bases: object

Timed task scheduler tied to a widget’s lifetime.

Runs callbacks after a delay, at idle, at an absolute time, or on a repeat, with automatic cleanup: all pending jobs are cancelled when the owner widget is destroyed.

Usage:

sched = widget.schedule          # property on every public widget
sched = Schedule(widget)      # or construct directly

job = sched.delay(500, callback)   # one-shot after delay
sched.idle(callback)               # one-shot at next idle
sched.at(datetime(...), callback)  # one-shot at absolute time
job = sched.every(1000, tick)      # repeating every 1 second

job.cancel()        # cancel one job
sched.cancel_all()  # cancel everything

All jobs are automatically cancelled when owner is destroyed.

Parameters:

owner (Any) – Widget that owns this scheduler. Its lifetime bounds all created jobs.

at(when, fn, *args, **kwargs)#

Schedule fn to run at an absolute datetime.

If when is in the past the job runs as soon as possible.

Parameters:

  • when (datetime) – Target datetime (local time).

  • fn (Callable) – Callable to invoke.

  • *args (Any) – Positional arguments forwarded to fn.

  • **kwargs (Any) – Keyword arguments forwarded to fn.

Returns:

Job handle.

Return type:

Job

cancel_all()#

Cancel all pending jobs created by this Schedule.

delay(ms, fn, *args, **kwargs)#

Schedule fn to run once after ms milliseconds.

Parameters:

  • ms (int) – Delay in milliseconds (clamped to 0).

  • fn (Callable) – Callable to invoke.

  • *args (Any) – Positional arguments forwarded to fn.

  • **kwargs (Any) – Keyword arguments forwarded to fn.

Returns:

Job handle — call .cancel() to prevent execution.

Return type:

Job

every(ms, fn, *args, **kwargs)#

Schedule fn to run repeatedly every ms milliseconds.

Compensates for callback execution time to reduce drift. If the callback raises an exception the interval is stopped and the exception is re-raised into the application’s error handler.

Parameters:

  • ms (int) – Period in milliseconds (minimum 1).

  • fn (Callable) – Callable to invoke on each tick.

  • *args (Any) – Positional arguments forwarded to fn.

  • **kwargs (Any) – Keyword arguments forwarded to fn.

Returns:

Job handle — call .cancel() to stop the repeating task.

Return type:

Job

idle(fn, *args, **kwargs)#

Schedule fn to run once when the event loop is next idle.

Parameters:

  • fn (Callable) – Callable to invoke.

  • *args (Any) – Positional arguments forwarded to fn.

  • **kwargs (Any) – Keyword arguments forwarded to fn.

Returns:

Job handle — call .cancel() to prevent execution.

Return type:

Job