diff options
Diffstat (limited to 'mastodon/search.py')
| -rw-r--r-- | mastodon/search.py | 91 |
1 files changed, 91 insertions, 0 deletions
diff --git a/mastodon/search.py b/mastodon/search.py new file mode 100644 index 0000000..b77002f --- /dev/null +++ b/mastodon/search.py | |||
| @@ -0,0 +1,91 @@ | |||
| 1 | # search.py - search endpoints | ||
| 2 | |||
| 3 | from .versions import _DICT_VERSION_SEARCHRESULT | ||
| 4 | from .errors import MastodonVersionError | ||
| 5 | from .utility import api_version | ||
| 6 | |||
| 7 | from .internals import Mastodon as Internals | ||
| 8 | |||
| 9 | class Mastodon(Internals): | ||
| 10 | ### | ||
| 11 | # Reading data: Searching | ||
| 12 | ### | ||
| 13 | def __ensure_search_params_acceptable(self, account_id, offset, min_id, max_id): | ||
| 14 | """ | ||
| 15 | Internal Helper: Throw a MastodonVersionError if version is < 2.8.0 but parameters | ||
| 16 | for search that are available only starting with 2.8.0 are specified. | ||
| 17 | """ | ||
| 18 | if any(item is not None for item in (account_id, offset, min_id, max_id)): | ||
| 19 | if not self.verify_minimum_version("2.8.0", cached=True): | ||
| 20 | raise MastodonVersionError("Advanced search parameters require Mastodon 2.8.0+") | ||
| 21 | |||
| 22 | @api_version("1.1.0", "2.8.0", _DICT_VERSION_SEARCHRESULT) | ||
| 23 | def search(self, q, resolve=True, result_type=None, account_id=None, offset=None, min_id=None, max_id=None, exclude_unreviewed=True): | ||
| 24 | """ | ||
| 25 | Fetch matching hashtags, accounts and statuses. Will perform webfinger | ||
| 26 | lookups if resolve is True. Full-text search is only enabled if | ||
| 27 | the instance supports it, and is restricted to statuses the logged-in | ||
| 28 | user wrote or was mentioned in. | ||
| 29 | |||
| 30 | `result_type` can be one of "accounts", "hashtags" or "statuses", to only | ||
| 31 | search for that type of object. | ||
| 32 | |||
| 33 | Specify `account_id` to only get results from the account with that id. | ||
| 34 | |||
| 35 | `offset`, `min_id` and `max_id` can be used to paginate. | ||
| 36 | |||
| 37 | `exclude_unreviewed` can be used to restrict search results for hashtags to only | ||
| 38 | those that have been reviewed by moderators. It is on by default. When using the | ||
| 39 | v1 search API (pre 2.4.1), it is ignored. | ||
| 40 | |||
| 41 | Will use search_v1 (no tag dicts in return values) on Mastodon versions before | ||
| 42 | 2.4.1), search_v2 otherwise. Parameters other than resolve are only available | ||
| 43 | on Mastodon 2.8.0 or above - this function will throw a MastodonVersionError | ||
| 44 | if you try to use them on versions before that. Note that the cached version | ||
| 45 | number will be used for this to avoid uneccesary requests. | ||
| 46 | |||
| 47 | Returns a :ref:`search result dict <search result dict>`, with tags as `hashtag dicts`_. | ||
| 48 | """ | ||
| 49 | if self.verify_minimum_version("2.4.1", cached=True): | ||
| 50 | return self.search_v2(q, resolve=resolve, result_type=result_type, account_id=account_id, offset=offset, min_id=min_id, max_id=max_id, exclude_unreviewed=exclude_unreviewed) | ||
| 51 | else: | ||
| 52 | self.__ensure_search_params_acceptable(account_id, offset, min_id, max_id) | ||
| 53 | return self.search_v1(q, resolve=resolve) | ||
| 54 | |||
| 55 | @api_version("1.1.0", "2.1.0", "2.1.0") | ||
| 56 | def search_v1(self, q, resolve=False): | ||
| 57 | """ | ||
| 58 | Identical to `search_v2()`, except in that it does not return | ||
| 59 | tags as :ref:`hashtag dicts <hashtag dicts>`. | ||
| 60 | |||
| 61 | Returns a :ref:`search result dict <search result dict>`. | ||
| 62 | """ | ||
| 63 | params = self.__generate_params(locals()) | ||
| 64 | if not resolve: | ||
| 65 | del params['resolve'] | ||
| 66 | return self.__api_request('GET', '/api/v1/search', params) | ||
| 67 | |||
| 68 | @api_version("2.4.1", "2.8.0", _DICT_VERSION_SEARCHRESULT) | ||
| 69 | def search_v2(self, q, resolve=True, result_type=None, account_id=None, offset=None, min_id=None, max_id=None, exclude_unreviewed=True): | ||
| 70 | """ | ||
| 71 | Identical to `search_v1()`, except in that it returns tags as | ||
| 72 | :ref:`hashtag dicts <hashtag dicts>`, has more parameters, and resolves by default. | ||
| 73 | |||
| 74 | For more details documentation, please see `search()` | ||
| 75 | |||
| 76 | Returns a :ref:`search result dict <search result dict>`. | ||
| 77 | """ | ||
| 78 | self.__ensure_search_params_acceptable(account_id, offset, min_id, max_id) | ||
| 79 | params = self.__generate_params(locals()) | ||
| 80 | |||
| 81 | if not resolve: | ||
| 82 | del params["resolve"] | ||
| 83 | |||
| 84 | if not exclude_unreviewed or not self.verify_minimum_version("3.0.0", cached=True): | ||
| 85 | del params["exclude_unreviewed"] | ||
| 86 | |||
| 87 | if "result_type" in params: | ||
| 88 | params["type"] = params["result_type"] | ||
| 89 | del params["result_type"] | ||
| 90 | |||
| 91 | return self.__api_request('GET', '/api/v2/search', params) | ||