Implement automatic AssignedCommitteeAction reminders

cogs/__init__.py

@@ -17,6 +17,7 @@
 from .command_error import CommandErrorCog
 from .committee_actions_tracking import (
     CommitteeActionsTrackingContextCommandsCog,
+    CommitteeActionsTrackingRemindersTaskCog,
     CommitteeActionsTrackingSlashCommandsCog,
 )
 from .delete_all import DeleteAllCommandsCog
@@ -55,6 +56,7 @@
     "ClearRemindersBacklogTaskCog",
     "CommandErrorCog",
     "CommitteeActionsTrackingContextCommandsCog",
+    "CommitteeActionsTrackingRemindersTaskCog",
     "CommitteeActionsTrackingSlashCommandsCog",
     "CommitteeHandoverCommandCog",
     "DeleteAllCommandsCog",
@@ -95,6 +97,7 @@ def setup(bot: "TeXBot") -> None:
         ClearRemindersBacklogTaskCog,
         CommandErrorCog,
         CommitteeActionsTrackingSlashCommandsCog,
+        CommitteeActionsTrackingRemindersTaskCog,
         CommitteeActionsTrackingContextCommandsCog,
         CommitteeHandoverCommandCog,
         DeleteAllCommandsCog,

cogs/committee_actions_tracking.py

@@ -3,12 +3,14 @@
 import logging
 import random
 from enum import Enum
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, overload, override
 
 import discord
+from discord.ext import tasks
 from django.core.exceptions import MultipleObjectsReturned, ObjectDoesNotExist, ValidationError
 from django.db.models import Q
 
+from config import settings
 from db.core.models import AssignedCommitteeAction, DiscordMember
 from exceptions import (
     CommitteeRoleDoesNotExistError,
@@ -19,21 +21,24 @@
     CommandChecks,
     TeXBotBaseCog,
 )
+from utils.error_capture_decorators import capture_guild_does_not_exist_error
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Iterable, Sequence
     from collections.abc import Set as AbstractSet
     from logging import Logger
     from typing import Final
 
     from utils import (
+        TeXBot,
         TeXBotApplicationContext,
         TeXBotAutocompleteContext,
     )
 
 __all__: "Sequence[str]" = (
     "CommitteeActionsTrackingBaseCog",
     "CommitteeActionsTrackingContextCommandsCog",
+    "CommitteeActionsTrackingRemindersTaskCog",
     "CommitteeActionsTrackingSlashCommandsCog",
 )
 
@@ -110,6 +115,135 @@ async def _create_action(
             ) from create_action_error
         return action
 
