add: synonym_set APIs

Author: harisarang

src/typesense/analytics_v1.py

@@ -19,6 +19,9 @@
 
 from typesense.analytics_rules_v1 import AnalyticsRulesV1
 from typesense.api_call import ApiCall
+from typesense.logger import logger
+
+_analytics_v1_deprecation_warned = False
 
 
 class AnalyticsV1(object):
@@ -39,6 +42,17 @@ def __init__(self, api_call: ApiCall) -> None:
         Args:
             api_call (ApiCall): The API call object for making requests.
         """
-        self.rules = AnalyticsRulesV1(api_call)
+        self._rules = AnalyticsRulesV1(api_call)
+
+    @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

@@ -51,6 +51,7 @@
 from typesense.operations import Operations
 from typesense.stemming import Stemming
 from typesense.stopwords import Stopwords
+from typesense.synonym_sets import SynonymSets
 
 TDoc = typing.TypeVar("TDoc", bound=DocumentSchema)
 
@@ -109,6 +110,7 @@ def __init__(self, config_dict: ConfigDict) -> None:
         self.operations = Operations(self.api_call)
         self.debug = Debug(self.api_call)
         self.stopwords = Stopwords(self.api_call)
+        self.synonym_sets = SynonymSets(self.api_call)
         self.metrics = Metrics(self.api_call)
         self.conversations_models = ConversationsModels(self.api_call)
         self.nl_search_models = NLSearchModels(self.api_call)

src/typesense/synonym.py

@@ -22,6 +22,9 @@
 """
 
 from typesense.api_call import ApiCall
+from typesense.logger import logger
+
+_synonym_deprecation_warned = False
 from typesense.types.synonym import SynonymDeleteSchema, SynonymSchema
 
 
@@ -63,6 +66,7 @@ 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:
@@ -72,6 +76,7 @@ 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,
@@ -95,3 +100,12 @@ 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/synonym_set.py

@@ -0,0 +1,43 @@
+"""Client for single Synonym Set operations."""
+
+import sys
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+from typesense.api_call import ApiCall
+from typesense.types.synonym_set import (
+    SynonymSetDeleteSchema,
+    SynonymSetRetrieveSchema,
+)
+
+
+class SynonymSet:
+    def __init__(self, api_call: ApiCall, name: str) -> None:
+        self.api_call = api_call
+        self.name = name
+
+    @property
+    def _endpoint_path(self) -> str:
+        from typesense.synonym_sets import SynonymSets
+
+        return "/".join([SynonymSets.resource_path, self.name])
+
+    def retrieve(self) -> SynonymSetRetrieveSchema:
+        response: SynonymSetRetrieveSchema = self.api_call.get(
+            self._endpoint_path,
+            as_json=True,
+            entity_type=SynonymSetRetrieveSchema,
+        )
+        return response
+
+    def delete(self) -> SynonymSetDeleteSchema:
+        response: SynonymSetDeleteSchema = self.api_call.delete(
+            self._endpoint_path,
+            entity_type=SynonymSetDeleteSchema,
+        )
+        return response
+
+

src/typesense/synonym_sets.py

@@ -0,0 +1,50 @@
+"""Client for Synonym Sets collection operations."""
+
+import sys
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+from typesense.api_call import ApiCall
+from typesense.types.synonym_set import (
+    SynonymSetCreateSchema,
+    SynonymSetDeleteSchema,
+    SynonymSetRetrieveSchema,
+    SynonymSetSchema,
+)
+
+
+class SynonymSets:
+    resource_path: typing.Final[str] = "/synonym_sets"
+
+    def __init__(self, api_call: ApiCall) -> None:
+        self.api_call = api_call
+
+    def retrieve(self) -> typing.List[SynonymSetSchema]:
+        response: typing.List[SynonymSetSchema] = self.api_call.get(
+            SynonymSets.resource_path,
+            as_json=True,
+            entity_type=typing.List[SynonymSetSchema],
+        )
+        return response
+
+    def __getitem__(self, synonym_set_name: str) -> "SynonymSet":
+        from typesense.synonym_set import SynonymSet as PerSet
+
+        return PerSet(self.api_call, synonym_set_name)
+
+    def upsert(
+        self,
+        synonym_set_name: str,
+        payload: SynonymSetCreateSchema,
+    ) -> SynonymSetSchema:
+        response: SynonymSetSchema = self.api_call.put(
+            "/".join([SynonymSets.resource_path, synonym_set_name]),
+            body=payload,
+            entity_type=SynonymSetSchema,
+        )
+        return response
+
+

src/typesense/synonyms.py

@@ -34,6 +34,9 @@
     SynonymSchema,
     SynonymsRetrieveSchema,
 )
+from typesense.logger import logger
+
+_synonyms_deprecation_warned = False
 
 if sys.version_info >= (3, 11):
     import typing
@@ -98,6 +101,7 @@ 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,
@@ -112,6 +116,7 @@ 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,
@@ -139,3 +144,12 @@ 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

src/typesense/types/synonym_set.py

