Документация Python неофициальный перевод
Содержание страницы

sched – Планировщик событийsched – Event scheduler

Исходный код: Lib/sched.py

Модуль sched определяет класс, который реализует планировщик событий общего назначения:

class sched.scheduler(timefunc=time.monotonic, delayfunc=time.sleep)

Класс scheduler определяет общий интерфейс для планирования событий. Ему нужны две функции для взаимодействия с «внешним миром»: timefunc должна быть вызываемой без аргументов и возвращать число («время» в любых единицах). Функция delayfunc должна быть вызываемой с одним аргументом, совместимым с выходными данными timefunc, и должна задерживать выполнение на это количество единиц времени. delayfunc также будет вызвана с аргументом 0 после выполнения каждого события, чтобы предоставить другим потокам возможность выполниться в многопоточных приложениях.

Изменено в версии 3.3: параметры timefunc и delayfunc стали необязательными.

Изменено в версии 3.3: класс scheduler можно безопасно использовать в многопоточных средах.

Пример:

>>> import sched, time
>>> s = sched.scheduler(time.time, time.sleep)
>>> def print_time(a='default'):
...     print("From print_time", time.time(), a)
...
>>> def print_some_times():
...     print(time.time())
...     s.enter(10, 1, print_time)
...     s.enter(5, 2, print_time, argument=('positional',))
...     # несмотря на более высокий приоритет, 'keyword' выполняется после 'positional', так как enter() является относительным
...     s.enter(5, 1, print_time, kwargs={'a': 'keyword'})
...     s.enterabs(1_650_000_000, 10, print_time, argument=("first enterabs",))
...     s.enterabs(1_650_000_000, 5, print_time, argument=("second enterabs",))
...     s.run()
...     print(time.time())
...
>>> print_some_times()
1652342830.3640375
From print_time 1652342830.3642538 second enterabs
From print_time 1652342830.3643398 first enterabs
From print_time 1652342835.3694863 positional
From print_time 1652342835.3696074 keyword
From print_time 1652342840.369612 default
1652342840.3697174

Объекты планировщикаScheduler Objects

Экземпляры scheduler имеют следующие методы и атрибуты:

scheduler.enterabs(time, priority, action, argument=(), kwargs={})

Планирует новое событие. Аргумент time должен быть числового типа, совместимого с возвращаемым значением функции timefunc, переданной конструктору. События, запланированные на одно и то же время, будут выполняться в порядке их приоритета. Меньшее число означает более высокий приоритет.

Выполнение события означает вызов action(*argument, **kwargs). argument – это последовательность позиционных аргументов для action. kwargs – это словарь именованных аргументов для action.

Возвращаемое значение – это событие, которое может быть использовано для последующей отмены события (см. cancel()).

Изменено в версии 3.3: параметр argument стал необязательным.

Изменено в версии 3.3: добавлен параметр kwargs.

scheduler.enter(delay, priority, action, argument=(), kwargs={})

Планирует событие через delay единиц времени. За исключением относительного времени, остальные аргументы, эффект и возвращаемое значение такие же, как и для enterabs().

Изменено в версии 3.3: параметр argument стал необязательным.

Изменено в версии 3.3: добавлен параметр kwargs.

scheduler.cancel(event)

Удаляет событие из очереди. Если event не является событием, находящимся в очереди, этот метод возбуждает исключение ValueError.

scheduler.empty()

Возвращает True, если очередь событий пуста.

scheduler.run(blocking=True)

Запускает все запланированные события. Этот метод будет ожидать (используя функцию delayfunc, переданную конструктору) следующего события, затем выполнять его и так далее, пока не останется запланированных событий.

Если blocking равен False, немедленно выполняет все события в очереди, значение времени которых меньше или равно текущему значению timefunc (если такие есть), и возвращает разницу между текущим значением timefunc и временем следующего запланированного события в очереди событий планировщика. Если очередь пуста, возвращает None.

Либо action, либо delayfunc могут возбуждать исключения. В любом случае планировщик сохранит согласованное состояние и пробросит исключение. Если исключение возбуждено action, событие не будет повторно предприниматься при последующих вызовах run().

Если выполнение последовательности событий занимает больше времени, чем доступно до следующего события, планировщик просто отстанет от графика. Ни одно событие не будет отброшено; вызывающий код отвечает за отмену событий, которые больше не актуальны.

Изменено в версии 3.3: добавлен параметр blocking.

scheduler.queue

Атрибут только для чтения, возвращающий список предстоящих событий в порядке их выполнения. Каждое событие представлено в виде именованного кортежа со следующими полями: time, priority, action, argument, kwargs.