From 4d794d7d0b51de054e7992ba8ea93a32c7c5944f Mon Sep 17 00:00:00 2001 From: Harmon Date: Sun, 11 Apr 2021 15:55:35 -0500 Subject: [PATCH] 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 --- docs/api.rst | 52 +++---------------------------- tweepy/api.py | 84 ++++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 78 insertions(+), 58 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 8a082ae..45fd579 100644 --- 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 6682d42..1c9ea82 100644 --- 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): -- 2.25.1