# SPDX-FileCopyrightText: 2026 Dennis Fink # # SPDX-License-Identifier: BSD-3-Clause """Integrate Huey tasks with Flask application contexts.""" from collections.abc import Callable from functools import 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 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 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) app.extensions["huey"] = self @property def huey(self) -> BaseHuey: """Return the initialized Huey instance. :return: Configured Huey backend 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 importing 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 task( self, *task_args: Any, **task_kwargs: Any ) -> Callable[[Callable[P, object]], TaskWrapper]: """Return a Huey task decorator with Flask application context.""" def decorator(func: Callable[P, R]) -> TaskWrapper: return self.huey.task(*task_args, **task_kwargs)(self._in_app_context(func)) return decorator def periodic_task( self, *task_args: Any, **task_kwargs: Any ) -> Callable[[Callable[P, object]], TaskWrapper]: """Return a periodic Huey decorator with Flask application context.""" def decorator(func: Callable[P, R]) -> TaskWrapper: return self.huey.periodic_task(*task_args, **task_kwargs)( self._in_app_context(func) ) 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}")