Перейти к содержанию

Timer

Существует встроенный дополнительный компонент (A)syncTimer, предназначенный для периодического запуска задач QTasks. Таймер интегрируется напрямую с QueueTasks через параметр app и работает с задачами как с расписанием, а не с единичными вызовами.

(A)syncTimer позволяет выносить логику планирования из бизнес-кода и использовать декларативные триггеры для запуска задач по времени.

Принцип работы

Timer является отдельным компонентом, который:

  • регистрирует периодические задачи;
  • использует внешние триггеры (например, cron);
  • инициирует выполнение задач через стандартный механизм QTasks;
  • не изменяет логику самих задач.

Задача, запускаемая через Timer, остаётся обычной задачей QTasks и может быть вызвана вручную, через API или другими компонентами.

Пример использования

from qtasks.timers import AsyncTimer
from apscheduler.triggers.cron import CronTrigger

timer = AsyncTimer(app=app)

timer.add_task(
    "daily_report",
    trigger=CronTrigger(hour=23, minute=59),
)

@app.task(name="daily_report")
async def daily_report():
    stats = await db.get_today_stats()
    await mailer.send(
        "owner@shop.com",
        "Ежедневный отчёт",
        stats.format(),
    )

В данном примере задача daily_report будет автоматически запускаться каждый день в 23:59.

Под капотом

Работа Timer состоит из следующих этапов:

  1. Timer инициализируется с экземпляром QueueTasks.

  2. При вызове add_task:

  3. сохраняется имя задачи;

  4. регистрируется триггер запуска;
  5. формируется связка «триггер → задача».

  6. При срабатывании триггера:

  7. Timer создаёт обычный вызов задачи через add_task;

  8. задача попадает в Broker и обрабатывается Worker как стандартная.

Таким образом, Timer не выполняет задачу напрямую и не обходит очередь.

Триггеры

(A)syncTimer не ограничивает тип триггера. На практике чаще всего используются триггеры из apscheduler, например:

  • CronTrigger — cron-расписание;
  • IntervalTrigger — запуск с фиксированным интервалом;
  • DateTrigger — однократный запуск в заданное время.

Это позволяет гибко управлять расписанием без изменения кода задач.

Особенности

  • Timer является дополнительным компонентом и не обязателен для работы QTasks.
  • Таймер работает с задачами по имени, а не по ссылке на функцию.
  • Задачи, зарегистрированные в Timer, полностью совместимы с retry, priority, middlewares и плагинами.
  • Timer не хранит состояние выполнения задач — этим занимается стандартное хранилище QTasks.

Итог

(A)syncTimer предоставляет:

  • декларативное планирование задач;
  • интеграцию с внешними системами расписаний;
  • единый механизм запуска задач через очередь;
  • чистое разделение бизнес-логики и логики планирования.

Страница оформлена как холст и может быть использована как шаблон для документации других дополнительных компонентов QTasks.