@@ -0,0 +1,72 @@
+"""Synonym Set types for Typesense Python Client."""
+
+import sys
+
+from typesense.types.collection import Locales
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+
+class SynonymItemSchema(typing.TypedDict):
+    """
+    Schema representing an individual synonym item inside a synonym set.
+
+    Attributes:
+        id (str): Unique identifier for the synonym item.
+        synonyms (list[str]): The synonyms array.
+        root (str, optional): For 1-way synonyms, indicates the root word that words in
+            the synonyms parameter map to.
+        locale (Locales, optional): Locale for the synonym.
+        symbols_to_index (list[str], optional): Symbols to index as-is in synonyms.
+    """
+
+    id: str
+    synonyms: typing.List[str]
+    root: typing.NotRequired[str]
+    locale: typing.NotRequired[Locales]
+    symbols_to_index: typing.NotRequired[typing.List[str]]
+
+
+class SynonymSetCreateSchema(typing.TypedDict):
+    """
+    Schema for creating or updating a synonym set.
+
+    Attributes:
+        items (list[SynonymItemSchema]): Array of synonym items.
+    """
+
+    items: typing.List[SynonymItemSchema]
+
+
+class SynonymSetSchema(SynonymSetCreateSchema):
+    """
+    Schema representing a synonym set.
+
+    Attributes:
+        name (str): Name of the synonym set.
+    """
+
+    name: str
+
+
+class SynonymSetsRetrieveSchema(typing.List[SynonymSetSchema]):
+    """Deprecated alias for list of synonym sets; use List[SynonymSetSchema] directly."""
+
+
+class SynonymSetRetrieveSchema(SynonymSetCreateSchema):
+    """Response schema for retrieving a single synonym set by name."""
+
+
+class SynonymSetDeleteSchema(typing.TypedDict):
+    """Response schema for deleting a synonym set.
+
+    Attributes:
+        name (str): Name of the deleted synonym set.
+    """
+
+    name: str
+
+

tests/analytics_test.py

@@ -7,7 +7,7 @@
 from typesense.api_call import ApiCall
 
 
-@pytest.mark.skipif(is_v30_or_above(Client({"api_key": "xyz", "nodes": [{"host": "localhost", "port": 8108, "protocol": "http"}]})), reason="Skip AnalyticsV1 tests on v30+")
+@pytest.mark.skipif(not is_v30_or_above(Client({"api_key": "xyz", "nodes": [{"host": "localhost", "port": 8108, "protocol": "http"}]})), reason="Skip AnalyticsV1 tests on v30+")
 def test_init(fake_api_call: ApiCall) -> None:
     """Test that the AnalyticsV1 object is initialized correctly."""
     analytics = Analytics(fake_api_call)

tests/fixtures/synonym_set_fixtures.py

@@ -0,0 +1,73 @@
+"""Fixtures for the synonym set tests."""
+
+import pytest
+import requests
+
+from typesense.api_call import ApiCall
+from typesense.synonym_set import SynonymSet
+from typesense.synonym_sets import SynonymSets
+
+
+@pytest.fixture(scope="function", name="create_synonym_set")
+def create_synonym_set_fixture() -> None:
+    """Create a synonym set in the Typesense server."""
+    url = "http://localhost:8108/synonym_sets/test-set"
+    headers = {"X-TYPESENSE-API-KEY": "xyz"}
+    data = {
+        "items": [
+            {
+                "id": "company_synonym",
+                "synonyms": ["companies", "corporations", "firms"],
+            }
+        ]
+    }
+
+    resp = requests.put(url, headers=headers, json=data, timeout=3)
+    resp.raise_for_status()
+
+
+@pytest.fixture(scope="function", name="delete_all_synonym_sets")
+def clear_typesense_synonym_sets() -> None:
+    """Remove all synonym sets from the Typesense server."""
+    url = "http://localhost:8108/synonym_sets"
+    headers = {"X-TYPESENSE-API-KEY": "xyz"}
+
+    # Get the list of synonym sets
+    response = requests.get(url, headers=headers, timeout=3)
+    response.raise_for_status()
+    data = response.json()
+
+    # Delete each synonym set
+    for synset in data:
+        name = synset.get("name")
+        if not name:
+            continue
+        delete_url = f"{url}/{name}"
+        delete_response = requests.delete(delete_url, headers=headers, timeout=3)
+        delete_response.raise_for_status()
+
+
+@pytest.fixture(scope="function", name="actual_synonym_sets")
+def actual_synonym_sets_fixture(actual_api_call: ApiCall) -> SynonymSets:
+    """Return a SynonymSets object using a real API."""
+    return SynonymSets(actual_api_call)
+
+
+@pytest.fixture(scope="function", name="actual_synonym_set")
+def actual_synonym_set_fixture(actual_api_call: ApiCall) -> SynonymSet:
+    """Return a SynonymSet object using a real API."""
+    return SynonymSet(actual_api_call, "test-set")
+
+
+@pytest.fixture(scope="function", name="fake_synonym_sets")
+def fake_synonym_sets_fixture(fake_api_call: ApiCall) -> SynonymSets:
+    """Return a SynonymSets object with test values."""
+    return SynonymSets(fake_api_call)
+
+
+@pytest.fixture(scope="function", name="fake_synonym_set")
+def fake_synonym_set_fixture(fake_api_call: ApiCall) -> SynonymSet:
+    """Return a SynonymSet object with test values."""
+    return SynonymSet(fake_api_call, "test-set")
+
+

tests/import_test.py

@@ -20,6 +20,7 @@
     "operations",
     "override",
     "stopword",
+    "synonym_set",
     "synonym",
 ]
 
@@ -41,6 +42,8 @@
     "overrides",
     "operations",
     "synonyms",
+    "synonym_set",
+    "synonym_sets",
     "preprocess",
     "stopwords",
 ]