Update and improve documentation for API.search_30_day

Automatically use docstring for documentation
Improve method and documentation order
Add API documentation header to match API reference index
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 8a082ae0e53e04458e86818eaf1dd7cb078ad95a..45fd579b7370f78477eb91e812409d152f4de192 100644 (file)
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -16,6 +16,11 @@ This page contains some basic documentation for the Tweepy module.
 
 .. autoclass:: API
 
+Premium Search APIs
+-------------------
+
+.. automethod:: API.search_30_day
+
 Tweets
 ------
 
@@ -277,53 +282,6 @@ Get app rate limit status
 Search Methods
 --------------
 
-.. method:: API.search_30_day(environment_name, query, [tag], [fromDate], \
-                              [toDate], [maxResults], [next])
-
-   Premium search that provides Tweets posted within the last 30 days.
-
-   :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.
-
-
 .. method:: API.search_full_archive(environment_name, query, [tag], \
                                     [fromDate], [toDate], [maxResults], [next])
 

diff --git a/tweepy/api.py b/tweepy/api.py
index 6682d42aeee91b4a091f03b4f7d4a2ae168331b8..1c9ea821bc36b89a1f9114b77effa6b6f35bf034 100644 (file)
--- a/tweepy/api.py
+++ b/tweepy/api.py
@@ -250,6 +250,79 @@ class API:
             return result
         finally:
             self.session.close()
+    
+    # Premium Search APIs
+
+    @pagination(mode='next')
+    @payload('status', list=True)
+    def search_30_day(self, label, query, **kwargs):
+        """search_30_day(label, query, *, tag, fromDate, toDate, maxResults, \
+                         next)
+
+        Premium search that provides Tweets posted within the last 30 days.
+
+        :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/30day/{label}', endpoint_parameters=(
+                'query', 'tag', 'fromDate', 'toDate', 'maxResults', 'next'
+            ), query=query, **kwargs
+        )
 
     # Get Tweet timelines
 
@@ -2830,17 +2903,6 @@ class API:
             ), use_cache=False, **kwargs
         )
 
-    @pagination(mode='next')
-    @payload('status', list=True)
-    def search_30_day(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/30day/{label}', endpoint_parameters=(
-                'query', 'tag', 'fromDate', 'toDate', 'maxResults', 'next'
-            ), query=query, **kwargs
-        )
-
     @pagination(mode='next')
     @payload('status', list=True)
     def search_full_archive(self, label, query, **kwargs):