feat(synonym-set): add async support for synonym set operations

tharropoulos · tharropoulos · commit 723b6dca9e28 · 2025-12-09T11:06:12.000+02:00
- add AsyncSynonymSet class for async individual synonym set operations
- add AsyncSynonymSets class for async synonym sets collection operations
- add async tests for synonym set and sets functionality
- add async fixtures for testing async synonym set operations
- remove future annotations imports from test files
diff --git a/src/typesense/async_synonym_set.py b/src/typesense/async_synonym_set.py
@@ -0,0 +1,102 @@
+"""Client for single Synonym Set operations (async)."""
+
+import sys
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+from typesense.async_api_call import AsyncApiCall
+from typesense.types.synonym_set import (
+    SynonymItemDeleteSchema,
+    SynonymItemSchema,
+    SynonymSetCreateSchema,
+    SynonymSetDeleteSchema,
+    SynonymSetRetrieveSchema,
+)
+
+
+class AsyncSynonymSet:
+    def __init__(self, api_call: AsyncApiCall, name: str) -> None:
+        self.api_call = api_call
+        self.name = name
+
+    @property
+    def _endpoint_path(self) -> str:
+        from typesense.async_synonym_sets import AsyncSynonymSets
+
+        return "/".join([AsyncSynonymSets.resource_path, self.name])
+
+    async def retrieve(self) -> SynonymSetRetrieveSchema:
+        response: SynonymSetRetrieveSchema = await self.api_call.get(
+            self._endpoint_path,
+            as_json=True,
+            entity_type=SynonymSetRetrieveSchema,
+        )
+        return response
+
+    async def upsert(self, set: SynonymSetCreateSchema) -> SynonymSetCreateSchema:
+        response: SynonymSetCreateSchema = await self.api_call.put(
+            self._endpoint_path,
+            entity_type=SynonymSetCreateSchema,
+            body=set,
+        )
+        return response
+
+    async def delete(self) -> SynonymSetDeleteSchema:
+        response: SynonymSetDeleteSchema = await self.api_call.delete(
+            self._endpoint_path,
+            entity_type=SynonymSetDeleteSchema,
+        )
+        return response
+
+    @property
+    def _items_path(self) -> str:
+        return "/".join([self._endpoint_path, "items"])  # /synonym_sets/{name}/items
+
+    async def list_items(
+        self,
+        *,
+        limit: typing.Union[int, None] = None,
+        offset: typing.Union[int, None] = None,
+    ) -> typing.List[SynonymItemSchema]:
+        params: typing.Dict[str, typing.Union[int, None]] = {
+            "limit": limit,
+            "offset": offset,
+        }
+        clean_params: typing.Dict[str, int] = {
+            k: v for k, v in params.items() if v is not None
+        }
+        response: typing.List[SynonymItemSchema] = await self.api_call.get(
+            self._items_path,
+            as_json=True,
+            entity_type=typing.List[SynonymItemSchema],
+            params=clean_params or None,
+        )
+        return response
+
+    async def get_item(self, item_id: str) -> SynonymItemSchema:
+        response: SynonymItemSchema = await self.api_call.get(
+            "/".join([self._items_path, item_id]),
+            as_json=True,
+            entity_type=SynonymItemSchema,
+        )
+        return response
+
+    async def upsert_item(
+        self, item_id: str, item: SynonymItemSchema
+    ) -> SynonymItemSchema:
+        response: SynonymItemSchema = await self.api_call.put(
+            "/".join([self._items_path, item_id]),
+            body=item,
+            entity_type=SynonymItemSchema,
+        )
+        return response
+
+    async def delete_item(self, item_id: str) -> SynonymItemDeleteSchema:
+        # API returns {"id": "..."} for delete; openapi defines SynonymItemDeleteResponse with name but for items it's id
+        response: SynonymItemDeleteSchema = await self.api_call.delete(
+            "/".join([self._items_path, item_id]), entity_type=SynonymItemDeleteSchema
+        )
+        return response
diff --git a/src/typesense/async_synonym_sets.py b/src/typesense/async_synonym_sets.py
@@ -0,0 +1,34 @@
+"""Client for Synonym Sets collection operations (async)."""
+
+import sys
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_synonym_set import AsyncSynonymSet
+from typesense.types.synonym_set import (
+    SynonymSetSchema,
+)
+
+
+class AsyncSynonymSets:
+    resource_path: typing.Final[str] = "/synonym_sets"
+
+    def __init__(self, api_call: AsyncApiCall) -> None:
+        self.api_call = api_call
+
+    async def retrieve(self) -> typing.List[SynonymSetSchema]:
+        response: typing.List[SynonymSetSchema] = await self.api_call.get(
+            AsyncSynonymSets.resource_path,
+            as_json=True,
+            entity_type=typing.List[SynonymSetSchema],
+        )
+        return response
+
+    def __getitem__(self, synonym_set_name: str) -> AsyncSynonymSet:
+        from typesense.async_synonym_set import AsyncSynonymSet as PerSet
+
+        return PerSet(self.api_call, synonym_set_name)
diff --git a/tests/fixtures/synonym_set_fixtures.py b/tests/fixtures/synonym_set_fixtures.py
@@ -4,6 +4,9 @@
 import requests
 
 from typesense.api_call import ApiCall
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_synonym_set import AsyncSynonymSet
+from typesense.async_synonym_sets import AsyncSynonymSets
 from typesense.synonym_set import SynonymSet
 from typesense.synonym_sets import SynonymSets
 