+    @overload
+    async def get_user_actions(
+        self, action_user: discord.Member | discord.User, status: str
+    ) -> list[AssignedCommitteeAction]: ...
+
+    @overload
+    async def get_user_actions(
+        self,
+        action_user: "Iterable[discord.Member]",
+        status: list[str],
+    ) -> dict[discord.Member, list[AssignedCommitteeAction]]: ...
+
+    async def get_user_actions(
+        self,
+        action_user: "discord.Member | discord.User | Iterable[discord.Member]",
+        status: str | list[str],
+    ) -> list[AssignedCommitteeAction] | dict[discord.Member, list[AssignedCommitteeAction]]:
+        """
+        Get the actions for a given user.
+
+        Takes in the user and returns a list of their actions.
+        """
+        if isinstance(action_user, (discord.User, discord.Member)):
+            user_actions: list[AssignedCommitteeAction]
+
+            if not status:
+                user_actions = [
+                    action
+                    async for action in await AssignedCommitteeAction.objects.afilter(
+                        (
+                            Q(status=Status.IN_PROGRESS.value)
+                            | Q(status=Status.BLOCKED.value)
+                            | Q(status=Status.NOT_STARTED.value)
+                        ),
+                        discord_id=int(action_user.id),
+                    )
+                ]
+            else:
+                user_actions = [
+                    action
+                    async for action in await AssignedCommitteeAction.objects.afilter(
+                        status=status,
+                        discord_id=int(action_user.id),
+                    )
+                ]
+
+            return user_actions
+
+        actions: list[AssignedCommitteeAction] = [
+            action async for action in AssignedCommitteeAction.objects.select_related().all()
+        ]
+
+        committee_actions: dict[discord.Member, list[AssignedCommitteeAction]] = {
+            committee: [
+                action
+                for action in actions
+                if str(action.discord_member) == DiscordMember.hash_discord_id(committee.id)  # type: ignore[has-type]
+                and action.status in status
+            ]
+            for committee in action_user
+        }
+
+        return {
+            committee: actions for committee, actions in committee_actions.items() if actions
+        }
+
+
+class CommitteeActionsTrackingRemindersTaskCog(CommitteeActionsTrackingBaseCog):
+    """Cog class that defines the committee-actions tracking reminders task functionality."""
+
+    @override
+    def __init__(self, bot: "TeXBot") -> None:
+        """Start all task managers when this cog is initialised."""
+        if settings["COMMITTEE_ACTIONS_REMINDERS"]:
+            _ = self.committee_actions_reminders_task.start()
+
+        super().__init__(bot)
+
+    @override
+    def cog_unload(self) -> None:
+        """
+        Unload-hook that ends all running tasks whenever the tasks cog is unloaded.
+
+        This may be run dynamically or when the bot closes.
+        """
+        self.committee_actions_reminders_task.cancel()
+
+    @tasks.loop(**settings["COMMITTEE_ACTIONS_REMINDERS_INTERVAL"])
+    @capture_guild_does_not_exist_error
+    async def committee_actions_reminders_task(self) -> None:
+        """
+        Definition of the background task that sends reminders of committee actions.
+
+        The task will run every interval specified in the settings and will send reminders
+        to all committee members who have actions that are either in progress or not started.
+        """
+        committee_general_channel: discord.TextChannel | None = discord.utils.get(
+            self.bot.main_guild.text_channels,
+            name="committee-general",  # TODO: Make this user-configurable  # noqa: FIX002
+        )
+        if not committee_general_channel:
+            logger.warning(
+                "Committee-general channel could not be found! "
+                "Actions reminders task will not run until next restart."
+            )
+            self.committee_actions_reminders_task.cancel()
+            return
+
+        committee_role: discord.Role = await self.bot.committee_role
+        committee_members: list[discord.Member] = committee_role.members
+        all_actions: dict[
+            discord.Member, list[AssignedCommitteeAction]
+        ] = await self.get_user_actions(
+            committee_members,
+            [Status.NOT_STARTED.value, Status.IN_PROGRESS.value, Status.BLOCKED.value],
+        )
+
+        all_actions_message: str = "\n".join(
+            [
+                f"\n{committee.mention}, Actions:"
+                f"\n{', \n'.join(str(action.description) + f' ({AssignedCommitteeAction.Status(action.status).label})' for action in actions)}"  # noqa: E501
+                for committee, actions in all_actions.items()
+            ],
+        )
+
+        await committee_general_channel.send(
+            content=all_actions_message,
+        )
+
 
 class CommitteeActionsTrackingSlashCommandsCog(CommitteeActionsTrackingBaseCog):
     """Cog class that defines the committee-actions tracking slash commands functionality."""
