feat(users): ✨ add api for search users

Author: MerleLiuKun

pytwitter/api.py

@@ -1786,6 +1786,47 @@ def get_me(
             return_json=return_json,
         )
 
+    def search_users(
+        self,
+        query: str,
+        *,
+        max_results: Optional[int] = None,
+        next_token: Optional[str] = None,
+        user_fields: Optional[Union[str, List, Tuple]] = None,
+        expansions: Optional[Union[str, List, Tuple]] = None,
+        tweet_fields: Optional[Union[str, List, Tuple]] = None,
+        return_json: bool = False,
+    ) -> Union[dict, md.Response]:
+        """
+        returns Users that match a search query.
+        :param query: One query for matching Users.
+        :param max_results: The maximum number of search results to be returned by a request. A number between 1 and 1000. By default, a request response will return 100 results.
+        :param next_token: Token for the pagination.
+        :param user_fields: Fields for the user object.
+        :param expansions: Fields for the expansions.
+        :param tweet_fields: Fields for the tweet object, Expansion required.
+        :param return_json: Type for returned data. If you set True JSON data will be returned.
+        :return: Response instance or json.
+        """
+
+        args = {
+            "query": query,
+            "max_results": max_results,
+            "next_token": next_token,
+            "user.fields": enf_comma_separated(name="user_fields", value=user_fields),
+            "expansions": enf_comma_separated(name="expansions", value=expansions),
+            "tweet.fields": enf_comma_separated(
+                name="tweet_fields", value=tweet_fields
+            ),
+        }
+        return self._get(
+            url="https://api.twitter.com/2/users/search",
+            params=args,
+            cls=md.User,
+            multi=True,
+            return_json=return_json,
+        )
+
     def get_following(
         self,
         user_id: str,

testdata/apis/user/search_users_resp.json

@@ -0,0 +1 @@
+{"data":[{"location":"127.0.0.1","name":"Developers","description":"The voice of the X Dev team and your official source for updates, news, and events, related to the X API.","username":"XDevelopers","id":"2244994945"},{"location":"Seattle, WA","name":"Suhem Parack","description":"Partner Engineering @XDevelopers","username":"suhemparack","id":"857699969263964161"},{"location":"New York, NY","name":"Chris Park","description":"𝕏 | @X @API @XDevelopers","username":"chrisparkX","id":"2533341854"},{"location":"Islington, London","name":"Haim Vaturi","description":"@XDevelopers","username":"haimvat","id":"853388192"},{"location":"Canada","name":"ROBLOX Devs","description":"Follow this account for a lot of cool ROBLOXdev from all kinds of different ROBLOX developers! Not an official @ROBLOX twitter account","username":"RBXdevelopers","id":"829457852125306890"},{"location":"東京都港区","name":"Twitter Dev Japan","description":"This account is no longer active. Follow @XDevelopers for updates.","username":"TwitterDevJP","id":"70915829"},{"name":"Rains®™☔️🧠 0xdevelopers.eth.eth","description":"","username":"0xdevelopersTm","id":"1619352801104039936"},{"name":"Project X Developers","description":"","username":"ProXDevelopers","id":"708786906058756096"},{"location":"Los Angeles, CA","name":"XDevelopersUS","description":"","username":"XDevelopersUS","id":"1315227013028904960"},{"location":"Rio de Janeiro & São Paulo","name":"XDevelopers","description":"Contato e Suporte Via Telefone (RJ): 21 980534086 e Via Email: [email protected]","username":"XDevBrasil","id":"3296066705"},{"location":"India","name":"ajX developers","description":"app developernweb designernentrepreneurnmachine learningnAI PIONEERnage just 16","username":"ajXdevelopers","id":"1234855897370910720"},{"name":"The X Developers","description":"","username":"TheXDevelopers","id":"1453775246"},{"name":"RBLXdevelopers","description":"","username":"XdevelopersRbl","id":"1513675812486193158"},{"location":"London, England","name":"XDevelopersUK","description":"","username":"XDevelopersUK","id":"1375178694520627204"},{"name":"xDevelopers","description":"","username":"xdevelopers_st","id":"1363113804842881024"},{"name":"xdevelopers","description":"","username":"itdenps","id":"2885219741"},{"name":"X","description":"","username":"xdevelopers_es","id":"1684769811539087362"},{"name":"XDevelopers","description":"","username":"XDeveloper_","id":"732232220803485696"},{"name":"xDevelopers","description":"","username":"developers_x","id":"831241935675326464"},{"location":"United States","name":"0xspark","description":"","username":"0xdevelopers","id":"1580611661169238016"},{"name":"XeXDevelopers","description":"","username":"XeXDevelopers","id":"2175184873"},{"name":"Izu","description":"","username":"XDevelopersJP","id":"1684141917129539585"},{"name":"SXDevelopers","description":"","username":"SonyXDevelopers","id":"1521381726"}],"meta":{"next_token":"5qym3iwm0f05lqu1ezcdkohsl2i4lyq"}}

tests/apis/test_users.py

@@ -104,7 +104,7 @@ def test_get_me(api_with_user, helpers):
 
     responses.add(
         responses.GET,
-        url=f"https://api.twitter.com/2/users/me",
+        url="https://api.twitter.com/2/users/me",
         json=me_data,
     )
 
@@ -116,6 +116,20 @@ def test_get_me(api_with_user, helpers):
     assert me_resp.data.id == "2244994945"
 
 
+@responses.activate
+def test_search_users(api_with_user, helpers):
+    responses.add(
+        responses.GET,
+        url="https://api.twitter.com/2/users/search",
+        json=helpers.load_json_data("testdata/apis/user/search_users_resp.json"),
+    )
+    search_resp = api_with_user.search_users(
+        query="developers",
+        user_fields="id,name,username,description,location",
+    )
+    assert search_resp.data[0].name == "Developers"
+
+
 @responses.activate
 def test_block_and_unblock_user(api_with_user):
     user_id, target_user_id = "123456", "78910"