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,36 @@ def fetch_members(
 
         return MemberIterator(self, limit=limit, after=after)
 
+    async def search_members(self, query: str, *, limit: int = 1000) -> list[Member]:
+        """Search 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, up to 1000.
+
+        Returns
+        -------
+        List[:class:`Member`]
+            The list of members that have matched the query.
+
+        Raises
+        ------
+        HTTPException
+            Getting the members failed.
+        """
+
+        data = await self._state.http.search_members(self.id, query, limit)
+        return [Member(data=m, guild=self, state=self._state) for m in data]
+
     async def fetch_member(self, member_id: int, /) -> Member:
         """|coro|
 

discord/http.py

@@ -1636,6 +1636,20 @@ 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,
+        query: str,
+        limit: int,
+    ) -> 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]: