feat: add typing deprecation decorators to deprecated apis

- add @deprecated decorator to analytics_rule_v1, analytics_v1 classes
- add @deprecated decorator to override, overrides, synonyms classes
- convert analyticsV1 to private attribute with deprecated property
- convert overrides and synonyms to private attributes with deprecated properties
- remove manual deprecation warning code from analytics_v1
- enable static type checker warnings for deprecated apis

Author: tharropoulos

src/typesense/analytics_rule_v1.py

@@ -27,6 +27,8 @@
 else:
     import typing_extensions as typing
 
+from typing_extensions import deprecated
+
 from typesense.api_call import ApiCall
 from typesense.logger import warn_deprecation
 from typesense.types.analytics_rule_v1 import (
@@ -36,6 +38,9 @@
 )
 
 
+@deprecated(
+    "AnalyticsRuleV1 is deprecated on v30+. Use client.analytics.rules[rule_id] instead."
+)
 class AnalyticsRuleV1:
     """
     Class for managing individual analytics rules in Typesense (V1).
@@ -48,7 +53,7 @@ class AnalyticsRuleV1:
         rule_id (str): The ID of the analytics rule.
     """
 
-    @warn_deprecation(
+    @warn_deprecation(  # type: ignore[misc]
         "AnalyticsRuleV1 is deprecated on v30+. Use client.analytics.rules[rule_id] instead.",
         flag_name="analytics_rules_v1_deprecation",
     )
@@ -107,5 +112,3 @@ def _endpoint_path(self) -> str:
         from typesense.analytics_rules_v1 import AnalyticsRulesV1
 
         return "/".join([AnalyticsRulesV1.resource_path, self.rule_id])
-
-

src/typesense/analytics_rules_v1.py

@@ -65,7 +65,7 @@ class AnalyticsRulesV1(object):
 
     resource_path: typing.Final[str] = "/analytics/rules"
 
-    @warn_deprecation(
+    @warn_deprecation(  # type: ignore[misc]
         "AnalyticsRulesV1 is deprecated on v30+. Use client.analytics instead.",
         flag_name="analytics_rules_v1_deprecation",
     )
@@ -167,5 +167,3 @@ def retrieve(self) -> RulesRetrieveSchema:
             entity_type=RulesRetrieveSchema,
         )
         return response
-
-

src/typesense/analytics_v1.py

@@ -17,13 +17,13 @@
 versions through the use of the typing_extensions library.
 """
 
+from typing_extensions import deprecated
+
 from typesense.analytics_rules_v1 import AnalyticsRulesV1
 from typesense.api_call import ApiCall
-from typesense.logger import logger
-
-_analytics_v1_deprecation_warned = False
 
 
+@deprecated("AnalyticsV1 is deprecated on v30+. Use client.analytics instead.")
 class AnalyticsV1(object):
     """
     Class for managing analytics in Typesense (V1).
@@ -46,13 +46,6 @@ def __init__(self, api_call: ApiCall) -> None:
 
     @property
     def rules(self) -> AnalyticsRulesV1:
-        global _analytics_v1_deprecation_warned
-        if not _analytics_v1_deprecation_warned:
-            logger.warning(
-                "AnalyticsV1 is deprecated and will be removed in a future release. "
-                "Use client.analytics instead."
-            )
-            _analytics_v1_deprecation_warned = True
         return self._rules
 
 

src/typesense/client.py

@@ -28,6 +28,8 @@
 
 import sys
 
+from typing_extensions import deprecated
+
 from typesense.types.document import DocumentSchema
 
 if sys.version_info >= (3, 11):
@@ -36,8 +38,8 @@
     import typing_extensions as typing
 
 from typesense.aliases import Aliases
-from typesense.analytics_v1 import AnalyticsV1
 from typesense.analytics import Analytics
+from typesense.analytics_v1 import AnalyticsV1
 from typesense.api_call import ApiCall
 from typesense.collection import Collection
 from typesense.collections import Collections
@@ -108,7 +110,7 @@ def __init__(self, config_dict: ConfigDict) -> None:
         self.multi_search = MultiSearch(self.api_call)
         self.keys = Keys(self.api_call)
         self.aliases = Aliases(self.api_call)
-        self.analyticsV1 = AnalyticsV1(self.api_call)
+        self._analyticsV1 = AnalyticsV1(self.api_call)
         self.analytics = Analytics(self.api_call)
         self.stemming = Stemming(self.api_call)
         self.curation_sets = CurationSets(self.api_call)
@@ -120,6 +122,14 @@ def __init__(self, config_dict: ConfigDict) -> None:
         self.conversations_models = ConversationsModels(self.api_call)
         self.nl_search_models = NLSearchModels(self.api_call)
 
+    @property
+    @deprecated(
+        "AnalyticsV1 is deprecated on v30+. Use client.analytics instead.",
+        category=None,
+    )
+    def analyticsV1(self) -> AnalyticsV1:
+        return self._analyticsV1
+
     def typed_collection(
         self,
         *,

src/typesense/collection.py

@@ -20,6 +20,8 @@
 
 import sys
 
+from typing_extensions import deprecated
+
 from typesense.types.collection import CollectionSchema, CollectionUpdateSchema
 
 if sys.version_info >= (3, 11):
@@ -63,8 +65,24 @@ def __init__(self, api_call: ApiCall, name: str):
         self.name = name
         self.api_call = api_call
         self.documents: Documents[TDoc] = Documents(api_call, name)
-        self.overrides = Overrides(api_call, name)
-        self.synonyms = Synonyms(api_call, name)
+        self._overrides = Overrides(api_call, name)
+        self._synonyms = Synonyms(api_call, name)
+
+    @property
+    @deprecated(
+        "Synonyms is deprecated on v30+. Use client.synonym_sets instead.",
+        category=None,
+    )
+    def synonyms(self) -> Synonyms:
+        return self._synonyms
+
+    @property
+    @deprecated(
+        "Overrides is deprecated on v30+. Use client.curation_sets instead.",
+        category=None,
+    )
+    def overrides(self) -> Overrides:
+        return self._overrides
 
     def retrieve(self) -> CollectionSchema:
         """

src/typesense/override.py

@@ -21,11 +21,14 @@
 versions through the use of the typing_extensions library.
 """
 
+from typing_extensions import deprecated
+
 from typesense.api_call import ApiCall
 from typesense.logger import warn_deprecation
 from typesense.types.override import OverrideDeleteSchema, OverrideSchema
 
 
+@deprecated("Override is deprecated on v30+. Use client.curation_sets instead.")
 class Override:
     """
     Class for managing individual overrides in a Typesense collection.
@@ -39,7 +42,7 @@ class Override:
         override_id (str): The ID of the override.
     """
 
-    @warn_deprecation(
+    @warn_deprecation(  # type: ignore[misc]
         "The override API (collections/{collection}/overrides/{override_id}) is deprecated is removed on v30+. "
         "Use curation sets (curation_sets) instead.",
         flag_name="overrides_deprecation",

src/typesense/overrides.py

@@ -29,6 +29,8 @@
 
 import sys
 
+from typing_extensions import deprecated
+
 from typesense.api_call import ApiCall
 from typesense.logger import warn_deprecation
 from typesense.override import Override
@@ -44,6 +46,7 @@
     import typing_extensions as typing
 
 
+@deprecated("Overrides is deprecated on v30+. Use client.curation_sets instead.")
 class Overrides:
     """
     Class for managing overrides in a Typesense collection.
@@ -60,15 +63,15 @@ class Overrides:
 
     resource_path: typing.Final[str] = "overrides"
 
-    @warn_deprecation(
+    @warn_deprecation( # type: ignore[misc]
         "Overrides is deprecated on v30+. Use client.curation_sets instead.",
         flag_name="overrides_deprecation",
     )
     def __init__(
         self,
         api_call: ApiCall,
         collection_name: str,
-    ) -> None:
+    ) -> None:  
         """
         Initialize the Overrides object.
 

src/typesense/synonym.py

@@ -39,7 +39,7 @@ class Synonym:
         synonym_id (str): The ID of the synonym.
     """
 
-    @warn_deprecation(
+    @warn_deprecation(  # type: ignore[misc]
         "The synonym API (collections/{collection}/synonyms/{synonym_id}) is deprecated is removed on v30+. "
         "Use synonym sets (synonym_sets) instead.",
         flag_name="synonyms_deprecation",

src/typesense/synonyms.py

@@ -27,6 +27,8 @@
 
 import sys
 
+from typing_extensions import deprecated
+
 from typesense.api_call import ApiCall
 from typesense.logger import warn_deprecation
 from typesense.synonym import Synonym
@@ -42,6 +44,7 @@
     import typing_extensions as typing
 
 
+@deprecated("Synonyms is deprecated on v30+. Use client.synonym_sets instead.")
 class Synonyms:
     """
     Class for managing synonyms in a Typesense collection.
@@ -58,12 +61,12 @@ class Synonyms:
 
     resource_path: typing.Final[str] = "synonyms"
 
-    @warn_deprecation(
+    @warn_deprecation( # type: ignore[misc]
         "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):
+    def __init__(self, api_call: ApiCall, collection_name: str) -> None:  
         """
         Initialize the Synonyms object.