Scheduler

Anything that depends on a time is handled by the Scheduler. The general idea is that the scheduler will wait do an async wait until the next scheduled event, and if anything happens

Scheduler Entry Structure

Each entry in the schedule (self.AD.sched.schedule) contains the following fields:

Field	Type	Description
`name`	`str`	The name of the scheduled callback (usually the method name)
`id`	`str`	Unique identifier for this scheduled entry
`callback`	`functools.partial`	The callback function to be executed, wrapped with bound method
`timestamp`	`datetime.datetime`	The next scheduled execution time (timezone-aware)
`interval`	`datetime.timedelta`	Time interval between repeated executions (0 for one-time callbacks)
`basetime`	`datetime.datetime`	The base time used for calculating subsequent executions
`repeat`	`bool`	Whether this callback should repeat after execution
`offset`	`datetime.timedelta`	Time offset applied to the base time for scheduling
`random_start`	`datetime.timedelta \| None`	Start of random time window (if using random scheduling)
`random_end`	`datetime.timedelta \| None`	End of random time window (if using random scheduling)
`type`	`str`	Type of schedule (e.g., ‘next_rising’, ‘interval’, ‘cron’)
`pin_app`	`bool`	Whether to pin this callback to a specific app thread
`pin_thread`	`int`	The thread number to pin this callback to (0 for main thread)
`kwargs`	`dict`	Additional keyword arguments to pass to the callback

Reference

class appdaemon.scheduler.Scheduler(ad: AppDaemon)

AppDaemon subsystem to manage internal scheduling, calculate the times of sun-based events, and parse datetime strings.

property active: bool: Whether the core scheduler loop is running.

async get_next_period(interval: TimeDeltaLike, start: time | datetime | str | None = None) → datetime

Calculate the next execution time for a periodic interval.

If start is “immediate”, returns the current time. Otherwise, calculates a start time (defaulting to “now”) and advances by the interval until a future time is reached.

async get_now(tz: str | BaseTzInfo | None = None) → datetime

Get the current time for the scheduler.

The time represented will be the same regardless of the timestamp. The timezone only influences how the time is displayed.

Parameters:: tz – The timezone to use for the current time. If None, uses the timezone configured in appdaemon.yaml.

async loop(): Core scheduler loop, which processes scheduled callbacks and sleeping between them.

make_naive(dt: datetime) → datetime

Convert a timezone-aware datetime to a naive datetime in local timezone.

This is used for display purposes only. The scheduler internally works with timezone-aware UTC datetimes.

async parse_datetime(input_: str | time | datetime, aware: bool = False, today: bool | None = None, days_offset: int = 0, *, now: datetime | None = None) → datetime

Parse a variety of inputs into a datetime object.

Parameters:

input (str | time | datetime) – The input to parse. Can be a string, time, or datetime object.
aware (bool, optional) – If False, the resulting datetime will be naive (without timezone). Defaults to True.
today (bool, optional) – If True, forces the result to have the same date as the now datetime. False is effectively equivalent to next. The default value is None, which doesn’t try to coerce the output at all. This results in slightly different date results for different input types. For example, a time string will be given the same date as the one in the now datetime, but a sun event string will be the datetime of the next one.
days_offset (int, optional) – Number of days to offset from the current date for sunrise/sunset parsing. If this is negative, this will unset the today argument, which allows the result to be in the past.
now (datetime, optional) – The current time to use as reference. If not provided, will call get_now().

property realtime: bool: Whether the scheduler is running in real time (timewarp == 1).

async reset_timer(name: str, handle: str) → bool: Only used by the ADAPI to reset an internal timer.

async restart_timer(uuid_: str, args: dict[str, Any]) → dict: Used to restart a timer. This directly modifies the internal schedule dict.

static sanitize_timer_kwargs(app: ADBase, kwargs: dict) → dict: Removes keywords from the keywords

start() → None: Starts the scheduler, which creates the the async task for loop() and adds some cleanup callbacks using the Python-native add_done_callback().

stop() → None: Stops the scheduler by cancelling the task for loop()

timer_running(name: str, handle: str) → bool: Check if the handler is still running by checking for the existence of the handle in the schedule.