diff --git a/docs/index.rst b/docs/index.rst index 9988a5f..637e771 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -780,6 +780,9 @@ Mastodon.py throws a `MastodonVersionError`. With the following functions, you can make Mastodon.py re-check the server version or explicitly determine if a specific minimum Version is available. +Long-running applications that aim to support multiple Mastodon versions +should do this from time to time in case a server they are running against +updated. .. automethod:: Mastodon.retrieve_mastodon_version .. automethod:: Mastodon.verify_minimum_version diff --git a/mastodon/Mastodon.py b/mastodon/Mastodon.py index 27acbaa..ebdeffc 100644 --- a/mastodon/Mastodon.py +++ b/mastodon/Mastodon.py @@ -356,13 +356,16 @@ class Mastodon: self.mastodon_major, self.mastodon_minor, self.mastodon_patch = parse_version_string(version_str) return version_str - def verify_minimum_version(self, version_str): + def verify_minimum_version(self, version_str, cached=False): """ Update version info from server and verify that at least the specified version is present. + If you specify "cached", the version info update part is skipped. + Returns True if version requirement is satisfied, False if not. """ - self.retrieve_mastodon_version() + if not cached: + self.retrieve_mastodon_version() major, minor, patch = parse_version_string(version_str) if major > self.mastodon_major: return False @@ -1106,7 +1109,16 @@ class Mastodon: ### # Reading data: Searching ### - @api_version("2.8.0", "2.8.0", __DICT_VERSION_SEARCHRESULT) + def __ensure_search_params_acceptable(self, account_id, offset, min_id, max_id): + """ + Internal Helper: Throw a MastodonVersionError if version is < 2.8.0 but parameters + for search that are available only starting with 2.8.0 are specified. + """ + if not account_id is None or not offset is None or not min_id is None or not max_id is None: + if self.verify_minimum_version("2.8.0", cached=True) == False: + raise MastodonVersionError("Advanced search parameters require Mastodon 2.8.0+") + + @api_version("1.1.0", "2.8.0", __DICT_VERSION_SEARCHRESULT) def search(self, q, resolve=True, result_type=None, account_id=None, offset=None, min_id=None, max_id=None): """ Fetch matching hashtags, accounts and statuses. Will perform webfinger @@ -1121,12 +1133,22 @@ class Mastodon: `offset`, `min_id` and `max_id` can be used to paginate. + Will use search_v1 (no tag dicts in return values) on Mastodon versions before + 2.4.1), search_v2 otherwise. Parameters other than resolve are only available + on Mastodon 2.8.0 or above - this function will throw a MastodonVersionError + if you try to use them on versions before that. Note that the cached version + number will be used for this to avoid uneccesary requests. + Returns a `search result dict`_, with tags as `hashtag dicts`_. """ - 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) - - @api_version("1.1.0", "2.1.0", __DICT_VERSION_SEARCHRESULT) + if self.verify_minimum_version("2.4.1", cached=True) == True: + 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) + else: + self.__ensure_search_params_acceptable(account_id, offset, min_id, max_id) + return self.search_v1(q, resolve=resolve) + + @api_version("1.1.0", "2.1.0", "2.1.0") def search_v1(self, q, resolve=False): """ Identical to `search_v2()`, except in that it does not return @@ -1139,7 +1161,7 @@ class Mastodon: del params['resolve'] return self.__api_request('GET', '/api/v1/search', params) - @api_version("2.8.0", "2.8.0", __DICT_VERSION_SEARCHRESULT) + @api_version("2.4.1", "2.8.0", __DICT_VERSION_SEARCHRESULT) def search_v2(self, q, resolve=True, result_type=None, account_id=None, offset=None, min_id=None, max_id=None): """ Identical to `search_v1()`, except in that it returns tags as @@ -1147,6 +1169,7 @@ class Mastodon: Returns a `search result dict`_. """ + self.__ensure_search_params_acceptable(account_id, offset, min_id, max_id) params = self.__generate_params(locals()) if resolve == False: