Декоратор задачи¶

Декоратор @app.task является ключевой точкой регистрации задач в QTasks. В момент применения декоратора функция задачи преобразуется в объект управления, который хранит как метаданные задачи, так и методы для её вызова и исполнения.

При регистрации задачи формируются два связанных представления:

(A)syncTask — пользовательский интерфейс задачи, через который выполняются вызовы add_task и управление выполнением.
TaskExecSchema — dataclass, используемый внутри app.tasks и app.worker.tasks для передачи и хранения исполняемой информации о задаче, включая саму функцию.

Оба объекта содержат согласованный набор данных, но используются на разных уровнях системы.

Общая модель¶

Для дальнейшего описания будем считать, что task_func — это функция, обёрнутая декоратором @app.task().

@app.task()
async def task_func(...):
    ...

После регистрации task_func перестаёт быть обычной функцией и становится экземпляром (A)syncTask.

Параметры задачи¶

Декоратор @app.task принимает следующие параметры конфигурации задачи:

Параметр	Тип	Описание
`name`	`str, optional`	Имя задачи. По умолчанию: `func.__name__`.
`priority`	`int, optional`	Приоритет задачи. По умолчанию: `config.task_default_priority`.
`echo`	`bool, optional`	Добавляет AsyncTask первым параметром. По умолчанию: `False`.
`max_time`	`float, optional`	Максимальное время выполнения задачи в секундах. По умолчанию: `None`.
`retry`	`int, optional`	Количество попыток повторного выполнения задачи. По умолчанию: `None`.
`retry_on_exc`	`List[Type[Exception]], optional`	Исключения, при которых задача будет повторно выполнена. По умолчанию: `None`.
`decode`	`Callable, optional`	Декодер результата задачи. По умолчанию: `None`.
`tags`	`List[str], optional`	Теги задачи. По умолчанию: `None`.
`description`	`str, optional`	Описание задачи. По умолчанию: `None`.
`generate_handler`	`Callable, optional`	Генератор обработчика. По умолчанию: `None`.
`executor`	`Type["BaseTaskExecutor"], optional`	Класс `BaseTaskExecutor`. По умолчанию: `AsyncTaskExecutor`.
`middlewares_before`	`List[Type["TaskMiddleware"]], optional`	Мидлвари, которые будут выполнены до задачи. По умолчанию: `Пустой массив`.
`middlewares_after`	`List[Type["TaskMiddleware"]], optional`	Мидлвари, которые будут выполнены после задачи. По умолчанию: `Пустой массив`.
`**kwargs`	-	Дополнительные параметры задачи. Передаётся как extra в `(A)syncTask` и `TaskExecSchema`.

(A)syncTask¶

(A)syncTask является объектом-обёрткой над задачей и предоставляет API для её вызова и предварительной конфигурации.

Предварительная сборка задачи¶

cls = task_func(*args, **kwargs, priority=0, timeout=None)

В этом случае:

аргументы и параметры сохраняются заранее;
создаётся экземпляр (A)syncTaskCls (наследник BaseTaskCls);
объект является dataclass и содержит все данные, необходимые для постановки задачи в очередь.

Такой объект можно передавать, модифицировать или вызывать позже.

Вызов задачи¶

Задачу можно запустить двумя эквивалентными способами:

task_func.add_task(*args, **kwargs, priority=0, timeout=None)

или

cls.add_task()

В обоих случаях вызывается app.add_task:

либо через app, переданный в момент создания (A)syncTask;
либо через qtasks._state.app_main, если задача была вызвана вне явного контекста приложения.

Это позволяет использовать задачи как внутри приложения, так и в изолированных модулях.

Ожидание результата (timeout)¶

Параметр timeout: float | None определяет поведение вызова задачи.

Если timeout is None — add_task немедленно возвращает объект Task со статусом new.
Если timeout указан — вызов блокируется до получения результата и возвращает объект (A)syncResult.

Ожидание завершается при достижении одного из конечных статусов, заданных в конфигурации приложения:

app.config.result_statuses_end = [
    TaskStatusEnum.SUCCESS.value,
    TaskStatusEnum.ERROR.value,
    TaskStatusEnum.CANCEL.value,
]

TaskExecSchema¶

TaskExecSchema — это dataclass, который используется для передачи задачи между компонентами QTasks.

Он хранит:

имя задачи;
приоритет;
параметры выполнения;
ссылку на функцию задачи;
дополнительные метаданные.

Экземпляры TaskExecSchema формируются при регистрации задачи и доступны в:

app.tasks;
app.worker.tasks.

Worker использует именно TaskExecSchema для фактического исполнения задачи.

Разделение ответственности¶

Такое разделение позволяет:

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

Итог¶

Декоратор @app.task:

регистрирует функцию как задачу QTasks;
создаёт объект (A)syncTask для управления вызовами;
формирует TaskExecSchema для внутреннего исполнения;
обеспечивает гибкий контроль параметров запуска и ожидания результата.

Страница оформлена как холст и может использоваться как базовый материал для разделов о задачах, контексте и выполнении.