From 0a3f680e7f1847935c2d1f2ce94bf1f309583912 Mon Sep 17 00:00:00 2001
From: Slipstream <me@slipstreamm.dev>
Date: Wed, 11 Jun 2025 18:24:09 -0600
Subject: [PATCH] Add AllowedMentions helpers and update docs (#73)

---
 README.md              |  3 ++-
 disagreement/models.py | 29 +++++++++++++++++++++++------
 docs/introduction.md   |  6 +++++-
 docs/mentions.md       |  7 ++++++-
 4 files changed, 36 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 0039a77..7768439 100644
--- a/README.md
+++ b/README.md
@@ -118,9 +118,10 @@ session parameter supported by ``aiohttp``.
 Specify default mention behaviour for all outgoing messages when constructing the client:
 
 ```python
+from disagreement.models import AllowedMentions
 client = disagreement.Client(
     token=token,
-    allowed_mentions={"parse": [], "replied_user": False},
+    allowed_mentions=AllowedMentions.none().to_dict(),
 )
 ```
 
diff --git a/disagreement/models.py b/disagreement/models.py
index f10731b..3d4040d 100644
--- a/disagreement/models.py
+++ b/disagreement/models.py
@@ -624,14 +624,31 @@ class File:
         self.data = data
 
 
-class AllowedMentions:
+class AllowedMentions:
     """Represents allowed mentions for a message or interaction response."""
 
-    def __init__(self, data: Dict[str, Any]):
-        self.parse: List[str] = data.get("parse", [])
-        self.roles: List[str] = data.get("roles", [])
-        self.users: List[str] = data.get("users", [])
-        self.replied_user: bool = data.get("replied_user", False)
+    def __init__(self, data: Dict[str, Any]):
+        self.parse: List[str] = data.get("parse", [])
+        self.roles: List[str] = data.get("roles", [])
+        self.users: List[str] = data.get("users", [])
+        self.replied_user: bool = data.get("replied_user", False)
+
+    @classmethod
+    def all(cls) -> "AllowedMentions":
+        """Return an instance allowing all mention types."""
+
+        return cls(
+            {
+                "parse": ["users", "roles", "everyone"],
+                "replied_user": True,
+            }
+        )
+
+    @classmethod
+    def none(cls) -> "AllowedMentions":
+        """Return an instance disallowing all mentions."""
+
+        return cls({"parse": [], "replied_user": False})
 
     def to_dict(self) -> Dict[str, Any]:
         payload: Dict[str, Any] = {"parse": self.parse}
diff --git a/docs/introduction.md b/docs/introduction.md
index 1578553..17a0f40 100644
--- a/docs/introduction.md
+++ b/docs/introduction.md
@@ -118,15 +118,19 @@ session parameter supported by ``aiohttp``.
 Specify default mention behaviour for all outgoing messages when constructing the client:
 
 ```python
+from disagreement.models import AllowedMentions
 client = disagreement.Client(
     token=token,
-    allowed_mentions={"parse": [], "replied_user": False},
+    allowed_mentions=AllowedMentions.none().to_dict(),
 )
 ```
 
 This dictionary is used whenever ``send_message`` is called without an explicit
 ``allowed_mentions`` argument.
 
+The :class:`AllowedMentions` class offers ``none()`` and ``all()`` helpers for
+quickly generating these configurations.
+
 ### Defining Subcommands with `AppCommandGroup`
 
 ```python
diff --git a/docs/mentions.md b/docs/mentions.md
index 2a604cf..e3db3f5 100644
--- a/docs/mentions.md
+++ b/docs/mentions.md
@@ -8,15 +8,20 @@ Use the ``allowed_mentions`` parameter of :class:`disagreement.Client` to set a
 default for all messages:
 
 ```python
+from disagreement.models import AllowedMentions
 client = disagreement.Client(
     token="YOUR_TOKEN",
-    allowed_mentions={"parse": [], "replied_user": False},
+    allowed_mentions=AllowedMentions.none().to_dict(),
 )
 ```
 
 When ``Client.send_message`` is called without an explicit ``allowed_mentions``
 argument this value will be used.
 
+``AllowedMentions`` also provides the convenience methods
+``AllowedMentions.none()`` and ``AllowedMentions.all()`` to quickly create
+common configurations.
+
 ## Next Steps
 
 - [Commands](commands.md)