refactor: Continue dynamic moderation refactoring timeout arguments

.vscode/settings.json

@@ -11,7 +11,7 @@
       "source.organizeImports.ruff": "explicit"
     }
   },
-  "python.languageServer": "Pylance",
+  "python.languageServer": "None",
   "python.analysis.typeCheckingMode": "strict",
   "python.analysis.autoFormatStrings": true,
   "python.analysis.completeFunctionParens": true,

tux/cogs/moderation/__init__.py

@@ -604,3 +604,184 @@ async def is_jailed(self, guild_id: int, user_id: int) -> bool:
             active_restriction_type=CaseType.JAIL,
             inactive_restriction_type=CaseType.UNJAIL,
         )
+
+    # ------------------------------------------------------------------
+    # Unified mixed-argument executor (dynamic moderation system)
+    # ------------------------------------------------------------------
+    async def execute_mixed_mod_action(
+        self,
+        ctx: commands.Context[Tux],
+        config: "ModerationCommandConfig",  # quoted to avoid circular import at runtime
+        user: discord.Member | discord.User,
+        mixed_args: str,
+    ) -> None:
+        """Parse *mixed_args* according to *config* and execute the moderation flow.
+
+        This serves as the single entry-point for all dynamically generated
+        moderation commands.  It handles:
+        1. Mixed-argument parsing (positional + flags).
+        2. Validation based on *config* (duration required?, purge range?, etc.).
+        3. Permission / sanity checks via *check_conditions*.
+        4. Building the *actions* list and delegating to :py:meth:`execute_mod_action`.
+        """
+
+        from tux.utils.mixed_args import parse_mixed_arguments  # local import to avoid heavy top-level deps
+        from tux.utils.constants import CONST  # default reason constant
+
+        assert ctx.guild, "This command can only be used in guild context."  # noqa: S101
+
+        parsed = parse_mixed_arguments(mixed_args or "")
+        ok, validated = self._validate_args(config, parsed)
+        if not ok:
+            await ctx.send(validated["error"], ephemeral=True)  # type: ignore[index]
+            return
+
+        duration = validated["duration"]  # type: ignore[assignment]
+        purge = validated["purge"]         # type: ignore[assignment]
+        reason = (validated.get("reason") or CONST.DEFAULT_REASON)  # type: ignore[assignment]
+        silent = validated["silent"]       # type: ignore[assignment]
+
+        # ------------------------------------------------------------------
+        # Permission / sanity checks
+        # ------------------------------------------------------------------
+        if not await self.check_conditions(ctx, user, ctx.author, config.name):
+            return
+
+        # ------------------------------------------------------------------
+        # Build Discord action coroutine(s)
+        # ------------------------------------------------------------------
+        # Prepare arg bundle for the lambda / callable
+        arg_bundle: dict[str, Any] = {
+            "duration": duration,
+            "purge": purge,
+            "silent": silent,
+        }
+
+        coroutine_or_none = config.discord_action(ctx.guild, user, reason, arg_bundle)
+        actions: list[tuple[Any, type[Any]]] = []
+        if coroutine_or_none is not None:
+            actions.append((coroutine_or_none, type(None)))
+
+        # ------------------------------------------------------------------
+        # Delegate to existing helper that handles DM, case creation, etc.
+        # ------------------------------------------------------------------
+        await self.execute_mod_action(
+            ctx=ctx,
+            case_type=config.case_type,
+            user=user,
+            reason=reason,
+            silent=silent,
+            dm_action=config.dm_action,
+            actions=actions,
+            duration=duration,
+        )
+
+    # ------------------------------------------------------------------
+    # Validation helper for dynamic moderation commands
+    # ------------------------------------------------------------------
+    def _validate_args(self, config: "ModerationCommandConfig", parsed: dict[str, Any]) -> tuple[bool, dict[str, Any]]:
+        """Validate *parsed* arguments against *config* rules.
+
+        Returns (is_valid, validated_dict).  On failure sends the error message
+        via the ctx stored in validated_dict["ctx"] and returns False.
+        """
+        validated: dict[str, Any] = {}
+
+        # Duration
+        duration = parsed.get("duration")
+        if config.supports_duration:
+            if not duration:
+                return False, {"error": "Duration required (e.g. `14d`)."}
+            from tux.utils.functions import parse_time_string
+            try:
+                parse_time_string(duration)  # ensure valid
+            except Exception:
+                return False, {"error": "Invalid duration format."}
+            validated["duration"] = duration
+        else:
+            validated["duration"] = None
+
+        # Purge
+        purge_raw = parsed.get("purge")
+        if config.supports_purge:
+            try:
+                purge_val = int(purge_raw or 0)
+            except ValueError:
+                return False, {"error": "Purge must be an integer 0-7."}
+            if not 0 <= purge_val <= 7:
+                return False, {"error": "Purge must be between 0 and 7."}
+            validated["purge"] = purge_val
+        else:
+            validated["purge"] = 0
+
+        validated["reason"] = parsed.get("reason")
+        validated["silent"] = bool(parsed.get("silent", False))
+        return True, validated
+
+    # ------------------------------------------------------------------
+    # New flag-based dynamic executor (replacing mixed-args approach)
+    # ------------------------------------------------------------------
+    async def execute_flag_mod_action(
+        self,
+        ctx: commands.Context[Tux],
+        config: "ModerationCommandConfig",
+        user: discord.Member | discord.User,
+        flags: Any,
+        reason: str,
+    ) -> None:
+        """Execute moderation flow based on *flags* parsed by FlagConverter.
+
+        This is the preferred pathway for dynamically generated moderation
+        commands that rely on discord.py's native FlagConverter parsing.
+        """
+
+        from tux.utils.constants import CONST
+
+        assert ctx.guild, "Command must run in a guild context."  # noqa: S101
+
+        duration = getattr(flags, "duration", None) if flags is not None else None
+        purge = getattr(flags, "purge", 0) if flags is not None else 0
+        silent = getattr(flags, "silent", False) if flags is not None else False
+
+        # Validation based on config
+        if config.supports_duration and not duration:
+            await ctx.send("Duration required (e.g. 14d).", ephemeral=True)
+            return
+        if not config.supports_duration:
+            duration = None
+
+        if not config.supports_purge:
+            purge = 0
+        else:
+            if not isinstance(purge, int) or not 0 <= purge <= 7:
+                await ctx.send("Purge must be between 0 and 7.", ephemeral=True)
+                return
+
+        reason_final = reason or CONST.DEFAULT_REASON
+
+        # Permission / sanity checks
+        if not await self.check_conditions(ctx, user, ctx.author, config.name):
+            return
+
+        # Build arg bundle for discord_action
+        arg_bundle: dict[str, Any] = {
+            "duration": duration,
+            "purge": purge,
+            "silent": silent,
+        }
+
+        coroutine_or_none = config.discord_action(ctx.guild, user, reason_final, arg_bundle)
+        actions: list[tuple[Any, type[Any]]] = []
+        if coroutine_or_none is not None:
+            actions.append((coroutine_or_none, type(None)))
+
+        await self.execute_mod_action(
+            ctx=ctx,
+            case_type=config.case_type,
+            user=user,
+            reason=reason_final,
+            silent=silent,
+            dm_action=config.dm_action,
+            actions=actions,
+            duration=duration,
+        )

