Update and improve documentation for API.search_full_archive

Automatically use docstring for documentation
Improve method and documentation order
Update environment_name parameter name to label in documentation
Add return type to documentation

diff --git a/docs/api.rst b/docs/api.rst
index 45fd579b7370f78477eb91e812409d152f4de192..f724d9430b8193c844fd3cf91bf19de67946cca5 100644 (file)
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -21,6 +21,8 @@ Premium Search APIs
 
 .. automethod:: API.search_30_day
 
+.. automethod:: API.search_full_archive
+
 Tweets
 ------
 
@@ -279,57 +281,6 @@ Get app rate limit status
 .. automethod:: API.rate_limit_status
 
 
-Search Methods
---------------
-
-.. method:: API.search_full_archive(environment_name, query, [tag], \
-                                    [fromDate], [toDate], [maxResults], [next])
-
-   Premium search that provides Tweets from as early as 2006, starting with the
-   first Tweet posted in March 2006.
-
-   :param environment_name: The (case-sensitive) label associated with your
-      search developer environment, as displayed at
-      https://developer.twitter.com/en/account/environments.
-   :param query: The equivalent of one premium rule/filter, with up to 1,024
-      characters (256 with Sandbox dev environments).
-      This parameter should include ALL portions of the rule/filter, including
-      all operators, and portions of the rule should not be separated into
-      other parameters of the query.
-   :param tag: Tags can be used to segregate rules and their matching data into
-      different logical groups. If a rule tag is provided, the rule tag is
-      included in the 'matching_rules' attribute.
-      It is recommended to assign rule-specific UUIDs to rule tags and maintain
-      desired mappings on the client side.
-   :param fromDate: The oldest UTC timestamp (from most recent 30 days) from
-      which the Tweets will be provided. Timestamp is in minute granularity and
-      is inclusive (i.e. 12:00 includes the 00 minute).
-      Specified: Using only the fromDate with no toDate parameter will deliver
-      results for the query going back in time from now( ) until the fromDate.
-      Not Specified: If a fromDate is not specified, the API will deliver all
-      of the results for 30 days prior to now( ) or the toDate (if specified).
-      If neither the fromDate or toDate parameter is used, the API will deliver
-      all results for the most recent 30 days, starting at the time of the
-      request, going backwards.
-   :param toDate: The latest, most recent UTC timestamp to which the Tweets
-      will be provided. Timestamp is in minute granularity and is not inclusive
-      (i.e. 11:59 does not include the 59th minute of the hour).
-      Specified: Using only the toDate with no fromDate parameter will deliver
-      the most recent 30 days of data prior to the toDate.
-      Not Specified: If a toDate is not specified, the API will deliver all of
-      the results from now( ) for the query going back in time to the fromDate.
-      If neither the fromDate or toDate parameter is used, the API will deliver
-      all results for the entire 30-day index, starting at the time of the
-      request, going backwards.
-   :param maxResults: The maximum number of search results to be returned by a
-      request. A number between 10 and the system limit (currently 500, 100 for
-      Sandbox environments). By default, a request response will return 100
-      results.
-   :param next: This parameter is used to get the next 'page' of results. The
-      value used with the parameter is pulled directly from the response
-      provided by the API, and should not be modified.
-
-
 :mod:`tweepy.error` --- Exceptions
 ==================================
 

diff --git a/tweepy/api.py b/tweepy/api.py
index 1c9ea821bc36b89a1f9114b77effa6b6f35bf034..265e78cb99f3eca6989deee3e2f46ef63488042c 100644 (file)
--- a/tweepy/api.py
+++ b/tweepy/api.py
@@ -324,6 +324,78 @@ class API:
             ), query=query, **kwargs
         )
 
+    @pagination(mode='next')
+    @payload('status', list=True)
+    def search_full_archive(self, label, query, **kwargs):
+        """search_full_archive(label, query, *, tag, fromDate, toDate, \
+                               maxResults, next)
+
+        Premium search that provides Tweets from as early as 2006, starting
+        with the first Tweet posted in March 2006.
+
+        :param label: The (case-sensitive) label associated with your search
+            developer environment, as displayed at
+            https://developer.twitter.com/en/account/environments.
+        :param query: The equivalent of one premium rule/filter, with up to
+            1,024 characters (256 with Sandbox dev environments).
+            
+            This parameter should include ALL portions of the rule/filter,
+            including all operators, and portions of the rule should not be
+            separated into other parameters of the query.
+        :param tag: Tags can be used to segregate rules and their matching data
+            into different logical groups. If a rule tag is provided, the rule
+            tag is included in the 'matching_rules' attribute.
+
+            It is recommended to assign rule-specific UUIDs to rule tags and
+            maintain desired mappings on the client side.
+        :param fromDate: The oldest UTC timestamp (from most recent 30 days)
+            from which the Tweets will be provided. Timestamp is in minute
+            granularity and is inclusive (i.e. 12:00 includes the 00 minute).
+
+            Specified: Using only the fromDate with no toDate parameter will
+            deliver results for the query going back in time from now( ) until
+            the fromDate.
+
+            Not Specified: If a fromDate is not specified, the API will deliver
+            all of the results for 30 days prior to now( ) or the toDate (if
+            specified).
+
+            If neither the fromDate or toDate parameter is used, the API will
+            deliver all results for the most recent 30 days, starting at the
+            time of the request, going backwards.
+        :param toDate: The latest, most recent UTC timestamp to which the
+            Tweets will be provided. Timestamp is in minute granularity and is
+            not inclusive (i.e. 11:59 does not include the 59th minute of the
+            hour).
+
+            Specified: Using only the toDate with no fromDate parameter will
+            deliver the most recent 30 days of data prior to the toDate.
+
+            Not Specified: If a toDate is not specified, the API will deliver
+            all of the results from now( ) for the query going back in time to
+            the fromDate.
+
+            If neither the fromDate or toDate parameter is used, the API will
+            deliver all results for the entire 30-day index, starting at the
+            time of the request, going backwards.
+        :param maxResults: The maximum number of search results to be returned
+            by a request. A number between 10 and the system limit (currently
+            500, 100 for Sandbox environments). By default, a request response
+            will return 100 results.
+        :param next: This parameter is used to get the next 'page' of results.
+            The value used with the parameter is pulled directly from the
+            response provided by the API, and should not be modified.
+
+        :rtype: list of :class:`Status` objects
+
+        :reference: https://developer.twitter.com/en/docs/twitter-api/premium/search-api/api-reference/premium-search
+        """
+        return self.request(
+            'GET', f'tweets/search/fullarchive/{label}', endpoint_parameters=(
+                'query', 'tag', 'fromDate', 'toDate', 'maxResults', 'next'
+            ), query=query, **kwargs
+        )
+
     # Get Tweet timelines
 
     @pagination(mode='id')
@@ -2902,14 +2974,3 @@ class API:
                 'resources',
             ), use_cache=False, **kwargs
         )
-
-    @pagination(mode='next')
-    @payload('status', list=True)
-    def search_full_archive(self, label, query, **kwargs):
-        """ :reference: https://developer.twitter.com/en/docs/twitter-api/premium/search-api/api-reference/premium-search
-        """
-        return self.request(
-            'GET', f'tweets/search/fullarchive/{label}', endpoint_parameters=(
-                'query', 'tag', 'fromDate', 'toDate', 'maxResults', 'next'
-            ), query=query, **kwargs
-        )