feat(synonyms): add async support for synonym operations

tharropoulos · tharropoulos · commit 0487a9a3c0df · 2025-12-09T11:06:12.000+02:00
- add AsyncSynonym class for async individual synonym operations
- add AsyncSynonyms class for async synonyms collection operations
- add async tests for synonym and synonyms functionality
- add async fixtures for testing async synonym operations
- remove future annotations imports from test files
diff --git a/src/typesense/async_synonym.py b/src/typesense/async_synonym.py
@@ -0,0 +1,104 @@
+"""
+This module provides async functionality for managing individual synonyms in Typesense.
+
+Classes:
+    - AsyncSynonym: Handles async operations related to a specific synonym within a collection.
+
+Methods:
+    - __init__: Initializes the AsyncSynonym object.
+    - _endpoint_path: Constructs the API endpoint path for this specific synonym.
+    - retrieve: Retrieves the details of this specific synonym.
+    - delete: Deletes this specific synonym.
+
+The AsyncSynonym class interacts with the Typesense API to manage operations on a
+specific synonym within a collection. It provides methods to retrieve and delete
+individual synonyms.
+
+For more information regarding Synonyms, refer to the Synonyms [documentation]
+(https://typesense.org/docs/27.0/api/synonyms.html#synonyms).
+
+This module uses type hinting and is compatible with Python 3.11+ as well as earlier
+versions through the use of the typing_extensions library.
+"""
+
+from typesense.async_api_call import AsyncApiCall
+from typesense.logger import warn_deprecation
+from typesense.types.synonym import SynonymDeleteSchema, SynonymSchema
+
+
+class AsyncSynonym:
+    """
+    Class for managing individual synonyms in a Typesense collection (async).
+
+    This class provides methods to interact with a specific synonym,
+    including retrieving and deleting it.
+
+    Attributes:
+        api_call (AsyncApiCall): The API call object for making requests.
+        collection_name (str): The name of the collection.
+        synonym_id (str): The ID of the synonym.
+    """
+
+    def __init__(
+        self,
+        api_call: AsyncApiCall,
+        collection_name: str,
+        synonym_id: str,
+    ) -> None:
+        """
+        Initialize the AsyncSynonym object.
+
+        Args:
+            api_call (AsyncApiCall): The API call object for making requests.
+            collection_name (str): The name of the collection.
+            synonym_id (str): The ID of the synonym.
+        """
+        self.api_call = api_call
+        self.collection_name = collection_name
+        self.synonym_id = synonym_id
+
+    async def retrieve(self) -> SynonymSchema:
+        """
+        Retrieve this specific synonym.
+
+        Returns:
+            SynonymSchema: The schema containing the synonym details.
+        """
+        return await self.api_call.get(self._endpoint_path, entity_type=SynonymSchema)
+
+    async def delete(self) -> SynonymDeleteSchema:
+        """
+        Delete this specific synonym.
+
+        Returns:
+            SynonymDeleteSchema: The schema containing the deletion response.
+        """
+        return await self.api_call.delete(
+            self._endpoint_path,
+            entity_type=SynonymDeleteSchema,
+        )
+
+    @property
+    @warn_deprecation(  # type: ignore[untyped-decorator]
+        "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 _endpoint_path(self) -> str:
+        """
+        Construct the API endpoint path for this specific synonym.
+
+        Returns:
+            str: The constructed endpoint path.
+        """
+        from typesense.async_collections import AsyncCollections
+        from typesense.async_synonyms import AsyncSynonyms
+
+        return "/".join(
+            [
+                AsyncCollections.resource_path,
+                self.collection_name,
+                AsyncSynonyms.resource_path,
+                self.synonym_id,
+            ],
+        )
diff --git a/src/typesense/async_synonyms.py b/src/typesense/async_synonyms.py
@@ -0,0 +1,152 @@
+"""
+This module provides async functionality for managing synonyms in Typesense.
+
+Classes:
+    - AsyncSynonyms: Handles async operations related to synonyms within a collection.
+
+Methods:
+    - __init__: Initializes the AsyncSynonyms object.
+    - __getitem__: Retrieves or creates an AsyncSynonym object for a given synonym_id.
+    - _endpoint_path: Constructs the API endpoint path for synonym operations.
+    - upsert: Creates or updates a synonym.
+    - retrieve: Retrieves all synonyms for the collection.
+
+Attributes:
+    - RESOURCE_PATH: The API resource path for synonyms.
+
+The AsyncSynonyms class interacts with the Typesense API to manage synonym operations
+within a specific collection. It provides methods to create, update, and retrieve
+synonyms, as well as access individual AsyncSynonym objects.
+
+For more information regarding Synonyms, refer to the Synonyms [documentation]
+(https://typesense.org/docs/27.0/api/synonyms.html#synonyms).
+
+This module uses type hinting and is compatible with Python 3.11+ as well as earlier
+versions through the use of the typing_extensions library.
+"""
+
+import sys
+
+from typing_extensions import deprecated
+
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_synonym import AsyncSynonym
+from typesense.logger import warn_deprecation
+from typesense.types.synonym import (
+    SynonymCreateSchema,
+    SynonymSchema,
+    SynonymsRetrieveSchema,
+)
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+
+@deprecated("AsyncSynonyms is deprecated on v30+. Use client.synonym_sets instead.")
+class AsyncSynonyms:
+    """
+    Class for managing synonyms in a Typesense collection (async).
+
+    This class provides methods to interact with synonyms, including
+    retrieving, creating, and updating them.
+
+    Attributes:
+        RESOURCE_PATH (str): The API resource path for synonyms.
+        api_call (AsyncApiCall): The API call object for making requests.
+        collection_name (str): The name of the collection.
+        synonyms (Dict[str, AsyncSynonym]): A dictionary of AsyncSynonym objects.
+    """
+
+    resource_path: typing.Final[str] = "synonyms"
+
+    def __init__(self, api_call: AsyncApiCall, collection_name: str) -> None:
+        """
+        Initialize the AsyncSynonyms object.
+
+        Args:
+            api_call (AsyncApiCall): The API call object for making requests.
+            collection_name (str): The name of the collection.
+        """
+        self.api_call = api_call
+        self.collection_name = collection_name
+        self.synonyms: typing.Dict[str, AsyncSynonym] = {}
+
+    def __getitem__(self, synonym_id: str) -> AsyncSynonym:
+        """
+        Get or create an AsyncSynonym object for a given synonym_id.
+
+        Args:
+            synonym_id (str): The ID of the synonym.
+
+        Returns:
+            AsyncSynonym: The AsyncSynonym object for the given ID.
+        """
+        if not self.synonyms.get(synonym_id):
+            self.synonyms[synonym_id] = AsyncSynonym(
+                self.api_call,
+                self.collection_name,
+                synonym_id,
+            )
+        return self.synonyms[synonym_id]
+
+    async def upsert(
+        self, synonym_id: str, schema: SynonymCreateSchema
+    ) -> SynonymSchema:
+        """
+        Create or update a synonym.
+
+        Args:
+            id (str): The ID of the synonym.
+            schema (SynonymCreateSchema): The schema for creating or updating the synonym.
+
+        Returns:
+            SynonymSchema: The created or updated synonym.
+        """
+        response = await self.api_call.put(
+            self._endpoint_path(synonym_id),
+            body=schema,
+            entity_type=SynonymSchema,
+        )
+        return response
+
+    async def retrieve(self) -> SynonymsRetrieveSchema:
+        """
+        Retrieve all synonyms for the collection.
+
+        Returns:
+            SynonymsRetrieveSchema: The schema containing all synonyms.
+        """
+        response = await self.api_call.get(
+            self._endpoint_path(),
+            entity_type=SynonymsRetrieveSchema,
+        )
+        return response
+
+    @warn_deprecation(  # type: ignore[untyped-decorator]
+        "The synonyms API (collections/{collection}/synonyms) is deprecated is removed on v30+. "
+        "Use synonym sets (synonym_sets) instead.",
+        flag_name="synonyms_deprecation",
+    )
+    def _endpoint_path(self, synonym_id: typing.Union[str, None] = None) -> str:
+        """
+        Construct the API endpoint path for synonym operations.
+
+        Args:
+            synonym_id (Union[str, None], optional): The ID of the synonym. Defaults to None.
+
+        Returns:
+            str: The constructed endpoint path.
+        """
+        from typesense.async_collections import AsyncCollections
+
+        synonym_id = synonym_id or ""
+        return "/".join(
+            [
+                AsyncCollections.resource_path,
+                self.collection_name,
+                AsyncSynonyms.resource_path,
+                synonym_id,
+            ],
+        )
diff --git a/tests/fixtures/synonym_fixtures.py b/tests/fixtures/synonym_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 import AsyncSynonym
+from typesense.async_synonyms import AsyncSynonyms
 from typesense.synonym import Synonym
 from typesense.synonyms import Synonyms
 
@@ -42,3 +45,25 @@ def actual_synonyms_fixture(actual_api_call: ApiCall) -> Synonyms:
 def fake_synonym_fixture(fake_api_call: ApiCall) -> Synonym:
     """Return a Synonym object with test values."""
     return Synonym(fake_api_call, "companies", "company_synonym")
+
+
+@pytest.fixture(scope="function", name="actual_async_synonyms")
+def actual_async_synonyms_fixture(
+    actual_async_api_call: AsyncApiCall,
+) -> AsyncSynonyms:
+    """Return a AsyncSynonyms object using a real API."""
+    return AsyncSynonyms(actual_async_api_call, "companies")
+
+
+@pytest.fixture(scope="function", name="fake_async_synonyms")
+def fake_async_synonyms_fixture(
+    fake_async_api_call: AsyncApiCall,
+) -> AsyncSynonyms:
+    """Return a AsyncSynonyms object with test values."""
+    return AsyncSynonyms(fake_async_api_call, "companies")
+
+
+@pytest.fixture(scope="function", name="fake_async_synonym")
+def fake_async_synonym_fixture(fake_async_api_call: AsyncApiCall) -> AsyncSynonym:
+    """Return a AsyncSynonym object with test values."""
+    return AsyncSynonym(fake_async_api_call, "companies", "company_synonym")
diff --git a/tests/synonym_test.py b/tests/synonym_test.py
@@ -1,7 +1,5 @@
 """Tests for the Synonym class."""
 
-from __future__ import annotations
-
 import pytest
 
 from tests.utils.object_assertions import (
@@ -11,8 +9,11 @@
 )
 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_collections import AsyncCollections
 from typesense.collections import Collections
 from typesense.client import Client
+from typesense.synonym import Synonym
 
 
 pytestmark = pytest.mark.skipif(
@@ -78,3 +79,63 @@ def test_actual_delete(
     response = actual_collections["companies"].synonyms["company_synonym"].delete()
 
     assert response == {"id": "company_synonym"}
+
+
+def test_init_async(fake_async_api_call: AsyncApiCall) -> None:
+    """Test that the AsyncSynonym object is initialized correctly."""
+    from typesense.async_synonym import AsyncSynonym
+
+    synonym = AsyncSynonym(fake_async_api_call, "companies", "company_synonym")
+
+    assert synonym.collection_name == "companies"
+    assert synonym.synonym_id == "company_synonym"
+    assert_match_object(synonym.api_call, fake_async_api_call)
+    assert_object_lists_match(
+        synonym.api_call.node_manager.nodes,
+        fake_async_api_call.node_manager.nodes,
+    )
+    assert_match_object(
+        synonym.api_call.config.nearest_node,
+        fake_async_api_call.config.nearest_node,
+    )
+    assert (
+        synonym._endpoint_path()  # noqa: WPS437
+        == "/collections/companies/synonyms/company_synonym"
+    )
+
+
+async def test_actual_retrieve_async(
+    actual_async_collections: AsyncCollections,
+    delete_all: None,
+    create_synonym: None,
+) -> None:
+    """Test that the AsyncSynonym object can retrieve an synonym from Typesense Server."""
+    response = (
+        await actual_async_collections["companies"]
+        .synonyms["company_synonym"]
+        .retrieve()
+    )
+
+    assert response["id"] == "company_synonym"
+
+    assert response["synonyms"] == ["companies", "corporations", "firms"]
+    assert_to_contain_object(
+        response,
+        {
+            "id": "company_synonym",
+            "synonyms": ["companies", "corporations", "firms"],
+        },
+    )
+
+
+async def test_actual_delete_async(
+    actual_async_collections: AsyncCollections,
+    delete_all: None,
+    create_synonym: None,
+) -> None:
+    """Test that the AsyncSynonym object can delete an synonym from Typesense Server."""
+    response = (
+        await actual_async_collections["companies"].synonyms["company_synonym"].delete()
+    )
+
+    assert response == {"id": "company_synonym"}
diff --git a/tests/synonyms_test.py b/tests/synonyms_test.py
