aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/tasks/extension.py
diff options
context:
space:
mode:
Diffstat (limited to 'webmentions_ssg/tasks/extension.py')
-rw-r--r--webmentions_ssg/tasks/extension.py74
1 files changed, 57 insertions, 17 deletions
diff --git a/webmentions_ssg/tasks/extension.py b/webmentions_ssg/tasks/extension.py
index b77a140..58e0036 100644
--- a/webmentions_ssg/tasks/extension.py
+++ b/webmentions_ssg/tasks/extension.py
@@ -19,7 +19,12 @@ from .json_serializer import JSONSerializer
def _redis_backend(parsed: SplitResult) -> tuple[type[BaseHuey], dict[str, Any]]:
- """Select a Redis Huey flavour while retaining the underlying URL scheme."""
+ """Select a Redis Huey flavour while retaining the underlying URL scheme.
+
+ :param parsed: Parsed Redis backend URL, including any flavour suffix.
+ :returns: Huey class and constructor options for the requested Redis flavour.
+ :raises RuntimeError: If the Redis backend flavour is unsupported.
+ """
from huey import (
PriorityRedisExpireHuey,
PriorityRedisHuey,
@@ -43,7 +48,13 @@ def _redis_backend(parsed: SplitResult) -> tuple[type[BaseHuey], dict[str, Any]]
def _path_backend(url: str, scheme: str) -> tuple[type[BaseHuey], dict[str, Any]]:
- """Extract a relative or absolute SQLite/file storage path."""
+ """Extract a relative or absolute SQLite/file storage path.
+
+ :param url: Backend URL containing the storage filename or path.
+ :param scheme: Selected file or SQLite backend scheme.
+ :returns: Huey class and constructor options for the file-backed queue.
+ :raises RuntimeError: If the storage URL is malformed or omits the path.
+ """
from huey import FileHuey, SqliteHuey
if scheme == "sqlite":
@@ -101,7 +112,11 @@ class _LazyTask:
update_wrapper(self, func)
def register(self) -> None:
- """Bind the original function to the latest initialized backend."""
+ """Bind the original function to the latest initialized backend.
+
+ Register the task decorator again so its stable handle uses the currently
+ initialized Huey instance.
+ """
backend = self._extension.huey
decorator = backend.periodic_task if self._periodic else backend.task
self._registered = decorator(*self._args, **self._kwargs)(
@@ -116,11 +131,20 @@ class _LazyTask:
return self._registered
def __call__(self, *args: Any, **kwargs: Any) -> Any:
- """Enqueue a task using the active backend."""
+ """Enqueue a task using the active backend.
+
+ :param args: Positional arguments passed to the queued task.
+ :param kwargs: Keyword arguments passed to the queued task.
+ :returns: Result of enqueueing the task on the current backend.
+ """
return self._current()(*args, **kwargs)
def __getattr__(self, name: str) -> Any:
- """Delegate Huey task operations (call_local, schedule, s, etc.)."""
+ """Delegate Huey task operations (call_local, schedule, s, etc.).
+
+ :param name: Huey task attribute to delegate.
+ :returns: Requested attribute of the currently bound Huey task.
+ """
return getattr(self._current(), name)
@@ -150,8 +174,8 @@ class Huey:
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.
+ :raises RuntimeError: If the configured Huey backend URL is invalid or uses an
+ unsupported scheme.
"""
config: dict[str, Any] = {
"name": app.import_name,
@@ -190,6 +214,7 @@ class Huey:
def huey(self) -> BaseHuey:
"""Return the initialized Huey instance.
+ :returns: Active, initialized Huey backend.
:raises RuntimeError: If the extension has not been initialized.
"""
if self._huey is None:
@@ -200,7 +225,12 @@ class Huey:
return self._huey
def _in_app_context[**P, R](self, func: Callable[P, R]) -> Callable[P, R]:
- """Return a task wrapper that executes with the configured Flask app."""
+ """Return a task wrapper that executes with the configured Flask app.
+
+ :param func: Task function to wrap in a Flask application context.
+ :returns: Task wrapper that enters the configured Flask application context.
+ :raises RuntimeError: If no Flask application has been registered.
+ """
@wraps(func)
def wrapped(*args: P.args, **kwargs: P.kwargs) -> R:
@@ -228,7 +258,12 @@ class Huey:
def task[**P, R](
self, *task_args: Any, **task_kwargs: Any
) -> Callable[[Callable[P, R]], _LazyTask]:
- """Declare a task even before :meth:`init_app` has run."""
+ """Declare a task even before :meth:`init_app` has run.
+
+ :param task_args: Positional arguments for the Huey task decorator.
+ :param task_kwargs: Keyword options for the Huey task decorator.
+ :returns: Decorator that registers and returns a lazily bound task.
+ """
def decorator(func: Callable[P, R]) -> _LazyTask:
return self._decorate_task(func, task_args, task_kwargs, periodic=False)
@@ -238,7 +273,12 @@ class Huey:
def periodic_task[**P, R](
self, *task_args: Any, **task_kwargs: Any
) -> Callable[[Callable[P, R]], _LazyTask]:
- """Declare a periodic task against the current or next backend."""
+ """Declare a periodic task against the current or next backend.
+
+ :param task_args: Positional arguments for the Huey periodic-task decorator.
+ :param task_kwargs: Keyword options for the Huey periodic-task decorator.
+ :returns: Decorator that registers and returns a lazily bound periodic task.
+ """
def decorator(func: Callable[P, R]) -> _LazyTask:
return self._decorate_task(func, task_args, task_kwargs, periodic=True)
@@ -249,7 +289,7 @@ class Huey:
"""Forward an unknown attribute to the underlying Huey instance.
:param name: Name of the attribute to retrieve.
- :return: Attribute from the initialized Huey instance.
+ :returns: Attribute from the initialized Huey instance.
:raises RuntimeError: If the extension has not been initialized.
"""
return getattr(self.huey, name)
@@ -258,12 +298,12 @@ class Huey:
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. SQLite and file paths use SQLAlchemy's
- slash convention: three slashes for relative paths and four for
- absolute paths (not RFC 8089 file-URI semantics).
- :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.
+ :param url: Huey backend URL. SQLite and file paths use SQLAlchemy's slash
+ convention: three slashes for relative paths and four for absolute
+ paths (not RFC 8089 file-URI semantics).
+ :returns: 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()