tux/cogs/moderation/action_mixin.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import discord
+from discord.ext import commands
+from prisma.enums import CaseType
+
+from tux.cogs.moderation import ModerationCogBase
+from tux.utils.constants import CONST
+from tux.utils.transformers import MemberOrUser
+
+__all__ = ["ModerationActionMixin"]
+
+
+class ModerationActionMixin(ModerationCogBase):
+    """Shared execution helper for moderation actions.
+
+    This mixin builds the *actions* list and delegates to
+    :py:meth:`ModerationCogBase.execute_mod_action` so concrete commands only
+    need to supply metadata and the Discord API coroutine.
+    """
+
+    async def _run_action(  # noqa: WPS211  (many params is ok for clarity)
+        self,
+        ctx: commands.Context,  # noqa: D401
+        *,
+        member: MemberOrUser,
+        reason: str,
+        duration: str | None,
+        purge: int,
+        silent: bool,
+        case_type: CaseType,
+        dm_verb: str,
+        discord_action: Callable[[], Awaitable[Any]] | None = None,
+    ) -> None:
+        """Validate and execute the moderation workflow."""
+
+        assert ctx.guild is not None, "Guild-only command"  # noqa: S101
+
+        # Permission / sanity checks
+        if not await self.check_conditions(ctx, member, ctx.author, case_type.name.lower()):
+            return
+
+        if purge and not (0 <= purge <= 7):
+            await ctx.send("Purge must be between 0 and 7 days.", ephemeral=True)
+            return
+
+        final_reason = reason or CONST.DEFAULT_REASON
+
+        actions: list[tuple[Awaitable[Any], type[Any]]] = []
+        if discord_action is not None:
+            actions.append((discord_action(), type(None)))
+
+        await self.execute_mod_action(
+            ctx=ctx,
+            case_type=case_type,
+            user=member,
+            reason=final_reason,
+            silent=silent,
+            dm_action=dm_verb,
+            actions=actions,
+            duration=duration,
+        )
+
+
+# ---------------------------------------------------------------------------
+# No-op setup so the cog loader skips this util module
+# ---------------------------------------------------------------------------
+
+
+async def setup(bot):  # type: ignore[unused-argument]
+    """Utility module – nothing to load."""
+    return