feat: Update AutoMod implementation (#1809)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: BobDotCom <71356958+BobDotCom@users.noreply.github.com>
Co-authored-by: plun1331 <49261529+plun1331@users.noreply.github.com>
Co-authored-by: Lala Sabathil <lala@pycord.dev>

CHANGELOG.md

@@ -10,7 +10,11 @@ possible (see our [Version Guarantees] for more info).
 
 These changes are available on the `master` branch, but have not yet been released.
 
-_No changes yet_
+### Added
+
+- Added new AutoMod trigger metadata properties `regex_patterns`, `allow_list`, and
+  `mention_total_limit`; and added the `mention_spam` trigger type.
+  ([#1809](https://github.com/Pycord-Development/pycord/pull/1809))
 
 ## [2.3.2] - 2022-12-03
 

discord/automod.py

@@ -39,7 +39,12 @@
 from .mixins import Hashable
 from .object import Object
 
-__all__ = ("AutoModRule",)
+__all__ = (
+    "AutoModRule",
+    "AutoModAction",
+    "AutoModActionMetadata",
+    "AutoModTriggerMetadata",
+)
 
 if TYPE_CHECKING:
     from .abc import Snowflake
@@ -167,45 +172,95 @@ def __repr__(self) -> str:
 
 
 class AutoModTriggerMetadata:
-    """Represents a rule's trigger metadata.
-
-    Depending on the trigger type, different attributes will be used.
+    r"""Represents a rule's trigger metadata, defining additional data used to determine when a rule triggers.
+
+    Depending on the trigger type, different metadata attributes will be used:
+
+    +-----------------------------+--------------------------------------------------------------------------------+
+    |   Attribute                 |   Trigger Types                                                                |
+    +=============================+================================================================================+
+    | :attr:`keyword_filter`      | :attr:`AutoModTriggerType.keyword`                                             |
+    +-----------------------------+--------------------------------------------------------------------------------+
+    | :attr:`regex_patterns`      | :attr:`AutoModTriggerType.keyword`                                             |
+    +-----------------------------+--------------------------------------------------------------------------------+
+    | :attr:`presets`             | :attr:`AutoModTriggerType.keyword_preset`                                      |
+    +-----------------------------+--------------------------------------------------------------------------------+
+    | :attr:`allow_list`          | :attr:`AutoModTriggerType.keyword`\, :attr:`AutoModTriggerType.keyword_preset` |
+    +-----------------------------+--------------------------------------------------------------------------------+
+    | :attr:`mention_total_limit` | :attr:`AutoModTriggerType.mention_spam`                                        |
+    +-----------------------------+--------------------------------------------------------------------------------+
+
+    Each attribute has limits that may change based on the trigger type.
+    See `here <https://discord.com/developers/docs/resources/auto-moderation#auto-moderation-rule-object-trigger-metadata-field-limits>`_
+    for information on attribute limits.
 
     .. versionadded:: 2.0
 
     Attributes
     ----------
     keyword_filter: List[:class:`str`]
-        A list of substrings to filter. Only for triggers of type :attr:`AutoModTriggerType.keyword`.
+        A list of substrings to filter.
+
+    regex_patterns: List[:class:`str`]
+        A list of regex patterns to filter using Rust-flavored regex, which is not
+        fully compatible with regex syntax supported by the builtin `re` module.
+
+        .. versionadded:: 2.4
+
     presets: List[:class:`AutoModKeywordPresetType`]
-        A list of keyword presets to filter. Only for triggers of type :attr:`AutoModTriggerType.keyword_preset`.
-    """
+        A list of preset keyword sets to filter.
 
-    # maybe add a table of action types and attributes?
-    # wording for presets could change
+    allow_list: List[:class:`str`]
+        A list of substrings to allow, overriding keyword and regex matches.
+
+        .. versionadded:: 2.4
+
+    mention_total_limit: :class:`int`
+        The total number of unique role and user mentions allowed.
+
+        .. versionadded:: 2.4
+    """
 
     __slots__ = (
         "keyword_filter",
+        "regex_patterns",
         "presets",
+        "allow_list",
+        "mention_total_limit",
     )
 
     def __init__(
         self,
         keyword_filter: list[str] = MISSING,
+        regex_patterns: list[str] = MISSING,
         presets: list[AutoModKeywordPresetType] = MISSING,
+        allow_list: list[str] = MISSING,
+        mention_total_limit: int = MISSING,
     ):
         self.keyword_filter = keyword_filter
+        self.regex_patterns = regex_patterns
         self.presets = presets
+        self.allow_list = allow_list
+        self.mention_total_limit = mention_total_limit
 
     def to_dict(self) -> dict:
         data = {}
 
         if self.keyword_filter is not MISSING:
             data["keyword_filter"] = self.keyword_filter
 
+        if self.regex_patterns is not MISSING:
+            data["regex_patterns"] = self.regex_patterns
+
         if self.presets is not MISSING:
             data["presets"] = [wordset.value for wordset in self.presets]
 
+        if self.allow_list is not MISSING:
+            data["allow_list"] = self.allow_list
+
+        if self.mention_total_limit is not MISSING:
+            data["mention_total_limit"] = self.mention_total_limit
+
         return data
 
     @classmethod
@@ -215,17 +270,29 @@ def from_dict(cls, data: AutoModTriggerMetadataPayload):
         if (keyword_filter := data.get("keyword_filter")) is not None:
             kwargs["keyword_filter"] = keyword_filter
 
+        if (regex_patterns := data.get("regex_patterns")) is not None:
+            kwargs["regex_patterns"] = regex_patterns
+
         if (presets := data.get("presets")) is not None:
             kwargs["presets"] = [
                 try_enum(AutoModKeywordPresetType, wordset) for wordset in presets
             ]
 
+        if (allow_list := data.get("allow_list")) is not None:
+            kwargs["allow_list"] = allow_list
+
+        if (mention_total_limit := data.get("mention_total_limit")) is not None:
+            kwargs["mention_total_limit"] = mention_total_limit
+
         return cls(**kwargs)
 
     def __repr__(self) -> str:
         repr_attrs = (
             "keyword_filter",
+            "regex_patterns",
             "presets",
+            "allow_list",
+            "mention_total_limit",
         )
         inner = []
 

discord/enums.py

@@ -880,6 +880,7 @@ class AutoModTriggerType(Enum):
     harmful_link = 2
     spam = 3
     keyword_preset = 4
+    mention_spam = 5
 
 
 class AutoModEventType(Enum):

discord/raw_models.py

@@ -28,7 +28,7 @@
 import datetime
 from typing import TYPE_CHECKING
 
-from .automod import AutoModAction
+from .automod import AutoModAction, AutoModTriggerType
 from .enums import ChannelType, try_enum
 
 if TYPE_CHECKING:
@@ -409,6 +409,10 @@ class AutoModActionExecutionEvent:
         The action that was executed.
     rule_id: :class:`int`
         The ID of the rule that the action belongs to.
+    rule_trigger_type: :class:`AutoModTriggerType`
+        The category of trigger the rule belongs to.
+
+        .. versionadded:: 2.4
     guild_id: :class:`int`
         The ID of the guild that the action was executed in.
     guild: Optional[:class:`Guild`]
@@ -443,6 +447,7 @@ class AutoModActionExecutionEvent:
     __slots__ = (
         "action",
         "rule_id",
+        "rule_trigger_type",
         "guild_id",
         "guild",
         "user_id",
@@ -461,6 +466,9 @@ class AutoModActionExecutionEvent:
     def __init__(self, state: ConnectionState, data: AutoModActionExecution) -> None:
         self.action: AutoModAction = AutoModAction.from_dict(data["action"])
         self.rule_id: int = int(data["rule_id"])
+        self.rule_trigger_type: AutoModTriggerType = try_enum(
+            AutoModTriggerType, int(data["rule_trigger_type"])
+        )
         self.guild_id: int = int(data["guild_id"])
         self.guild: Guild | None = state._get_guild(self.guild_id)
         self.user_id: int = int(data["user_id"])

discord/types/automod.py

@@ -27,7 +27,7 @@
 from .._typed_dict import NotRequired, TypedDict
 from .snowflake import Snowflake
 
-AutoModTriggerType = Literal[1, 2, 3, 4]
+AutoModTriggerType = Literal[1, 2, 3, 4, 5]
 
 AutoModEventType = Literal[1]
 
@@ -38,7 +38,10 @@
 
 class AutoModTriggerMetadata(TypedDict, total=False):
     keyword_filter: list[str]
+    regex_patterns: list[str]
     presets: list[AutoModKeywordPresetType]
+    allow_list: list[str]
+    mention_total_limit: int
 
 
 class AutoModActionMetadata(TypedDict, total=False):

docs/api/enums.rst

@@ -1867,3 +1867,97 @@ of :class:`enum.Enum`.
     .. attribute:: guild_only
 
         Represents a scheduled event that is only available to members inside the guild.
+
+.. class:: AutoModTriggerType
+
+    Represents an AutoMod trigger type.
+
+    .. versionadded:: 2.0
+
+    .. attribute:: keyword
+
+        Represents a keyword rule trigger, which are customizable by a guild.
+
+        Possible attributes for :class:`AutoModTriggerMetadata`:
+
+        - :attr:`~AutoModTriggerMetadata.keyword_filter`
+        - :attr:`~AutoModTriggerMetadata.regex_patterns`
+        - :attr:`~AutoModTriggerMetadata.allow_list`
+
+    .. attribute:: keyword_preset
+
+        Represents a preset keyword rule trigger.
+
+        Possible attributes for :class:`AutoModTriggerMetadata`:
+
+        - :attr:`~AutoModTriggerMetadata.presets`
+        - :attr:`~AutoModTriggerMetadata.allow_list`
+
+    .. attribute:: spam
+
+        Represents the spam rule trigger.
+
+        There are no possible attributes for :class:`AutoModTriggerMetadata`.
+
+    .. attribute:: mention_spam
+
+        Represents a mention spam keyword rule trigger.
+
+        Possible attributes for :class:`AutoModTriggerMetadata`:
+
+        - :attr:`~AutoModTriggerMetadata.mention_total_limit`
+
+        .. versionadded:: 2.4
+
+    .. attribute:: harmful_link
+
+        Represents a harmful link rule trigger.
+
+        .. deprecated:: 2.4
+            Removed by Discord and merged into :attr:`spam`.
+
+.. class:: AutoModEventType
+
+    Represents an AutoMod event type.
+
+    .. versionadded:: 2.0
+
+    .. attribute:: message_send
+
+        Represents a message send AutoMod event.
+
+.. class:: AutoModActionType
+
+    Represents the type of action AutoMod is performing.
+
+    .. versionadded:: 2.0
+
+    .. attribute:: block_message
+
+        Represents a block message action.
+
+    .. attribute:: send_alert_message
+
+        Represents a send alert message action.
+
+    .. attribute:: timeout
+
+        Represents a timeout action.
+
+.. class:: AutoModKeywordPresetType
+
+    Represents an AutoMod keyword preset type.
+
+    .. versionadded:: 2.0
+
+    .. attribute:: profanity
+
+        Represents the profanity keyword preset rule.
+
+    .. attribute:: sexual_content
+
+        Represents the sexual content keyword preset rule.
+
+    .. attribute:: slurs
+
+        Represents the slurs keyword preset rule.

docs/api/models.rst

@@ -146,11 +146,29 @@ Guild
 .. autoclass:: Template()
     :members:
 
+AutoMod
+~~~~~~~
+
 .. attributetable:: AutoModRule
 
 .. autoclass:: AutoModRule()
     :members:
 
+.. attributetable:: AutoModAction
+
+.. autoclass:: AutoModAction()
+    :members:
+
+.. attributetable:: AutoModActionMetadata
+
+.. autoclass:: AutoModActionMetadata()
+    :members:
+
+.. attributetable:: AutoModTriggerMetadata
+
+.. autoclass:: AutoModTriggerMetadata()
+    :members:
+
 Invites
 ~~~~~~~