Scheduler

class scheduler.threading.scheduler.Scheduler(*, max_exec: int = 0, tzinfo: ~datetime.tzinfo | None = None, priority_function: ~typing.Callable[[float, ~scheduler.threading.job.Job, int, int], float] = <function linear_priority_function>, jobs: ~collections.abc.Iterable[~scheduler.threading.job.Job] | None = None, n_threads: int = 1, logger: ~logging.Logger | None = None)

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

Implementation of a scheduler for callback functions.

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

Parameters:

tzinfodatetime.tzinfo

Set the timezone of the Scheduler.

max_execint

Limits the number of overdue Jobs that can be executed by calling function Scheduler.exec_jobs().

priority_functionCallable[[float, Job, int, int], float]

A function handle to compute the priority of a Job depending on the time it is overdue and its respective weight. Defaults to a linear priority function.

jobsset[Job]

A collection of job instances.

n_threadsint

The number of worker threads. 0 for unlimited, default 1.

loggerOptional[logging.Logger]

A custom Logger instance.

Notes

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

Methods

__init__(*[, max_exec, tzinfo, ...])
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.
exec_jobs([force_exec_all])	Execute scheduled Jobs.
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[[...], 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[…, 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.
weight	Relative weight against other Jobs.

daily(timing: time | list[datetime.time], handle: Callable[[...], 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[…, 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.
weight	Relative weight against other Jobs.

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 deleta a Job at least one tag has to match.

exec_jobs(force_exec_all: bool = False) → int

Execute scheduled Jobs.

By default executes the Jobs that are overdue.

Jobs are executed in order of their priority Job Prioritization. If the Scheduler instance has a limit on the job execution counts per call of exec_jobs(), via the max_exec argument, Jobs of lower priority might not get executed when competing Jobs are overdue.

Parameters:

force_exec_allbool

Ignore the both - the status of the Job timers as well as the execution limit of the Scheduler

Returns:

int

Number of executed Jobs.

get_jobs(tags: set[str] | None = None, any_tag: bool = False) → set[scheduler.threading.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[[...], 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[…, 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.
weight	Relative weight against other Jobs.

Notes

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

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

Get the set of all Jobs.

Returns:

set[Job]

Currently scheduled Jobs.

minutely(timing: time | list[datetime.time], handle: Callable[[...], 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[…, 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.
weight	Relative weight against other Jobs.

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[[...], None], *, args: tuple[Any] | None = None, kwargs: dict[str, Any] | None = None, tags: Iterable[str] | None = None, alias: str | None = None, weight: float = 1) → Job

Schedule a oneshot Job.

Parameters:

timingTimingOnceUnion

Desired execution time.

handleCallable[…, 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.

weightfloat

Relative weight against other Jobs.

Returns:

Job

Instance of a scheduled Job.

weekly(timing: Weekday | list[scheduler.trigger.core.Weekday], handle: Callable[[...], 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[…, 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.
weight	Relative weight against other Jobs.