feat: implement Guild.search_members

CHANGELOG.md

@@ -18,6 +18,8 @@ These changes are available on the `master` branch, but have not yet been releas
   ([#2390](https://github.com/Pycord-Development/pycord/pull/2390))
 - Added `bridge_option` decorator. Required for `bridge.Bot` in 2.7.
   ([#2417](https://github.com/Pycord-Development/pycord/pull/2417))
+- Added `Guild.search_members`.
+  ([#2418](https://github.com/Pycord-Development/pycord/pull/2418))
 
 ### Fixed
 

discord/guild.py

@@ -2027,6 +2027,49 @@ def fetch_members(
 
         return MemberIterator(self, limit=limit, after=after)
 
+    def search_members(self, query: str, *, limit: int | None = 1000) -> MemberIterator:
+        """Retrieves an :class:`.AsyncIterator` that enables searching for guild members whose usernames or nicknames start with the query string. Unlike :meth:`fetch_members`, this does not require :meth:`Intents.members`.
+
+        .. note::
+
+            This method is an API call. For general usage, consider filtering :attr:`members` instead.
+
+        .. versionadded:: 2.6
+
+        Parameters
+        ----------
+        query: :class:`str`
+            Searches for usernames and nicknames that start with this string, case-insensitive.
+        limit: Optional[:class:`int`]
+            The maximum number of members to retrieve. Defaults to 1000.
+            Pass ``None`` to fetch all members matching the query. Note that this is potentially slow.
+
+        Yields
+        ------
+        :class:`.Member`
+            The member with the member data parsed.
+
+        Raises
+        ------
+        HTTPException
+            Getting the members failed.
+
+        Examples
+        --------
+
+        Usage ::
+
+            async for member in guild.search_members(query="Bob"):
+                print(member.name)
+
+        Flattening into a list ::
+
+            members = await guild.search_members(query="Lala").flatten()
+            # members is now a list of Member...
+        """
+
+        return MemberIterator(self, limit=limit, query=query)
+
     async def fetch_member(self, member_id: int, /) -> Member:
         """|coro|
 

discord/http.py

@@ -1636,6 +1636,17 @@ def get_members(
         r = Route("GET", "/guilds/{guild_id}/members", guild_id=guild_id)
         return self.request(r, params=params)
 
+    def search_members(
+        self, guild_id: Snowflake, limit: int, query: str
+    ) -> Response[list[member.MemberWithUser]]:
+        params: dict[str, Any] = {
+            "query": query,
+            "limit": limit,
+        }
+
+        r = Route("GET", "/guilds/{guild_id}/members/search", guild_id=guild_id)
+        return self.request(r, params=params)
+
     def get_member(
         self, guild_id: Snowflake, member_id: Snowflake
     ) -> Response[member.MemberWithUser]:

discord/iterators.py

@@ -646,16 +646,19 @@ async def _retrieve_guilds_after_strategy(self, retrieve):
 
 
 class MemberIterator(_AsyncIterator["Member"]):
-    def __init__(self, guild, limit=1000, after=None):
+    def __init__(self, guild, limit=1000, after=None, query=None):
         if isinstance(after, datetime.datetime):
             after = Object(id=time_snowflake(after, high=True))
 
         self.guild = guild
         self.limit = limit
         self.after = after or OLDEST_OBJECT
+        self.query = query
 
         self.state = self.guild._state
-        self.get_members = self.state.http.get_members
+        self.get_members = (
+            self.state.http.search_members if query else self.state.http.get_members
+        )
         self.members = asyncio.Queue()
 
     async def next(self) -> Member:
@@ -679,16 +682,17 @@ def _get_retrieve(self):
     async def fill_members(self):
         if not self._get_retrieve():
             return
-        after = self.after.id if self.after else None
-        data = await self.get_members(self.guild.id, self.retrieve, after)
+        param = self.query or (self.after.id if self.after else None)
+        data = await self.get_members(self.guild.id, self.retrieve, param)
         if not data:
             # no data, terminate
             return
 
         if len(data) < 1000:
             self.limit = 0  # terminate loop
 
-        self.after = Object(id=int(data[-1]["user"]["id"]))
+        if not self.query:
+            self.after = Object(id=int(data[-1]["user"]["id"]))
 
         for element in reversed(data):
             await self.members.put(self.create_member(element))