@@ -69,3 +72,31 @@ def fake_synonym_sets_fixture(fake_api_call: ApiCall) -> SynonymSets:
 def fake_synonym_set_fixture(fake_api_call: ApiCall) -> SynonymSet:
     """Return a SynonymSet object with test values."""
     return SynonymSet(fake_api_call, "test-set")
+
+
+@pytest.fixture(scope="function", name="actual_async_synonym_sets")
+def actual_async_synonym_sets_fixture(
+    actual_async_api_call: AsyncApiCall,
+) -> AsyncSynonymSets:
+    """Return a AsyncSynonymSets object using a real API."""
+    return AsyncSynonymSets(actual_async_api_call)
+
+
+@pytest.fixture(scope="function", name="actual_async_synonym_set")
+def actual_async_synonym_set_fixture(actual_async_api_call: AsyncApiCall) -> AsyncSynonymSet:
+    """Return a AsyncSynonymSet object using a real API."""
+    return AsyncSynonymSet(actual_async_api_call, "test-set")
+
+
+@pytest.fixture(scope="function", name="fake_async_synonym_sets")
+def fake_async_synonym_sets_fixture(
+    fake_async_api_call: AsyncApiCall,
+) -> AsyncSynonymSets:
+    """Return a AsyncSynonymSets object with test values."""
+    return AsyncSynonymSets(fake_async_api_call)
+
+
+@pytest.fixture(scope="function", name="fake_async_synonym_set")
+def fake_async_synonym_set_fixture(fake_async_api_call: AsyncApiCall) -> AsyncSynonymSet:
+    """Return a AsyncSynonymSet object with test values."""
+    return AsyncSynonymSet(fake_async_api_call, "test-set")
diff --git a/tests/synonym_set_items_test.py b/tests/synonym_set_items_test.py
@@ -5,6 +5,7 @@
 import pytest
 
 from tests.utils.version import is_v30_or_above
