From 9242d88ac339db13febad3cf0879d374a12c4313 Mon Sep 17 00:00:00 2001 From: Harmon Date: Sun, 11 Apr 2021 16:03:28 -0500 Subject: [PATCH] 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 --- docs/api.rst | 53 ++------------------------------ tweepy/api.py | 83 ++++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 74 insertions(+), 62 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 45fd579..f724d94 100644 --- 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 1c9ea82..265e78c 100644 --- 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 - ) -- 2.25.1