Scheduler

class scheduler.asyncio.scheduler.Scheduler(*, loop: BaseSelectorEventLoop | None = None, tzinfo: tzinfo | None = None, logger: Logger | None = None)

Bases: BaseScheduler[Job, Callable[[…], Coroutine[Any, Any, None]]]

Implementation of an asyncio scheduler.

This implementation enables the planning of Jobs depending on time cycles, fixed times, weekdays, dates, offsets and execution counts.

Parameters:

loopasyncio.selector_events.BaseSelectorEventLoop

Set a AsyncIO event loop, default is the global event loop

tzinfodatetime.tzinfo

Set the timezone of the Scheduler.

loggerOptional[logging.Logger]

A custom Logger instance.

Notes

Due to the support of datetime objects, the Scheduler is able to work with timezones.

Methods

__init__(*[, loop, tzinfo, logger])
cyclic(timing, handle, **kwargs)	Schedule a cyclic Job.
daily(timing, handle, **kwargs)	Schedule a daily Job.
delete_job(job)	Delete a Job from the Scheduler.
delete_jobs([tags, any_tag])	Delete a set of Jobs from the Scheduler by tags.
get_jobs([tags, any_tag])	Get a set of Jobs from the Scheduler by tags.
hourly(timing, handle, **kwargs)	Schedule an hourly Job.
minutely(timing, handle, **kwargs)	Schedule a minutely Job.
once(timing, handle, *[, args, kwargs, ...])	Schedule a oneshot Job.
weekly(timing, handle, **kwargs)	Schedule a weekly Job.

Attributes

jobs	Get the set of all Jobs.

cyclic(timing: timedelta, handle: Callable[[...], Coroutine[Any, Any, None]], **kwargs) → Job

Schedule a cyclic Job.

Use a datetime.timedelta object or a list of datetime.timedelta objects to schedule a cyclic Job.

Parameters:

timingTimingTypeCyclic

Desired execution time.

handleCallable[…, Coroutine[Any, Any, None]]

Handle to a callback function.

Returns:

Job

Instance of a scheduled Job.

Other Parameters:

**kwargs

Job properties, optional

kwargs are used to specify Job properties.

Here is a list of available Job properties:

args	Positional argument payload for the function handle within a Job.
kwargs	Keyword arguments payload for the function handle within a Job.
max_attempts	Number of times the Job will be executed where 0 <=> inf. A Job with no free attempt will be deleted.
tags	A set of str identifiers for a Job.
delay	Deprecated: If True wait with the execution for the next scheduled time.
start	Set the reference datetime.datetime stamp the Job will be scheduled against. Default value is datetime.datetime.now().
stop	Define a point in time after which a Job will be stopped and deleted.
skip_missing	If True a Job will only schedule it’s newest planned execution and drop older ones.
alias	Overwrites the function handle name in the string representation.

daily(timing: time | list[datetime.time], handle: Callable[[...], Coroutine[Any, Any, None]], **kwargs) → Job

Schedule a daily Job.

Use a datetime.time object or a list of datetime.time objects to schedule a Job every day.

Parameters:

timingTimingDailyUnion

Desired execution time(s).

handleCallable[…, Coroutine[Any, Any, None]]

Handle to a callback function.

Returns:

Job

Instance of a scheduled Job.

Other Parameters:

**kwargs

Job properties, optional

kwargs are used to specify Job properties.

Here is a list of available Job properties:

args	Positional argument payload for the function handle within a Job.
kwargs	Keyword arguments payload for the function handle within a Job.
max_attempts	Number of times the Job will be executed where 0 <=> inf. A Job with no free attempt will be deleted.
tags	A set of str identifiers for a Job.
delay	Deprecated: If True wait with the execution for the next scheduled time.
start	Set the reference datetime.datetime stamp the Job will be scheduled against. Default value is datetime.datetime.now().
stop	Define a point in time after which a Job will be stopped and deleted.
skip_missing	If True a Job will only schedule it’s newest planned execution and drop older ones.
alias	Overwrites the function handle name in the string representation.

delete_job(job: Job) → None

Delete a Job from the Scheduler.

Parameters:

jobJob

Job instance to delete.

Raises:

SchedulerError

Raises if the Job of the argument is not scheduled.

delete_jobs(tags: set[str] | None = None, any_tag: bool = False) → int

Delete a set of Jobs from the Scheduler by tags.

If no tags or an empty set of tags are given defaults to the deletion of all Jobs.

Parameters:

tagsOptional[set[str]]

Set of tags to identify target Jobs.

any_tagbool

False: To delete a Job all tags have to match. True: To delete a Job at least one tag has to match.

get_jobs(tags: set[str] | None = None, any_tag: bool = False) → set[scheduler.asyncio.job.Job]

Get a set of Jobs from the Scheduler by tags.

If no tags or an empty set of tags are given defaults to returning all Jobs.

Parameters:

tagsset[str]

Tags to filter scheduled Jobs. If no tags are given all Jobs are returned.

any_tagbool

