@@ -2027,6 +2027,36 @@ def fetch_members(
20272027
20282028 return MemberIterator (self , limit = limit , after = after )
20292029
2030+ async def search_members (self , query : str , * , limit : int = 1000 ) -> list [Member ]:
2031+ """Search for guild members whose usernames or nicknames start with the query string. Unlike :meth:`fetch_members`, this does not require :meth:`Intents.members`.
2032+
2033+ .. note::
2034+
2035+ This method is an API call. For general usage, consider filtering :attr:`members` instead.
2036+
2037+ .. versionadded:: 2.6
2038+
2039+ Parameters
2040+ ----------
2041+ query: :class:`str`
2042+ Searches for usernames and nicknames that start with this string, case-insensitive.
2043+ limit: :class:`int`
2044+ The maximum number of members to retrieve, up to 1000.
2045+
2046+ Returns
2047+ -------
2048+ List[:class:`Member`]
2049+ The list of members that have matched the query.
2050+
2051+ Raises
2052+ ------
2053+ HTTPException
2054+ Getting the members failed.
2055+ """
2056+
2057+ data = await self ._state .http .search_members (self .id , query , limit )
2058+ return [Member (data = m , guild = self , state = self ._state ) for m in data ]
2059+
20302060 async def fetch_member (self , member_id : int , / ) -> Member :
20312061 """|coro|
20322062
@@ -3354,7 +3384,7 @@ async def query_members(
33543384 self ,
33553385 query : str | None = None ,
33563386 * ,
3357- limit : int = 5 ,
3387+ limit : int | None = 5 ,
33583388 user_ids : list [int ] | None = None ,
33593389 presences : bool = False ,
33603390 cache : bool = True ,
@@ -3372,22 +3402,22 @@ async def query_members(
33723402 ----------
33733403 query: Optional[:class:`str`]
33743404 The string that the username's start with.
3375- limit: :class:`int`
3376- The maximum number of members to send back. This must be
3377- a number between 5 and 100.
3378- presences: :class:`bool`
3405+ user_ids: Optional[List[:class:`int`]]
3406+ List of user IDs to search for. If the user ID is not in the guild then it won't be returned.
3407+
3408+ .. versionadded:: 1.4
3409+ limit: Optional[:class:`int`]
3410+ The maximum number of members to send back. If no query is passed, passing ``None`` returns all members.
3411+ If a ``query`` or ``user_ids`` is passed, must be between 1 and 100. Defaults to 5.
3412+ presences: Optional[:class:`bool`]
33793413 Whether to request for presences to be provided. This defaults
33803414 to ``False``.
33813415
33823416 .. versionadded:: 1.6
33833417
33843418 cache: :class:`bool`
33853419 Whether to cache the members internally. This makes operations
3386- such as :meth:`get_member` work for those that matched.
3387- user_ids: Optional[List[:class:`int`]]
3388- List of user IDs to search for. If the user ID is not in the guild then it won't be returned.
3389-
3390- .. versionadded:: 1.4
3420+ such as :meth:`get_member` work for those that matched. Defaults to ``True``.
33913421
33923422 Returns
33933423 -------
@@ -3407,20 +3437,25 @@ async def query_members(
34073437 if presences and not self ._state ._intents .presences :
34083438 raise ClientException ("Intents.presences must be enabled to use this." )
34093439
3410- if query is None :
3411- if query == "" :
3412- raise ValueError ("Cannot pass empty query string." )
3440+ if not limit or limit > 100 or limit < 1 :
3441+ if query or user_ids :
3442+ raise ValueError (
3443+ "limit must be between 1 and 100 when using query or user_ids"
3444+ )
3445+ if not limit :
3446+ query = ""
3447+ limit = 0
34133448
3449+ if query is None :
34143450 if user_ids is None :
3415- raise ValueError ("Must pass either query or user_ids" )
3451+ raise ValueError ("Must pass query or user_ids, or set limit to None " )
34163452
34173453 if user_ids is not None and query is not None :
34183454 raise ValueError ("Cannot pass both query and user_ids" )
34193455
34203456 if user_ids is not None and not user_ids :
34213457 raise ValueError ("user_ids must contain at least 1 value" )
34223458
3423- limit = min (100 , limit or 5 )
34243459 return await self ._state .query_members (
34253460 self ,
34263461 query = query ,
![pre-commit-ci[bot]](https://avatars.githubusercontent.com/in/68672?v=4&size=40){kind=avatar}
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4&size=40){kind=avatar}
0 commit comments