feat: optionally play notification+sound on completion (#5657)

dependency not installed by default, very opt in

Co-authored-by: Darragh Elliott <me@delliott.net>
Reviewed-on: #5657
Reviewed-by: tobiasd <tobiasd@fsfe.org>
Co-authored-by: delliott <delliott@fsfe.org>
Co-committed-by: delliott <delliott@fsfe.org>

build/fsfe_website_build/build.py

@@ -22,6 +22,7 @@ from .phase0.global_symlinks import global_symlinks
 from .phase0.prepare_early_subdirectories import prepare_early_subdirectories
 from .phase1.run import phase1_run
 from .phase2.run import phase2_run
+from .phase3.completion_notification import completion_notification
 from .phase3.serve_websites import serve_websites
 from .phase3.stage_to_target import stage_to_target
 
@@ -97,6 +98,15 @@ def _build_parser() -> argparse.ArgumentParser:
         nargs="+",
         type=str,
     )
+    parser.add_argument(
+        "--completion-notification",
+        help=dedent("""\
+        Send a notification a build finishes successfully.
+        Requires extra dependencies from the `notifications` dep group.
+        Easiest way to get them is `uv sync --all-groups`
+        """),
+        action="store_true",
+    )
     return parser
 
 
@@ -205,6 +215,8 @@ def _run_build(global_build_config: GlobalBuildConfig) -> None:
             stage_to_target(
                 global_build_config.working_target, global_build_config.targets, pool
             )
+    if global_build_config.completion_notification:
+        completion_notification()
 
     if global_build_config.serve:
         serve_websites(

build/fsfe_website_build/globals.py

@@ -7,4 +7,6 @@ from pathlib import Path
 
 from platformdirs import user_cache_dir
 
-CACHE_DIR = Path(user_cache_dir("fsfe-website-build", "fsfe"))
+APP_NAME = "fsfe-website-build"
+
+CACHE_DIR = Path(user_cache_dir(APP_NAME, "fsfe"))

build/fsfe_website_build/lib/build_config.py

@@ -26,6 +26,7 @@ class GlobalBuildConfig:
     stage: bool
     targets: list[str]
     working_target: Path
+    completion_notification: bool
 
     def __post_init__(self) -> None:
         """Validate build settings."""

build/fsfe_website_build/phase3/completion_notification.py

@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: Free Software Foundation Europe e.V. <https://fsfe.org>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Send notification on completion."""
+
+import asyncio
+import logging
+
+from fsfe_website_build.globals import APP_NAME
+
+logger = logging.getLogger(__name__)
+
+
+def completion_notification() -> None:
+    """Send a completion notification."""
+    try:
+        from desktop_notifier import DEFAULT_SOUND, DesktopNotifier  # noqa: PLC0415
+
+        notifier = DesktopNotifier(app_name=APP_NAME)
+        asyncio.run(
+            notifier.send(
+                title="Website Build Complete",
+                message="Current build finished successfully.",
+                sound=DEFAULT_SOUND,
+            )
+        )
+    except ImportError:
+        logger.warning("desktop-notifier is not available. Skipping playing sound.")