False: To match a Job all tags have to match. True: To match a Job at least one tag has to match.

Returns:

set[Job]

Currently scheduled Jobs.

hourly(timing: time | list[datetime.time], handle: Callable[[...], Coroutine[Any, Any, None]], **kwargs) → Job

Schedule an hourly Job.

Use a datetime.time object or a list of datetime.time objects to schedule a Job every hour.

Parameters:

timingTimingDailyUnion

Desired execution time(s).

handleCallable[…, Coroutine[Any, Any, None]]

Handle to a callback function.

Returns:

Job

Instance of a scheduled Job.

Other Parameters:

**kwargs

Job properties, optional

kwargs are used to specify Job properties.

Here is a list of available Job properties:

args	Positional argument payload for the function handle within a Job.
kwargs	Keyword arguments payload for the function handle within a Job.
max_attempts	Number of times the Job will be executed where 0 <=> inf. A Job with no free attempt will be deleted.
tags	A set of str identifiers for a Job.
delay	Deprecated: If True wait with the execution for the next scheduled time.
start	Set the reference datetime.datetime stamp the Job will be scheduled against. Default value is datetime.datetime.now().
stop	Define a point in time after which a Job will be stopped and deleted.
skip_missing	If True a Job will only schedule it’s newest planned execution and drop older ones.
alias	Overwrites the function handle name in the string representation.

Notes

If given a datetime.time object with a non zero hour property, this information will be ignored.

property jobs: set[scheduler.asyncio.job.Job]

Get the set of all Jobs.

Returns:

set[Job]

Currently scheduled Jobs.

minutely(timing: time | list[datetime.time], handle: Callable[[...], Coroutine[Any, Any, None]], **kwargs) → Job

Schedule a minutely Job.

Use a datetime.time object or a list of datetime.time objects to schedule a Job every minute.

Parameters:

timingTimingDailyUnion

Desired execution time(s).

handleCallable[…, Coroutine[Any, Any, None]]

Handle to a callback function.

Returns:

Job

Instance of a scheduled Job.

Other Parameters:

**kwargs

Job properties, optional

kwargs are used to specify Job properties.

Here is a list of available Job properties:

args	Positional argument payload for the function handle within a Job.
kwargs	Keyword arguments payload for the function handle within a Job.
max_attempts	Number of times the Job will be executed where 0 <=> inf. A Job with no free attempt will be deleted.
tags	A set of str identifiers for a Job.
delay	Deprecated: If True wait with the execution for the next scheduled time.
start	Set the reference datetime.datetime stamp the Job will be scheduled against. Default value is datetime.datetime.now().
stop	Define a point in time after which a Job will be stopped and deleted.
skip_missing	If True a Job will only schedule it’s newest planned execution and drop older ones.
alias	Overwrites the function handle name in the string representation.

Notes

If given a datetime.time object with a non zero hour or minute property, these information will be ignored.

once(timing: datetime | timedelta | Weekday | time, handle: Callable[[...], Coroutine[Any, Any, None]], *, args: tuple[Any, ...] | None = None, kwargs: dict[str, Any] | None = None, tags: Iterable[str] | None = None, alias: str | None = None) → Job

Schedule a oneshot Job.

Parameters:

timingTimingOnceUnion

Desired execution time.

handleCallable[…, Coroutine[Any, Any, None]]

Handle to a callback function.

argstuple[Any]

Positional argument payload for the function handle within a Job.

kwargsOptional[dict[str, Any]]

Keyword arguments payload for the function handle within a Job.

tagsOptional[Iterable[str]]

The tags of the Job.

aliasOptional[str]

Overwrites the function handle name in the string representation.

Returns:

Job

Instance of a scheduled Job.

weekly(timing: Weekday | list[scheduler.trigger.core.Weekday], handle: Callable[[...], Coroutine[Any, Any, None]], **kwargs) → Job

Schedule a weekly Job.

Use a tuple of a Weekday and a datetime.time object to define a weekly recurring Job. Combine multiple desired tuples in a list. If the planed execution time is 00:00 the datetime.time object can be ignored, just pass a Weekday without a tuple.

Parameters:

timingTimingWeeklyUnion

Desired execution time(s).

handleCallable[…, Coroutine[Any, Any, None]]

Handle to a callback function.

Returns:

Job

Instance of a scheduled Job.

Other Parameters:

**kwargs

Job properties, optional

kwargs are used to specify Job properties.

Here is a list of available Job properties:

args	Positional argument payload for the function handle within a Job.
kwargs	Keyword arguments payload for the function handle within a Job.
max_attempts	Number of times the Job will be executed where 0 <=> inf. A Job with no free attempt will be deleted.
tags	A set of str identifiers for a Job.
delay	Deprecated: If True wait with the execution for the next scheduled time.
start	Set the reference datetime.datetime stamp the Job will be scheduled against. Default value is datetime.datetime.now().
stop	Define a point in time after which a Job will be stopped and deleted.
skip_missing	If True a Job will only schedule it’s newest planned execution and drop older ones.
alias	Overwrites the function handle name in the string representation.