diff options
| author | Dennis Fink | 2026-11-14 18:44:23 +0100 |
|---|---|---|
| committer | Dennis Fink | 2026-11-14 18:44:23 +0100 |
| commit | 968e1b4e4a6fbd5a15037cdb11a3f9dee5108570 (patch) | |
| tree | 0096a0125c4d94a047e5bd24288e1f3f4a58ada5 /webmentions_ssg/tasks/extension.py | |
| parent | 2366d455c7d1ae16c84e0bcbffb94ed762c16832 (diff) | |
| download | webmentions-ssg-968e1b4e4a6fbd5a15037cdb11a3f9dee5108570.tar.gz webmentions-ssg-968e1b4e4a6fbd5a15037cdb11a3f9dee5108570.zip | |
docs(core): standardize reST docstrings
Expand function and method documentation with consistent reST parameter,
return, and exception fields while clarifying behavior where additional
context is useful.
Normalize test and migration docstrings to the same documentation
conventions.
Diffstat (limited to 'webmentions_ssg/tasks/extension.py')
| -rw-r--r-- | webmentions_ssg/tasks/extension.py | 74 |
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() |