+from typesense.async_synonym_sets import AsyncSynonymSets
 from typesense.client import Client
 from typesense.synonym_sets import SynonymSets
 from typesense.types.synonym_set import (
@@ -83,3 +84,68 @@ def test_actual_delete_item(
     response = actual_synonym_sets["test-set"].delete_item("company_synonym")
 
     assert response == {"id": "company_synonym"}
+
+
+async def test_actual_list_items_async(
+    actual_async_synonym_sets: AsyncSynonymSets,
+    delete_all_synonym_sets: None,
+    create_synonym_set: None,
+) -> None:
+    """Test that the AsyncSynonymSet object can list items from Typesense Server."""
+    response = await actual_async_synonym_sets["test-set"].list_items()
+
+    assert response == [
+        {
+            "id": "company_synonym",
+            "root": "",
+            "synonyms": ["companies", "corporations", "firms"],
+        },
+    ]
+
+
+async def test_actual_get_item_async(
+    actual_async_synonym_sets: AsyncSynonymSets,
+    delete_all_synonym_sets: None,
+    create_synonym_set: None,
+) -> None:
+    """Test that the AsyncSynonymSet object can get a specific item from Typesense Server."""
+    response = await actual_async_synonym_sets["test-set"].get_item("company_synonym")
+
+    assert response == {
+        "id": "company_synonym",
+        "root": "",
+        "synonyms": ["companies", "corporations", "firms"],
+    }
+
+
+async def test_actual_upsert_item_async(
+    actual_async_synonym_sets: AsyncSynonymSets,
+    delete_all_synonym_sets: None,
+    create_synonym_set: None,
+) -> None:
+    """Test that the AsyncSynonymSet object can upsert an item in Typesense Server."""
+    payload: SynonymItemSchema = {
+        "id": "brand_synonym",
+        "synonyms": ["brand", "brands", "label"],
+    }
+    response = await actual_async_synonym_sets["test-set"].upsert_item(
+        "brand_synonym", payload
+    )
+
+    assert response == {
+        "id": "brand_synonym",
+        "synonyms": ["brand", "brands", "label"],
+    }
+
+
+async def test_actual_delete_item_async(
+    actual_async_synonym_sets: AsyncSynonymSets,
+    delete_all_synonym_sets: None,
+    create_synonym_set: None,
+) -> None:
+    """Test that the AsyncSynonymSet object can delete an item from Typesense Server."""
+    response = await actual_async_synonym_sets["test-set"].delete_item(
+        "company_synonym"
+    )
+
+    assert response == {"id": "company_synonym"}
diff --git a/tests/synonym_set_test.py b/tests/synonym_set_test.py
@@ -7,6 +7,8 @@
 from tests.utils.object_assertions import assert_match_object, assert_object_lists_match
 from tests.utils.version import is_v30_or_above
 from typesense.api_call import ApiCall
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_synonym_sets import AsyncSynonymSets
 from typesense.client import Client
 from typesense.synonym_set import SynonymSet
 from typesense.synonym_sets import SynonymSets
@@ -69,3 +71,52 @@ def test_actual_delete(
     response = actual_synonym_sets["test-set"].delete()
 
     assert response == {"name": "test-set"}
+
+
+def test_init_async(fake_async_api_call: AsyncApiCall) -> None:
+    """Test that the AsyncSynonymSet object is initialized correctly."""
+    from typesense.async_synonym_set import AsyncSynonymSet
+
+    synset = AsyncSynonymSet(fake_async_api_call, "test-set")
+
+    assert synset.name == "test-set"
+    assert_match_object(synset.api_call, fake_async_api_call)
+    assert_object_lists_match(
+        synset.api_call.node_manager.nodes,
+        fake_async_api_call.node_manager.nodes,
+    )
+    assert_match_object(
+        synset.api_call.config.nearest_node,
+        fake_async_api_call.config.nearest_node,
+    )
+    assert synset._endpoint_path == "/synonym_sets/test-set"  # noqa: WPS437
+
+
+async def test_actual_retrieve_async(
+    actual_async_synonym_sets: AsyncSynonymSets,
+    delete_all_synonym_sets: None,
+    create_synonym_set: None,
+) -> None:
+    """Test that the AsyncSynonymSet object can retrieve a synonym set from Typesense Server."""
+    response = await actual_async_synonym_sets["test-set"].retrieve()
+
+    assert response == {
+        "name": "test-set",
+        "items": [
+            {
+                "id": "company_synonym",
+                "root": "",
+                "synonyms": ["companies", "corporations", "firms"],
+            }
+        ],
+    }
+
+
+async def test_actual_delete_async(
+    actual_async_synonym_sets: AsyncSynonymSets,
+    create_synonym_set: None,
+) -> None:
+    """Test that the AsyncSynonymSet object can delete a synonym set from Typesense Server."""
+    response = await actual_async_synonym_sets["test-set"].delete()
+
+    assert response == {"name": "test-set"}
diff --git a/tests/synonym_sets_test.py b/tests/synonym_sets_test.py
