feat: guild join requests

discord/__init__.py

@@ -47,6 +47,7 @@
 from .file import *
 from .flags import *
 from .guild import *
+from .guild_join_request import *
 from .http import *
 from .incidents import *
 from .integrations import *

discord/enums.py

@@ -88,6 +88,9 @@
     "SelectDefaultValueType",
     "ApplicationEventWebhookStatus",
     "InviteTargetUsersJobStatusCode",
+    "JoinRequestStatus",
+    "JoinRequestFormFieldType",
+    "JoinRequestAction",
 )
 
 
@@ -1212,6 +1215,31 @@ class InviteTargetUsersJobStatusCode(Enum):
     failed = 3
 
 
+class JoinRequestStatus(Enum):
+    """Represents the status of a guild join request application."""
+
+    STARTED = "STARTED"
+    SUBMITTED = "SUBMITTED"
+    APPROVED = "APPROVED"
+    REJECTED = "REJECTED"
+
+
+class JoinRequestFormFieldType(Enum):
+    """Represents the type of a guild join request form field."""
+
+    TERMS = "TERMS"
+    TEXT_INPUT = "TEXT_INPUT"
+    PARAGRAPH = "PARAGRAPH"
+    MULTIPLE_CHOICE = "MULTIPLE_CHOICE"
+
+
+class JoinRequestAction(Enum):
+    """Represents the action of a guild join request application."""
+
+    APPROVE = "APPROVED"
+    REJECT = "REJECTED"
+
+
 T = TypeVar("T")
 
 

discord/guild.py

@@ -56,6 +56,7 @@
     ChannelType,
     ContentFilter,
     EntitlementOwnerType,
+    JoinRequestStatus,
     NotificationLevel,
     NSFWLevel,
     OnboardingMode,
@@ -78,6 +79,7 @@
     AuditLogIterator,
     BanIterator,
     EntitlementIterator,
+    JoinRequestIterator,
     MemberIterator,
 )
 from .member import Member, VoiceState
@@ -111,6 +113,7 @@
         TextChannel,
         VoiceChannel,
     )
+    from .guild_join_request import JoinRequest
     from .onboarding import OnboardingPrompt
     from .permissions import Permissions
     from .state import ConnectionState
@@ -4719,3 +4722,87 @@ def get_sound(self, sound_id: int) -> SoundboardSound | None:
             The sound or ``None`` if not found.
         """
         return self._sounds.get(sound_id)
+
+    def join_requests(
+        self,
+        *,
+        status: JoinRequestStatus | None = None,
+        limit: int | None = 100,
+        before: SnowflakeTime | None = None,
+        after: SnowflakeTime | None = None,
+    ) -> JoinRequestIterator:
+        """Retrieves an :class:`.AsyncIterator` that enables receiving the guild's join requests.
+
+        This requires either the :attr:`~Permissions.kick_members` or :attr:`~Permissions.manage_guild`
+        permission. Apps with only :attr:`~Permissions.manage_guild` receive no join requests, but the
+        iterator's :attr:`~JoinRequestIterator.total` attribute is populated with the pending-request count
+        after its first request.
+
+        The :attr:`~JoinRequestIterator.total` attribute is only populated when `status` is set to
+        either ``None`` or :attr:`JoinRequestStatus.SUBMITTED`. It's always ``None`` otherwise.
+
+        Only have the request ID and want to take action? Consider using :meth:`JoinRequest.partial`.
+
+        .. versionadded:: 2.9
+
+        Parameters
+        ----------
+        status: Optional[:class:`JoinRequestStatus`]
+            The single status to which results are restricted. If ``None``,
+            fetches submitted join requests.
+
+            Defaults to :data:`None`.
+        limit: Optional[:class:`int`]
+            The number of join requests to retrieve.
+            If ``None``, retrieves every join request, which may be slow.
+
+            Defaults to ``100``.
+        before: :class:`.abc.Snowflake` | :class:`datetime.datetime` | None
+            Retrieves join requests before this date or object.
+            If a datetime is provided, it is recommended to use a UTC-aware datetime.
+            If the datetime is naive, it is assumed to be local time.
+
+            Defaults to :data:`None`.
+        after: :class:`.abc.Snowflake` | :class:`datetime.datetime` | None
+            Retrieve join requests after this date or object.
+            If a datetime is provided, it is recommended to use a UTC-aware datetime.
+            If the datetime is naive, it is assumed to be local time.
+
+            Defaults to :data:`None`.
+
+        Yields
+        ------
+        :class:`JoinRequest`
+            The join request.
+
+        Raises
+        ------
+        :exc:`HTTPException`
+            Retrieving the join requests failed.
+
+        Examples
+        --------
+
+        Usage ::
+
+            async for request in guild.join_requests(limit=250):
+                print(request.user, request.status)
+
+        Flattening into a list ::
+
+            requests = await guild.join_requests(limit=None).flatten()
+            # requests is now a list of JoinRequest...
+
+            # need the total number of submitted join requests? do this:
+            iterator = guild.join_requests(limit=None)
+            await iterator.next()
+            print(iterator.total)  # prints the total number of submitted join requests
+            requests = await iterator.flatten()
+        """
+        return JoinRequestIterator(
+            self,
+            status=status,
+            limit=limit,
+            before=before,
+            after=after,
+        )