# SPDX-FileCopyrightText: 2026 Dennis Fink # # SPDX-License-Identifier: BSD-3-Clause """Integrate Huey tasks with Flask application contexts.""" from __future__ import annotations from collections.abc import Callable from functools import update_wrapper, wraps from typing import Any, ParamSpec, TypeVar from urllib.parse import urlsplit, urlunsplit from flask import Flask from huey import Huey as BaseHuey from huey.api import TaskWrapper from .json_serializer import JSONSerializer P = ParamSpec("P") R = TypeVar("R") class _LazyTask: """Stable public task handle which follows the extension's current backend. Huey creates task classes and registers them when its decorator is applied. Keep that backend-specific TaskWrapper private, so imported task handles can be used across Flask app factories without referring to an obsolete queue. """ def __init__( self, extension: Huey, func: Callable[..., Any], args: tuple[Any, ...], kwargs: dict[str, Any], *, periodic: bool, ) -> None: self._extension = extension self._func = func self._args = args self._kwargs = kwargs self._periodic = periodic self._registered: TaskWrapper | None = None update_wrapper(self, func) def register(self) -> None: """Bind the original function to the latest initialized backend.""" backend = self._extension.huey decorator = backend.periodic_task if self._periodic else backend.task self._registered = decorator(*self._args, **self._kwargs)( self._extension._in_app_context(self._func) ) def _current(self) -> TaskWrapper: if self._registered is None: raise RuntimeError( "Huey has not been initialized. Call huey.init_app(app) first." ) return self._registered def __call__(self, *args: Any, **kwargs: Any) -> Any: """Enqueue a task using the active backend.""" return self._current()(*args, **kwargs) def __getattr__(self, name: str) -> Any: """Delegate Huey task operations (call_local, schedule, s, etc.).""" return getattr(self._current(), name) class Huey: """Provide Flask integration for a Huey instance. The extension initializes a Huey backend from the Flask configuration and wraps tasks so that they execute within an application context. """ def __init__(self, app: Flask | None = None) -> None: """Initialize the Huey extension. :param app: Flask application to initialize immediately, if provided. """ self.app: Flask | None = None self._huey: BaseHuey | None = None self._tasks: list[_LazyTask] = [] if app is not None: self.init_app(app) def init_app(self, app: Flask) -> None: """Initialize Huey for a Flask application. The backend and its storage options are derived from ``HUEY_URL`` and the resulting extension is registered with the application. :param app: Flask application to initialize. :raises RuntimeError: If the configured Huey backend URL is invalid or uses an unsupported scheme. """ config: dict[str, Any] = { "name": app.import_name, "results": True, "store_none": False, "utc": True, "immediate": app.config.get("TESTING", False), **app.config.get("HUEY", {}), } # An arbitrary serializer supplied via HUEY would silently restore # pickle deserialization of broker-controlled bytes. Fail closed. if "serializer" in config: raise RuntimeError( "HUEY.serializer cannot be overridden; JSON is required." ) config["serializer"] = JSONSerializer( compression=config.pop("compression", False), use_zlib=config.pop("use_zlib", False), ) url = app.config.get("HUEY_URL", config.pop("url", "memory://")) huey_class, storage_kwargs = self.backend_from_url(url) self.app = app self._huey = huey_class(**config, **storage_kwargs) # Import order is immaterial: tasks declared before initialization are # registered now, and previously imported handles follow this backend. for task in self._tasks: task.register() app.extensions["huey"] = self @property def huey(self) -> BaseHuey: """Return the initialized Huey instance. :raises RuntimeError: If the extension has not been initialized. """ if self._huey is None: raise RuntimeError( "Huey has not been initialized. " "Call huey.init_app(app) before using tasks." ) return self._huey def _in_app_context(self, func: Callable[P, R]) -> Callable[P, R]: """Return a task wrapper that executes with the configured Flask app.""" @wraps(func) def wrapped(*args: P.args, **kwargs: P.kwargs) -> R: if self.app is None: raise RuntimeError("Flask app is not available.") with self.app.app_context(): return func(*args, **kwargs) return wrapped def _decorate_task( self, func: Callable[P, R], task_args: tuple[Any, ...], task_kwargs: dict[str, Any], *, periodic: bool, ) -> _LazyTask: handle = _LazyTask(self, func, task_args, task_kwargs, periodic=periodic) self._tasks.append(handle) if self._huey is not None: handle.register() return handle def task( self, *task_args: Any, **task_kwargs: Any ) -> Callable[[Callable[P, R]], _LazyTask]: """Declare a task even before :meth:`init_app` has run.""" def decorator(func: Callable[P, R]) -> _LazyTask: return self._decorate_task(func, task_args, task_kwargs, periodic=False) return decorator def periodic_task( self, *task_args: Any, **task_kwargs: Any ) -> Callable[[Callable[P, R]], _LazyTask]: """Declare a periodic task against the current or next backend.""" def decorator(func: Callable[P, R]) -> _LazyTask: return self._decorate_task(func, task_args, task_kwargs, periodic=True) return decorator def __getattr__(self, name: str) -> Any: """Forward an unknown attribute to the underlying Huey instance. :param name: Name of the attribute to retrieve. :return: Attribute from the initialized Huey instance. :raises RuntimeError: If the extension has not been initialized. """ return getattr(self.huey, name) @staticmethod def backend_from_url(url: str) -> tuple[type[BaseHuey], dict[str, Any]]: """Determine the Huey backend and storage options from a URL. :param url: Huey backend URL. :return: Huey backend class and keyword arguments for its storage backend. :raises RuntimeError: If the URL is malformed for the selected backend or uses an unsupported scheme. """ parsed = urlsplit(url) scheme = parsed.scheme.lower() base_scheme, separator, flavour = scheme.partition("+") if base_scheme in {"redis", "rediss"}: from huey import ( PriorityRedisExpireHuey, PriorityRedisHuey, RedisExpireHuey, RedisHuey, ) backends = { "": RedisHuey, "priority": PriorityRedisHuey, "expire": RedisExpireHuey, "priority+expire": PriorityRedisExpireHuey, } if flavour not in backends or (separator and not flavour): raise RuntimeError(f"Unsupported HUEY_URL scheme: {scheme!r}") fixed_url = urlunsplit(parsed._replace(scheme=base_scheme)) return backends[flavour], {"url": fixed_url} if scheme == "sqlite": from huey import SqliteHuey prefix = "sqlite:///" if not url.startswith(prefix): raise RuntimeError( "SQLite Huey URLs must look like sqlite:///var/huey.db" ) filename = url.removeprefix(prefix) if not filename: raise RuntimeError("SQLite Huey URL must include a database path.") return SqliteHuey, {"filename": filename} if scheme == "file": from huey import FileHuey prefix = "file:///" if not url.startswith(prefix): raise RuntimeError( "File Huey URLs must look like file:///var/huey-queue" ) path = url.removeprefix(prefix) if not path: raise RuntimeError("File Huey URL must include a directory path.") return FileHuey, {"path": path} if scheme in {"postgres", "postgresql"}: from huey import PostgresHuey return PostgresHuey, {"dsn": url} if scheme == "memory": from huey import MemoryHuey return MemoryHuey, {} if scheme == "blackhole": from huey import BlackHoleHuey return BlackHoleHuey, {} raise RuntimeError(f"Unsupported HUEY_URL scheme: {scheme!r}")