From cb0fcfec15e6802fd7553e7e90782805e015902e Mon Sep 17 00:00:00 2001 From: Harmon Date: Wed, 7 Apr 2021 09:25:38 -0500 Subject: [PATCH] Update and improve documentation for API.search Automatically use docstring for documentation Improve method and documentation order Add API documentation header to match API reference index --- docs/api.rst | 57 ++++-------------------------------- tweepy/api.py | 80 +++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 73 insertions(+), 64 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 660ccf0..6850620 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -59,6 +59,11 @@ Post, retrieve, and engage with Tweets .. automethod:: API.update_with_media +Search Tweets +^^^^^^^^^^^^^ + +.. automethod:: API.search + User methods ------------ @@ -466,58 +471,6 @@ Saved Searches Methods Search Methods -------------- -.. method:: API.search(q, [geocode], [lang], [locale], [result_type], \ - [count], [until], [since_id], [max_id], \ - [include_entities]) - - Returns a collection of relevant Tweets matching a specified query. - - Please note that Twitter's search service and, by extension, the Search API - is not meant to be an exhaustive source of Tweets. Not all Tweets will be - indexed or made available via the search interface. - - In API v1.1, the response format of the Search API has been improved to - return Tweet objects more similar to the objects you’ll find across the REST - API and platform. However, perspectival attributes (fields that pertain to - the perspective of the authenticating user) are not currently supported on - this endpoint.\ [#]_\ [#]_ - - :param q: the search query string of 500 characters maximum, including - operators. Queries may additionally be limited by complexity. - :param geocode: Returns tweets by users located within a given radius of the - given latitude/longitude. The location is preferentially taking from the - Geotagging API, but will fall back to their Twitter profile. The - parameter value is specified by "latitide,longitude,radius", where radius - units must be specified as either "mi" (miles) or "km" (kilometers). Note - that you cannot use the near operator via the API to geocode arbitrary - locations; however you can use this geocode parameter to search near - geocodes directly. A maximum of 1,000 distinct "sub-regions" will be - considered when using the radius modifier. - :param lang: Restricts tweets to the given language, given by an ISO 639-1 - code. Language detection is best-effort. - :param locale: Specify the language of the query you are sending (only ja is - currently effective). This is intended for language-specific consumers - and the default should work in the majority of cases. - :param result_type: Specifies what type of search results you would prefer - to receive. The current default is "mixed." Valid values include: - - * mixed : include both popular and real time results in the response - * recent : return only the most recent results in the response - * popular : return only the most popular results in the response - :param count: |count| - :param until: Returns tweets created before the given date. Date should be - formatted as YYYY-MM-DD. Keep in mind that the search index has a 7-day - limit. In other words, no tweets will be found for a date older than one - week. - :param since_id: |since_id| There are limits to the number of Tweets which - can be accessed through the API. If the limit of Tweets has occurred - since the since_id, the since_id will be forced to the oldest ID - available. - :param max_id: |max_id| - :param include_entities: |include_entities| - :rtype: :class:`SearchResults` object - - .. method:: API.search_30_day(environment_name, query, [tag], [fromDate], \ [toDate], [maxResults], [next]) diff --git a/tweepy/api.py b/tweepy/api.py index f8485b2..b563d0d 100644 --- a/tweepy/api.py +++ b/tweepy/api.py @@ -801,6 +801,74 @@ class API: ), status=status, files=files, **kwargs ) + # Search Tweets + + @pagination(mode='id') + @payload('search_results') + def search(self, q, **kwargs): + """search(q, *, geocode, lang, locale, result_type, count, until, \ + since_id, max_id, include_entities) + + Returns a collection of relevant Tweets matching a specified query. + + Please note that Twitter's search service and, by extension, the Search + API is not meant to be an exhaustive source of Tweets. Not all Tweets + will be indexed or made available via the search interface. + + In API v1.1, the response format of the Search API has been improved to + return Tweet objects more similar to the objects you’ll find across the + REST API and platform. However, perspectival attributes (fields that + pertain to the perspective of the authenticating user) are not + currently supported on this endpoint.\ [#]_\ [#]_ + + :param q: the search query string of 500 characters maximum, including + operators. Queries may additionally be limited by complexity. + :param geocode: Returns tweets by users located within a given radius + of the given latitude/longitude. The location is preferentially + taking from the Geotagging API, but will fall back to their Twitter + profile. The parameter value is specified by + "latitide,longitude,radius", where radius units must be specified + as either "mi" (miles) or "km" (kilometers). Note that you cannot + use the near operator via the API to geocode arbitrary locations; + however you can use this geocode parameter to search near geocodes + directly. A maximum of 1,000 distinct "sub-regions" will be + considered when using the radius modifier. + :param lang: Restricts tweets to the given language, given by an ISO + 639-1 code. Language detection is best-effort. + :param locale: Specify the language of the query you are sending (only + ja is currently effective). This is intended for language-specific + consumers and the default should work in the majority of cases. + :param result_type: Specifies what type of search results you would + prefer to receive. The current default is "mixed." Valid values + include: + + * mixed : include both popular and real time results in the \ + response + * recent : return only the most recent results in the response + * popular : return only the most popular results in the response + :param count: |count| + :param until: Returns tweets created before the given date. Date should + be formatted as YYYY-MM-DD. Keep in mind that the search index has + a 7-day limit. In other words, no tweets will be found for a date + older than one week. + :param since_id: |since_id| There are limits to the number of Tweets + which can be accessed through the API. If the limit of Tweets has + occurred since the since_id, the since_id will be forced to the + oldest ID available. + :param max_id: |max_id| + :param include_entities: |include_entities| + + :rtype: :class:`SearchResults` object + + :reference: https://developer.twitter.com/en/docs/twitter-api/v1/tweets/search/api-reference/get-search-tweets + """ + return self.request( + 'GET', 'search/tweets', endpoint_parameters=( + 'q', 'geocode', 'lang', 'locale', 'result_type', 'count', + 'until', 'since_id', 'max_id', 'include_entities' + ), q=q, **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 @@ -1619,18 +1687,6 @@ class API: ), lat=lat, long=long, **kwargs ) - @pagination(mode='id') - @payload('search_results') - def search(self, q, **kwargs): - """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/tweets/search/api-reference/get-search-tweets - """ - return self.request( - 'GET', 'search/tweets', endpoint_parameters=( - 'q', 'geocode', 'lang', 'locale', 'result_type', 'count', - 'until', 'since_id', 'max_id', 'include_entities' - ), q=q, **kwargs - ) - @pagination(mode='next') @payload('status', list=True) def search_30_day(self, label, query, **kwargs): -- 2.25.1