refactor: migrate deprecated apis to use warn_deprecation decorator

- add warn_deprecation decorator to analytics_rule_v1 and analytics_rules_v1
- add warn_deprecation decorator to override and overrides classes
- add warn_deprecation decorator to synonym and synonyms classes
- remove manual deprecation warning code and global flags
- replace manual logger.warning calls with decorator-based warnings

Author: tharropoulos

src/typesense/analytics_rule_v1.py

@@ -28,6 +28,7 @@
     import typing_extensions as typing
 
 from typesense.api_call import ApiCall
+from typesense.logger import warn_deprecation
 from typesense.types.analytics_rule_v1 import (
     RuleDeleteSchema,
     RuleSchemaForCounters,
@@ -47,6 +48,10 @@ class AnalyticsRuleV1:
         rule_id (str): The ID of the analytics rule.
     """
 
+    @warn_deprecation(
+        "AnalyticsRuleV1 is deprecated on v30+. Use client.analytics.rules[rule_id] instead.",
+        flag_name="analytics_rules_v1_deprecation",
+    )
     def __init__(self, api_call: ApiCall, rule_id: str):
         """
         Initialize the AnalyticsRuleV1 object.

src/typesense/analytics_rules_v1.py

@@ -27,6 +27,8 @@
 
 import sys
 
+from typesense.logger import warn_deprecation
+
 if sys.version_info >= (3, 11):
     import typing
 else:
@@ -63,6 +65,10 @@ class AnalyticsRulesV1(object):
 
     resource_path: typing.Final[str] = "/analytics/rules"
 
+    @warn_deprecation(
+        "AnalyticsRulesV1 is deprecated on v30+. Use client.analytics instead.",
+        flag_name="analytics_rules_v1_deprecation",
+    )
     def __init__(self, api_call: ApiCall):
         """
         Initialize the AnalyticsRulesV1 object.

src/typesense/override.py

@@ -22,6 +22,7 @@
 """
 
 from typesense.api_call import ApiCall
+from typesense.logger import warn_deprecation
 from typesense.types.override import OverrideDeleteSchema, OverrideSchema
 
 
@@ -38,6 +39,11 @@ class Override:
         override_id (str): The ID of the override.
     """
 
+    @warn_deprecation(
+        "The override API (collections/{collection}/overrides/{override_id}) is deprecated is removed on v30+. "
+        "Use curation sets (curation_sets) instead.",
+        flag_name="overrides_deprecation",
+    )
     def __init__(
         self,
         api_call: ApiCall,

src/typesense/overrides.py

@@ -30,6 +30,7 @@
 import sys
 
 from typesense.api_call import ApiCall
+from typesense.logger import warn_deprecation
 from typesense.override import Override
 from typesense.types.override import (
     OverrideCreateSchema,
@@ -59,6 +60,10 @@ class Overrides:
 
     resource_path: typing.Final[str] = "overrides"
 
+    @warn_deprecation(
+        "Overrides is deprecated on v30+. Use client.curation_sets instead.",
+        flag_name="overrides_deprecation",
+    )
     def __init__(
         self,
         api_call: ApiCall,

src/typesense/synonym.py

@@ -22,11 +22,9 @@
 """
 
 from typesense.api_call import ApiCall
-from typesense.logger import logger
+from typesense.logger import warn_deprecation
 from typesense.types.synonym import SynonymDeleteSchema, SynonymSchema
 
-_synonym_deprecation_warned = False
-
 
 class Synonym:
     """
@@ -41,6 +39,11 @@ class Synonym:
         synonym_id (str): The ID of the synonym.
     """
 
+    @warn_deprecation(
+        "The synonym API (collections/{collection}/synonyms/{synonym_id}) is deprecated is removed on v30+. "
+        "Use synonym sets (synonym_sets) instead.",
+        flag_name="synonyms_deprecation",
+    )
     def __init__(
         self,
         api_call: ApiCall,
@@ -66,7 +69,6 @@ def retrieve(self) -> SynonymSchema:
         Returns:
             SynonymSchema: The schema containing the synonym details.
         """
-        self._maybe_warn_deprecation()
         return self.api_call.get(self._endpoint_path(), entity_type=SynonymSchema)
 
     def delete(self) -> SynonymDeleteSchema:
@@ -76,7 +78,6 @@ def delete(self) -> SynonymDeleteSchema:
         Returns:
             SynonymDeleteSchema: The schema containing the deletion response.
         """
-        self._maybe_warn_deprecation()
         return self.api_call.delete(
             self._endpoint_path(),
             entity_type=SynonymDeleteSchema,
@@ -100,12 +101,3 @@ def _endpoint_path(self) -> str:
                 self.synonym_id,
             ],
         )
-
-    def _maybe_warn_deprecation(self) -> None:
-        global _synonym_deprecation_warned
-        if not _synonym_deprecation_warned:
-            logger.warning(
-                "The synonyms API (collections/{collection}/synonyms) is deprecated and will be "
-                "removed in a future release. Use synonym sets (synonym_sets) instead."
-            )
-            _synonym_deprecation_warned = True

src/typesense/synonyms.py

@@ -28,15 +28,13 @@
 import sys
 
 from typesense.api_call import ApiCall
+from typesense.logger import warn_deprecation
 from typesense.synonym import Synonym
 from typesense.types.synonym import (
     SynonymCreateSchema,
     SynonymSchema,
     SynonymsRetrieveSchema,
 )
-from typesense.logger import logger
-
-_synonyms_deprecation_warned = False
 
 if sys.version_info >= (3, 11):
     import typing
@@ -60,6 +58,11 @@ class Synonyms:
 
     resource_path: typing.Final[str] = "synonyms"
 
+    @warn_deprecation(
+        "The synonyms API (collections/{collection}/synonyms) is deprecated is removed on v30+. "
+        "Use synonym sets (synonym_sets) instead.",
+        flag_name="synonyms_deprecation",
+    )
     def __init__(self, api_call: ApiCall, collection_name: str):
         """
         Initialize the Synonyms object.
@@ -101,7 +104,6 @@ def upsert(self, synonym_id: str, schema: SynonymCreateSchema) -> SynonymSchema:
         Returns:
             SynonymSchema: The created or updated synonym.
         """
-        self._maybe_warn_deprecation()
         response = self.api_call.put(
             self._endpoint_path(synonym_id),
             body=schema,
@@ -116,7 +118,6 @@ def retrieve(self) -> SynonymsRetrieveSchema:
         Returns:
             SynonymsRetrieveSchema: The schema containing all synonyms.
         """
-        self._maybe_warn_deprecation()
         response = self.api_call.get(
             self._endpoint_path(),
             entity_type=SynonymsRetrieveSchema,
@@ -144,12 +145,3 @@ def _endpoint_path(self, synonym_id: typing.Union[str, None] = None) -> str:
                 synonym_id,
             ],
         )
-
-    def _maybe_warn_deprecation(self) -> None:
-        global _synonyms_deprecation_warned
-        if not _synonyms_deprecation_warned:
-            logger.warning(
-                "The synonyms API (collections/{collection}/synonyms) is deprecated and will be "
-                "removed in a future release. Use synonym sets (synonym_sets) instead."
-            )
-            _synonyms_deprecation_warned = True