From 36dd36e3f36b97a6a81ab534d270c557d1bd31e1 Mon Sep 17 00:00:00 2001 From: Sacul Date: Sat, 16 Aug 2025 16:46:42 +0800 Subject: [PATCH 1/5] Add `fetch_members_named` method to `Guild --- discord/guild.py | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/discord/guild.py b/discord/guild.py index 6e2a9e626ed9..6183d4dc928a 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -2462,6 +2462,40 @@ async def active_threads(self) -> List[Thread]: return threads + async def fetch_members_named(self, name: str, *, limit: Optional[int] = 1) -> List[Member]: + """A List[:class:`.Member`] members whose username or nickname starts + with the provided `name`. + + .. versionadded:: 2.6 + + + Parameters + ---------- + name: :class:`str` + The string to match a username and nickname against. + limit: Optional[:class:`int`] + The maximum number of members to return. Max of 1000, defaults to 1. + + Raises + ------ + HTTPException + Getting the members failed. + ValueError + Maximum number of members to return of 1000 was exceeded. + + Returns + ------ + List[:class:`.Member`] + A list of members. + """ + + if limit > 1000: + raise ValueError('Maximum number of members to return was exceeded') + + state = self._state + data = await state.http.search_members(name, self.id, limit) + return [Member(data=raw_member, guild=self, state=state) for raw_member in data] + async def fetch_members(self, *, limit: Optional[int] = 1000, after: SnowflakeTime = MISSING) -> AsyncIterator[Member]: """Retrieves an :term:`asynchronous iterator` that enables receiving the guild's members. In order to use this, :meth:`Intents.members` must be enabled. From 9cc25129ecb32c31c7ef6eb3eb29bd66a781e539 Mon Sep 17 00:00:00 2001 From: Sacul Date: Sat, 16 Aug 2025 16:48:57 +0800 Subject: [PATCH 2/5] Add `search_members` method --- discord/http.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/discord/http.py b/discord/http.py index 9d1b85a50359..c5fc7e07fc60 100644 --- a/discord/http.py +++ b/discord/http.py @@ -1616,6 +1616,11 @@ def get_members( r = Route('GET', '/guilds/{guild_id}/members', guild_id=guild_id) return self.request(r, params=params) + def search_members(self, query: str, guild_id: Snowflake, 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]: return self.request(Route('GET', '/guilds/{guild_id}/members/{member_id}', guild_id=guild_id, member_id=member_id)) From a2c285d916984254a0a96ab4f03295fd420df66a Mon Sep 17 00:00:00 2001 From: Sacul Date: Sat, 16 Aug 2025 16:50:20 +0800 Subject: [PATCH 3/5] Update guild.py --- discord/guild.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/discord/guild.py b/discord/guild.py index 6183d4dc928a..c1531f1582a3 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -2463,7 +2463,7 @@ async def active_threads(self) -> List[Thread]: return threads async def fetch_members_named(self, name: str, *, limit: Optional[int] = 1) -> List[Member]: - """A List[:class:`.Member`] members whose username or nickname starts + """A List[:class:`.Member`] whose username or nickname starts with the provided `name`. .. versionadded:: 2.6 From 3846b9f68833a8481e524a773a164b1041abb948 Mon Sep 17 00:00:00 2001 From: Sacul Date: Sat, 16 Aug 2025 18:51:21 +0800 Subject: [PATCH 4/5] Update guild.py --- discord/guild.py | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/discord/guild.py b/discord/guild.py index c1531f1582a3..470c8bce52f4 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -2462,11 +2462,13 @@ async def active_threads(self) -> List[Thread]: return threads - async def fetch_members_named(self, name: str, *, limit: Optional[int] = 1) -> List[Member]: - """A List[:class:`.Member`] whose username or nickname starts + async def fetch_members_named(self, name: str, *, limit: Optional[int] = 1000) -> List[Member]: + """|coro| + + A List[:class:`Member`] whose username or nickname starts with the provided `name`. - .. versionadded:: 2.6 + .. versionadded:: 2.? Parameters @@ -2474,24 +2476,19 @@ async def fetch_members_named(self, name: str, *, limit: Optional[int] = 1) -> L name: :class:`str` The string to match a username and nickname against. limit: Optional[:class:`int`] - The maximum number of members to return. Max of 1000, defaults to 1. + The maximum number of members to return. Defaults to 1000. Raises ------ HTTPException Getting the members failed. - ValueError - Maximum number of members to return of 1000 was exceeded. Returns ------ - List[:class:`.Member`] + List[:class:`Member`] A list of members. """ - if limit > 1000: - raise ValueError('Maximum number of members to return was exceeded') - state = self._state data = await state.http.search_members(name, self.id, limit) return [Member(data=raw_member, guild=self, state=state) for raw_member in data] From f2cd662c5f32c44dc711bad156b83ead1979fe3d Mon Sep 17 00:00:00 2001 From: Sacul Date: Sat, 16 Aug 2025 19:01:16 +0800 Subject: [PATCH 5/5] Update guild.py --- discord/guild.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/discord/guild.py b/discord/guild.py index 470c8bce52f4..9f2350a8cfd7 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -2465,7 +2465,7 @@ async def active_threads(self) -> List[Thread]: async def fetch_members_named(self, name: str, *, limit: Optional[int] = 1000) -> List[Member]: """|coro| - A List[:class:`Member`] whose username or nickname starts + Returns a list of members whose username or nickname starts with the provided `name`. .. versionadded:: 2.? @@ -2476,17 +2476,17 @@ async def fetch_members_named(self, name: str, *, limit: Optional[int] = 1000) - name: :class:`str` The string to match a username and nickname against. limit: Optional[:class:`int`] - The maximum number of members to return. Defaults to 1000. + The maximum number of members to return. Max of 1000. Raises ------ HTTPException Getting the members failed. - +s Returns ------ List[:class:`Member`] - A list of members. + A list of matched members. """ state = self._state