Improce search() versioning

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

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: