Обзор APScheduler: расписание задач Python показывает библиотеку для запуска функций по расписанию внутри процесса приложения. Документация проекта описывает четыре вида компонентов: планировщик, триггеры, хранилища задач и исполнители. Триггеры содержат логику расписания, исполнители занимаются запуском задач. Ниже рассматривается API ветки APScheduler 3.x: процесс, триггеры, пропуски и пересечения. Примеры этой ветки нужно сверять отдельно с API других основных версий.
Где работает планировщик
Планировщик APScheduler живёт внутри процесса Python-приложения. Документация проекта в разделе про BackgroundScheduler описывает планировщик, который работает в фоне через отдельный поток. Такой вариант подходит для веб-приложений: код приложения продолжает обслуживать запросы, а поток планировщика отсчитывает время и передаёт задачи исполнителям.
Для FastAPI, Django и других фреймворков это означает один общий процесс: приложение поднимает планировщик при старте и останавливает при завершении. Документация проекта отдельно отмечает, что остановка не прерывает уже запущенные задачи. Планировщик перестаёт назначать новые запуски, а текущая работа доходит до конца.
Отсюда практический вывод для выбора. Планировщик подходит, когда задачи должны выполняться в том же процессе, что и приложение, и когда допустимо, что при остановке процесса расписание тоже остановится. При закрытии процесса планировщик прекращает работу при любом хранилище. Постоянное хранилище сохраняет расписание для следующего старта, но не исполняет функции, пока приложение остановлено.
Установка идёт обычным пакетом из PyPI. Имя пакета — apscheduler, поэтому команда установки выглядит так:
pip install "APScheduler>=3,<4" SQLAlchemy
Документация проекта в FAQ указывает, что графический интерфейс библиотека сама не предоставляет. Наблюдать за работой приходится через логи приложения и события планировщика. Это важно для эксплуатации: отдельной панели управления расписанием у библиотеки нет, её нужно строить вокруг приложения.
Для распределённых систем есть ограничение из документации проекта: хранилища задач нельзя делить между планировщиками. Если несколько процессов приложения смотрят в одну таблицу задач, каждый из них считает расписание своим. Такой сценарий требует отдельного решения о том, какой процесс владеет расписанием.
Типы trigger
Триггеры содержат логику расписания. Документация проекта в разделе apscheduler.triggers.cron описывает cron-триггер: он срабатывает, когда текущее время совпадает со всеми заданными ограничениями, по принципу, похожему на UNIX cron. Документация apscheduler.triggers.interval описывает интервальный триггер, который отсчитывает промежутки между запусками.
Третий тип — date-триггер, запуск один раз в конкретный момент. Он удобен для отложенной задачи: напоминание, отложенная отправка, разовая синхронизация. Для повторяющихся задач используют interval и cron.
| Триггер | Когда срабатывает | Типичное применение |
|---|---|---|
date |
один раз в заданный момент | отложенная разовая задача |
interval |
через равные промежутки | периодический опрос, сводка |
cron |
при совпадении с ограничениями времени | запуск по календарю, в рабочие дни |
Отдельная деталь про interval из документации проекта: если дата старта лежит в прошлом, триггер не срабатывает много раз задним числом. Он вычисляет следующий запуск от текущего времени, опираясь на прошлую дату старта. Это снимает ожидание, что новый триггер «догонит» всю историю пропущенных моментов.
У cron-триггера часовой пояс по умолчанию берётся из планировщика. Задайте его явно в конфигурации, чтобы перенос окружения не менял вашу календарную привязку. В учебном примере ниже часовой пояс задан как UTC, чтобы ожидаемые старты читались однозначно.
Выбор между interval и cron определяется вопросом: важен интервал между запланированными моментами старта или привязка к календарному времени. Interval задаёт сетку моментов старта и не ждёт окончания предыдущего вызова. Cron описывает календарные ограничения. Длительность самой функции и пересечения проверяются отдельно.
Процесс и постоянное хранилище
Хранилище задач определяет, что произойдёт с расписанием при перезапуске приложения. Документация проекта различает память и постоянные хранилища. В памяти расписание живёт, пока живёт процесс. Постоянное хранилище сохраняет записи о задачах и позволяет восстановить расписание после старта.
Документация проекта в руководстве пользователя даёт жёсткое требование: если задачи ставятся в постоянное хранилище при инициализации приложения, нужно задать явный идентификатор задачи и использовать replace_existing=True. Без этого при каждом перезапуске приложения появляется новая копия задачи. Накопление копий может привести к повторному выполнению одной и той же работы.
Практический порядок настройки постоянного хранилища:
- Выбрать хранилище, которое переживает перезапуск процесса.
- При старте приложения открыть планировщик с этим хранилищем.
- Для каждой задачи задать стабильный
id. - Передавать
replace_existing=Trueпри постановке задачи. - Проверить, что после двух перезапусков число задач в хранилище не выросло.
Пятый шаг — простая проверка на ошибку из документации. Если после второго старта задач стало вдвое больше, идентификатор не задан или replace_existing не передан.
Память как хранилище удобна для быстрых экспериментов и для случаев, когда история запусков не нужна. После закрытия процесса память не сохраняет расписание, и при следующем старте задачи ставятся заново. В таком варианте расписание собирается кодом приложения при каждом запуске. Сохранённую историю просроченных моментов из памяти завершённого процесса восстановить нельзя.
Пропущенные запуски
Пропущенный запуск возникает, когда момент по расписанию прошёл, а планировщик не выполнил задачу. Причины бывают разные: процесс был недоступен, задача ещё выполнялась, ресурсы были заняты. Документация проекта описывает два параметра, которые определяют судьбу пропуска: misfire_grace_time и coalesce.
misfire_grace_time задаёт окно, в котором просроченный запуск ещё допустим. Если момент запуска прошёл, но укладывается в это окно, планировщик может поставить задачу на исполнение по своим правилам. Допустимость запуска и факт успешного завершения — разные вещи: попадание в окно означает право на попытку, а результат зависит от самой задачи.
coalesce управляет схлопыванием. Документация проекта объясняет: если схлопывание включено и планировщик видит один или несколько запусков в очереди, задача срабатывает один раз. Несколько накопившихся моментов превращаются в один запуск.
Учебный пример показывает разницу. Возьмём задачу daily_digest с интервалом 10 минут и часовым поясом UTC. Ожидаемые старты: 09:00, 09:10, 09:20, 09:30. Последний успешный старт — 09:00, процесс недоступен с 09:05 до 09:35, историческое расписание сохранено в хранилище. Ресурсы условно свободны при возврате в 09:35.
| Вариант | misfire_grace_time |
coalesce |
Что происходит с тремя моментами |
|---|---|---|---|
| A | 3600 секунд | false | три просроченных старта ещё допустимы, планировщик может поставить их на исполнение |
| B | 3600 секунд | true | пропуски схлопываются в один запуск |
| C | 60 секунд | false | каждый прошедший старт позже допуска, выдавать их за успешную работу нельзя |
Числа здесь учебные. Реальный планировщик в этом примере не поднимался, сообщения никому не отправлялись. Таблица показывает допустимые попытки по заданному расписанию. Успех каждой попытки нужно фиксировать отдельно.
Пересекающиеся задачи
Пересечение возникает, когда предыдущий запуск ещё выполняется, а наступает следующий момент по расписанию. Документация проекта описывает параметр max_instances, который ограничивает число одновременных экземпляров одной задачи. Значение 1 означает, что второй экземпляр не стартует, пока работает первый.
Учебная проба пересечения: работа длится 15 минут при интервале 10 минут и max_instances=1. Новые старты могут быть пропущены. Снимайте фактические старты, пропуски и завершения из событий планировщика. Иными словами, расписание говорит о намерении запустить задачу, а события говорят о том, что произошло.
Порядок разбора пересечения:
- Включить запись событий планировщика в лог приложения.
- Зафиксировать длительность задачи на реальных данных.
- Сравнить длительность с интервалом расписания.
- Задать
max_instancesи решить, допустимы ли пропуски. - Перечитать события после нескольких циклов и сверить с ожиданием.
Если длительность задачи превышает интервал, расписание перестаёт соответствовать фактическому ритму. Варианты решения: увеличить интервал, ускорить задачу, разрешить параллельные экземпляры осознанно. Каждый вариант меняет нагрузку, поэтому решение принимается после измерения длительности и проверки допустимой нагрузки.
События планировщика дают материал для проверки. По ним видно, сколько запусков было назначено, сколько стартовало и сколько завершилось. Сверка событий с ожидаемым расписанием — основной способ убедиться, что периодичность достигнута.
Полный учебный журнал
Ниже — учебный пример для APScheduler 3.x. Это бумажный fixture: реальный планировщик не поднимался, внешние сервисы не вызывались, сообщения не отправлялись. Значения служат входом для проверки логики расписания.
import os
from threading import Event
from apscheduler.schedulers.background import BackgroundScheduler
from apscheduler.jobstores.sqlalchemy import SQLAlchemyJobStore
JOB_ID = "daily_digest"
DB_URL = os.environ["APSCHEDULER_DB_URL"]
def daily_digest():
# Учебная функция без внешних отправок.
print("daily_digest: выполнена учебная попытка")
if __name__ == "__main__":
scheduler = BackgroundScheduler(
jobstores={"default": SQLAlchemyJobStore(url=DB_URL)}, timezone="UTC")
scheduler.start(paused=True)
try:
# Существующую запись оставляем с сохранённым next_run_time.
if scheduler.get_job(JOB_ID) is None:
scheduler.add_job(
daily_digest, "interval", minutes=10,
id=JOB_ID, replace_existing=True,
misfire_grace_time=3600, coalesce=False, max_instances=1,
)
scheduler.resume()
Event().wait() # Держим отдельный учебный процесс живым до остановки.
except (KeyboardInterrupt, SystemExit):
pass
finally:
scheduler.shutdown(wait=True)
Для локальной пробы задайте APSCHEDULER_DB_URL как sqlite:///jobs.sqlite и запустите файл отдельным процессом. Функция должна оставаться доступной для импорта при восстановлении задачи. Во фреймворке используйте его жизненный цикл вместо Event().wait(), и назначьте одного владельца расписания.
Разбор по строкам. JOB_ID задаёт стабильный идентификатор, который документация проекта требует для постоянного хранилища. DB_URL берётся из переменной окружения, чтобы строка подключения не попадала в код и логи. jobstores связывает планировщик с постоянным хранилищем. timezone="UTC" фиксирует часовой пояс. replace_existing=True защищает от накопления копий при перезапуске. misfire_grace_time=3600 и coalesce=False задают вариант A для уже сохранённой сетки моментов. Новый первый запуск кода не создаёт историю 09:00–09:30; таблица отдельно задаёт такой условный вход. max_instances=1 ограничивает параллельные экземпляры.
Что менять под себя: интервал, идентификатор задачи, часовой пояс и значения grace, coalesce, max_instances. Строку подключения передавайте через переменную окружения и исключите её из логов.
Журнал проверки для этого примера:
| Шаг | Что проверяем | Ожидание |
|---|---|---|
| 1 | число задач в хранилище после первого старта | одна запись с id="daily_digest" |
| 2 | число задач после второго старта | по-прежнему одна запись |
| 3 | события после простоя 09:05–09:35 | три просроченных момента в окне grace |
| 4 | события при длительности 15 минут | пропущенные старты видны в событиях |
| 5 | часовой пояс в записи задачи | UTC |
Третий шаг опирается на вариант A: grace 3600 секунд оставляет три момента допустимыми. Четвёртый шаг — проба пересечения. Пятый шаг подтверждает, что расписание не сместится при переносе сервера.
Контроль перезапуска
Перезапуск приложения — момент, когда проявляются ошибки настройки. Документация проекта называет главную: копии задач в постоянном хранилище. Проверка проста: посчитать задачи до перезапуска и после. Рост числа записей означает, что идентификатор или replace_existing настроены неверно.
Второй контроль — поведение при остановке. Документация проекта для фонового планировщика указывает, что остановка не прерывает текущие задачи. Планировщик перестаёт назначать новые запуски, а работающие задачи завершаются. При выключении приложения это даёт предсказуемое завершение вместо обрыва на середине.
Третий контроль — восстановление расписания. При постоянном хранилище оно читается при старте. Слепой повтор add_job с новым interval-триггером и replace_existing=True может заменить сохранённый следующий момент запуска. Для проверки пропусков нужно сохранить исходное расписание: пример ниже создаёт задачу только при её отсутствии. Если приложение намеренно меняет конфигурацию существующей задачи, это отдельная миграция.
Четвёртый контроль — часовой пояс. Он задаётся явно и проверяется в записи задачи. Смена сервера с другим локальным временем не должна менять моменты запуска.
Порядок контроля перезапуска:
- Записать число задач в хранилище.
- Перезапустить приложение.
- Сравнить число задач с записанным.
- Проверить, что часовой пояс в записях совпадает с заданным.
- Убедиться, что остановка не оборвала текущую задачу.
Эти пять шагов закрывают основные риски эксплуатации расписания. Они не требуют отдельной панели управления и выполняются по логам и записям хранилища.
Частые вопросы
Что такое APScheduler в Python?
Это библиотека для запуска функций по расписанию внутри процесса приложения. Документация проекта описывает четыре компонента: планировщик, триггеры, хранилища задач и исполнители. Триггеры содержат логику расписания, исполнители занимаются запуском. Библиотека ставится пакетом apscheduler из PyPI.
Как установить APScheduler?
Для примера ветки 3.x установите pip install "APScheduler>=3,<4" SQLAlchemy. SQLAlchemy нужна выбранному постоянному хранилищу. После установки зафиксируйте конкретные версии; пример не описывает API другой основной ветки.
Как использовать APScheduler с FastAPI или Django?
Планировщик поднимается при старте приложения и останавливается при завершении. Документация проекта описывает фоновый планировщик, который работает через отдельный поток. При остановке он не прерывает текущие задачи. Для постоянного хранилища задайте явный идентификатор задачи и replace_existing=True.
Чем cron-триггер отличается от interval?
Cron-триггер срабатывает при совпадении текущего времени с заданными ограничениями, по принципу UNIX cron. Interval-триггер задаёт равные промежутки между запланированными моментами старта. Cron привязывает задачу к календарному времени, interval задаёт сетку моментов старта и не ждёт завершения предыдущего вызова. По умолчанию cron-триггер использует часовой пояс планировщика; для воспроизводимости задайте его явно.
Что делать с пропущенными и пересекающимися запусками?
Для пропусков настраивают misfire_grace_time и coalesce. Окно grace определяет, какие просроченные моменты ещё допустимы, схлопывание сводит несколько моментов к одному запуску. Для пересечений задают max_instances. Фактические попытки, пропуски и завершения проверяют по событиям планировщика.
