Update and improve documentation for API.lookup_users

Automatically use docstring for documentation
Improve method and documentation order
Update parameter names in documentation
Improve parameter order in documentation

diff --git a/docs/api.rst b/docs/api.rst
index 9bee31364450b151e9d79b14ad7526b205e8b0ca..9fda16f795d2da38fa87e97327d10bc51b922a83 100644 (file)
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -129,6 +129,8 @@ Follow, search, and get users
 
 .. automethod:: API.show_friendship
 
+.. automethod:: API.lookup_users
+
 
 User methods
 ------------
@@ -150,34 +152,6 @@ User methods
    :rtype: :class:`User` object
 
 
-.. method:: API.lookup_users([user_ids], [screen_names], [include_entities], \
-                             [tweet_mode])
-
-   Returns fully-hydrated user objects for up to 100 users per request.
-
-   There are a few things to note when using this method.
-
-   * You must be following a protected user to be able to see their most recent
-     status update. If you don't follow a protected user their status will be
-     removed.
-   * The order of user IDs or screen names may not match the order of users in
-     the returned array.
-   * If a requested user is unknown, suspended, or deleted, then that user will
-     not be returned in the results list.
-   * If none of your lookup criteria can be satisfied by returning a user
-     object, a HTTP 404 will be thrown.
-
-   :param user_ids: A list of user IDs, up to 100 are allowed in a single
-                    request.
-   :param screen_names: A list of screen names, up to 100 are allowed in a
-                        single request.
-   :param include_entities: |include_entities|
-   :param tweet_mode: Valid request values are compat and extended, which give
-                      compatibility mode and extended mode, respectively for
-                      Tweets that contain over 140 characters.
-   :rtype: list of :class:`User` objects
-
-
 .. method:: API.search_users(q, [count], [page])
 
    Run a search for users similar to Find People button on Twitter.com; the

diff --git a/tweepy/api.py b/tweepy/api.py
index b596962b22087126ee284cf300218130e8b74144..104da97e0dceebb4a5ea8ef8c2fb67cde6fcad46 100644 (file)
--- a/tweepy/api.py
+++ b/tweepy/api.py
@@ -1592,6 +1592,45 @@ class API:
             ), **kwargs
         )
 
+    @payload('user', list=True)
+    def lookup_users(self, *, screen_name=None, user_id=None, **kwargs):
+        """lookup_users(*, screen_name, user_id, include_entities, tweet_mode)
+
+        Returns fully-hydrated user objects for up to 100 users per request.
+
+        There are a few things to note when using this method.
+
+        * You must be following a protected user to be able to see their most
+            recent status update. If you don't follow a protected user their
+            status will be removed.
+        * The order of user IDs or screen names may not match the order of
+            users in the returned array.
+        * If a requested user is unknown, suspended, or deleted, then that user
+            will not be returned in the results list.
+        * If none of your lookup criteria can be satisfied by returning a user
+            object, a HTTP 404 will be thrown.
+
+        :param screen_name: A list of screen names, up to 100 are allowed in a
+                            single request.
+        :param user_id: A list of user IDs, up to 100 are allowed in a single
+                        request.
+        :param include_entities: |include_entities|
+        :param tweet_mode: Valid request values are compat and extended, which
+                           give compatibility mode and extended mode,
+                           respectively for Tweets that contain over 140
+                           characters.
+
+        :rtype: list of :class:`User` objects
+
+        :reference: https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup
+        """
+        return self.request(
+            'POST', 'users/lookup', endpoint_parameters=(
+                'screen_name', 'user_id', 'include_entities', 'tweet_mode'
+            ), screen_name=list_to_csv(screen_name),
+            user_id=list_to_csv(user_id), **kwargs
+        )
+
     def media_upload(self, filename, *, file=None, chunked=False,
                      media_category=None, additional_owners=None, **kwargs):
         """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/overview
@@ -1769,17 +1808,6 @@ class API:
             ), **kwargs
         )
 
-    @payload('user', list=True)
-    def lookup_users(self, *, screen_name=None, user_id=None, **kwargs):
-        """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup
-        """
-        return self.request(
-            'POST', 'users/lookup', endpoint_parameters=(
-                'screen_name', 'user_id', 'include_entities', 'tweet_mode'
-            ), screen_name=list_to_csv(screen_name),
-            user_id=list_to_csv(user_id), **kwargs
-        )
-
     def me(self):
         """ Get the authenticated user """
         return self.get_user(screen_name=self.auth.get_username())