@@ -585,28 +719,10 @@ async def list_user_actions(
         else:
             action_member = ctx.user
 
-        user_actions: list[AssignedCommitteeAction]
-
-        if not status:
-            user_actions = [
-                action
-                async for action in await AssignedCommitteeAction.objects.afilter(
-                    (
-                        Q(status=Status.IN_PROGRESS.value)
-                        | Q(status=Status.BLOCKED.value)
-                        | Q(status=Status.NOT_STARTED.value)
-                    ),
-                    discord_id=int(action_member.id),
-                )
-            ]
-        else:
-            user_actions = [
-                action
-                async for action in await AssignedCommitteeAction.objects.afilter(
-                    status=status,
-                    discord_id=int(action_member.id),
-                )
-            ]
+        user_actions: list[AssignedCommitteeAction] = await self.get_user_actions(
+            action_user=action_member,
+            status=status,
+        )
 
         if not user_actions:
             await ctx.respond(
@@ -743,10 +859,6 @@ async def list_all_actions(
         """List all actions."""  # NOTE: this doesn't actually list *all* actions as it is possible for non-committee to be actioned.
         committee_role: discord.Role = await self.bot.committee_role
 
-        actions: list[AssignedCommitteeAction] = [
-            action async for action in AssignedCommitteeAction.objects.select_related().all()
-        ]
-
         desired_status: list[str] = (
             [status]
             if status
@@ -759,21 +871,11 @@ async def list_all_actions(
 
         committee_members: list[discord.Member] = committee_role.members
 
-        committee_actions: dict[discord.Member, list[AssignedCommitteeAction]] = {
-            committee: [
-                action
-                for action in actions
-                if str(action.discord_member) == DiscordMember.hash_discord_id(committee.id)  # type: ignore[has-type]
-                and action.status in desired_status
-            ]
-            for committee in committee_members
-        }
-
-        filtered_committee_actions = {
-            committee: actions for committee, actions in committee_actions.items() if actions
-        }
+        committee_actions: dict[
+            discord.Member, list[AssignedCommitteeAction]
+        ] = await self.get_user_actions(action_user=committee_members, status=desired_status)
 
-        if not filtered_committee_actions:
+        if not committee_actions:
             await ctx.respond(content="No one has any actions that match the request!")
             logger.debug("No actions found with the status filter: %s", status)
             return
@@ -782,7 +884,7 @@ async def list_all_actions(
             [
                 f"\n{committee.mention if ping else committee}, Actions:"
                 f"\n{', \n'.join(str(action.description) + f' ({AssignedCommitteeAction.Status(action.status).label})' for action in actions)}"  # noqa: E501
-                for committee, actions in filtered_committee_actions.items()
+                for committee, actions in committee_actions.items()
             ],
         )
 

config.py

@@ -724,6 +724,62 @@ def _setup_auto_add_committee_to_threads(cls) -> None:
             raw_auto_add_committee_to_threads in TRUE_VALUES
         )
 
+    @classmethod
+    def _setup_committee_actions_reminders(cls) -> None:
+        raw_committee_actions_reminders: str = str(
+            os.getenv("COMMITTEE_ACTIONS_REMINDERS", "True"),
+        ).lower()
+
+        if raw_committee_actions_reminders not in TRUE_VALUES | FALSE_VALUES:
+            INVALID_COMMITTEE_ACTIONS_REMINDERS_MESSAGE: Final[str] = (
+                "COMMITTEE_ACTIONS_REMINDERS must be a boolean value."
+            )
+            raise ImproperlyConfiguredError(INVALID_COMMITTEE_ACTIONS_REMINDERS_MESSAGE)
+
+        cls._settings["COMMITTEE_ACTIONS_REMINDERS"] = (
+            raw_committee_actions_reminders in TRUE_VALUES
+        )
+
+    @classmethod
+    def _setup_committee_actions_reminders_interval(cls) -> None:
+        if "COMMITTEE_ACTIONS_REMINDERS" not in cls._settings:
+            INVALID_SETUP_ORDER_MESSAGE: Final[str] = (
+                "Invalid setup order: COMMITTEE_ACTIONS_REMINDERS must be set up "
+                "before COMMITTEE_ACTIONS_REMINDERS_INTERVAL can be set up."
+            )
+            raise RuntimeError(INVALID_SETUP_ORDER_MESSAGE)
+
+        raw_committee_actions_reminders_interval: re.Match[str] | None = re.fullmatch(
+            r"\A(?:(?P<seconds>(?:\d*\.)?\d+)s)?(?:(?P<minutes>(?:\d*\.)?\d+)m)?(?:(?P<hours>(?:\d*\.)?\d+)h)?\Z",
+            str(os.getenv("COMMITTEE_ACTIONS_REMINDERS_INTERVAL", "24h")),
+        )
+
+        raw_timedelta_details_committee_actions_reminders_interval: Mapping[str, float] = {
+            "hours": 24,
+        }
+
+        if cls._settings["COMMITTEE_ACTIONS_REMINDERS"]:
+            if not raw_committee_actions_reminders_interval:
+                INVALID_COMMITTEE_ACTIONS_REMINDERS_INTERVAL_MESSAGE: Final[str] = (
+                    "COMMITTEE_ACTIONS_REMINDERS_INTERVAL must contain the interval "
+                    "in any combination of seconds, minutes or hours."
+                )
+                raise ImproperlyConfiguredError(
+                    INVALID_COMMITTEE_ACTIONS_REMINDERS_INTERVAL_MESSAGE,
+                )
+
+            raw_timedelta_details_committee_actions_reminders_interval = {
+                key: float(value)
+                for key, value in (
+                    raw_committee_actions_reminders_interval.groupdict().items()
+                )
+                if value
+            }
+
+        cls._settings["COMMITTEE_ACTIONS_REMINDERS_INTERVAL"] = (
+            raw_timedelta_details_committee_actions_reminders_interval
+        )
+
     @classmethod
     def _setup_env_variables(cls) -> None:
         """
@@ -765,6 +821,8 @@ def _setup_env_variables(cls) -> None:
             cls._setup_moderation_document_url()
             cls._setup_strike_performed_manually_warning_location()
             cls._setup_auto_add_committee_to_threads()
+            cls._setup_committee_actions_reminders()
+            cls._setup_committee_actions_reminders_interval()
         except ImproperlyConfiguredError as improper_config_error:
             webhook_config_logger.error(improper_config_error.message)  # noqa: TRY400
             raise improper_config_error from improper_config_error