Merge pull request #107 from tharropoulos/master

feat: add deprecation warning system for v30+ api migrations & add curation sets to client

Author: kishorenc

pyproject.toml

@@ -16,7 +16,7 @@ classifiers = [
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
 ]
-dependencies = ["requests"]
+dependencies = ["requests", "typing-extensions"]
 dynamic = ["version"]
 
 [project.urls]

src/typesense/analytics_rule_v1.py

@@ -27,14 +27,20 @@
 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 (
     RuleDeleteSchema,
     RuleSchemaForCounters,
     RuleSchemaForQueries,
 )
 
 
+@deprecated(
+    "AnalyticsRuleV1 is deprecated on v30+. Use client.analytics.rules[rule_id] instead."
+)
 class AnalyticsRuleV1:
     """
     Class for managing individual analytics rules in Typesense (V1).
@@ -47,6 +53,10 @@ class AnalyticsRuleV1:
         rule_id (str): The ID of the analytics rule.
     """
 
+    @warn_deprecation(  # type: ignore[misc]
+        "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.
@@ -102,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

@@ -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(  # type: ignore[misc]
+        "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.
@@ -161,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,13 +38,14 @@
     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
 from typesense.configuration import ConfigDict, Configuration
 from typesense.conversations_models import ConversationsModels
+from typesense.curation_sets import CurationSets
 from typesense.debug import Debug
 from typesense.keys import Keys
 from typesense.metrics import Metrics
@@ -73,7 +76,8 @@ class Client:
         keys (Keys): Instance for managing API keys.
         aliases (Aliases): Instance for managing collection aliases.
         analyticsV1 (AnalyticsV1): Instance for analytics operations (V1).
-        analytics (AnalyticsV30): Instance for analytics operations (v30).
+        analytics (Analytics): Instance for analytics operations (v30).
+        curation_sets (CurationSets): Instance for Curation Sets (v30+)
         stemming (Stemming): Instance for stemming dictionary operations.
         operations (Operations): Instance for various Typesense operations.
         debug (Debug): Instance for debug operations.
@@ -93,8 +97,10 @@ def __init__(self, config_dict: ConfigDict) -> None:
         Example:
             >>> config = {
             ...     "api_key": "your_api_key",
-            ...     "nodes": [{"host": "localhost", "port": "8108", "protocol": "http"}],
-            ...     "connection_timeout_seconds": 2
+            ...     "nodes": [
+            ...         {"host": "localhost", "port": "8108", "protocol": "http"}
+            ...     ],
+            ...     "connection_timeout_seconds": 2,
             ... }
             >>> client = Client(config)
         """
@@ -104,9 +110,10 @@ 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)
         self.operations = Operations(self.api_call)
         self.debug = Debug(self.api_call)
         self.stopwords = Stopwords(self.api_call)
@@ -115,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,
         *,
@@ -140,7 +155,6 @@ def typed_collection(
             >>> class Company(DocumentSchema):
             ...     name: str
             ...     num_employees: int
-            ...
             >>> client = Client(config)
             >>> companies_collection = client.typed_collection(model=Company)
             # This is equivalent to:

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/configuration.py

@@ -80,6 +80,8 @@ class ConfigDict(typing.TypedDict):
             dictionaries or URLs that represent the read replica nodes.
 
         connection_timeout_seconds (float): The connection timeout in seconds.
+
+        suppress_deprecation_warnings (bool): Whether to suppress deprecation warnings.
     """
 
     nodes: typing.List[typing.Union[str, NodeConfigDict]]
@@ -96,6 +98,7 @@ class ConfigDict(typing.TypedDict):
         typing.List[typing.Union[str, NodeConfigDict]]
     ]  # deprecated
     connection_timeout_seconds: typing.NotRequired[float]
+    suppress_deprecation_warnings: typing.NotRequired[bool]
 
 
 class Node:
@@ -220,6 +223,7 @@ def __init__(
         )
         self.verify = config_dict.get("verify", True)
         self.additional_headers = config_dict.get("additional_headers", {})
+        self.suppress_deprecation_warnings = config_dict.get("suppress_deprecation_warnings", False)
 
     def _handle_nearest_node(
         self,
@@ -371,7 +375,7 @@ def show_deprecation_warnings(config_dict: ConfigDict) -> None:
                 to check for deprecated fields.
         """
         if config_dict.get("timeout_seconds"):
-            logger.warn(
+            logger.warning(
                 " ".join(
                     [
                         "Deprecation warning: timeout_seconds is now renamed",
@@ -381,7 +385,7 @@ def show_deprecation_warnings(config_dict: ConfigDict) -> None:
             )
 
         if config_dict.get("master_node"):
-            logger.warn(
+            logger.warning(
                 " ".join(
                     [
                         "Deprecation warning: master_node is now consolidated",
@@ -391,7 +395,7 @@ def show_deprecation_warnings(config_dict: ConfigDict) -> None:
             )
 
         if config_dict.get("read_replica_nodes"):
-            logger.warn(
+            logger.warning(
                 " ".join(
                     [
                         "Deprecation warning: read_replica_nodes is now",

src/typesense/curation_set.py

@@ -9,11 +9,12 @@
 
 from typesense.api_call import ApiCall
 from typesense.types.curation_set import (
-    CurationSetSchema,
+    CurationItemDeleteSchema,
+    CurationItemSchema,
     CurationSetDeleteSchema,
     CurationSetListItemResponseSchema,
-    CurationItemSchema,
-    CurationItemDeleteSchema,
+    CurationSetSchema,
+    CurationSetUpsertSchema,
 )
 
 
@@ -43,6 +44,17 @@ def delete(self) -> CurationSetDeleteSchema:
         )
         return response
 
+    def upsert(
+        self,
+        payload: CurationSetUpsertSchema,
+    ) -> CurationSetSchema:
+        response: CurationSetSchema = self.api_call.put(
+            "/".join([self._endpoint_path]),
+            body=payload,
+            entity_type=CurationSetSchema,
+        )
+        return response
+
     # Items sub-resource
     @property
     def _items_path(self) -> str:
@@ -92,5 +104,3 @@ def delete_item(self, item_id: str) -> CurationItemDeleteSchema:
             entity_type=CurationItemDeleteSchema,
         )
         return response
-
-

src/typesense/curation_sets.py

@@ -10,9 +10,7 @@
 from typesense.api_call import ApiCall
 from typesense.curation_set import CurationSet
 from typesense.types.curation_set import (
-    CurationSetSchema,
     CurationSetsListResponseSchema,
-    CurationSetUpsertSchema,
 )
 
 
@@ -34,15 +32,3 @@ def __getitem__(self, curation_set_name: str) -> CurationSet:
         from typesense.curation_set import CurationSet as PerSet
 
         return PerSet(self.api_call, curation_set_name)
-
-    def upsert(
-        self,
-        curation_set_name: str,
-        payload: CurationSetUpsertSchema,
-    ) -> CurationSetSchema:
-        response: CurationSetSchema = self.api_call.put(
-            "/".join([CurationSets.resource_path, curation_set_name]),
-            body=payload,
-            entity_type=CurationSetSchema,
-        )
-        return response