feat(overrides): add async support for override operations

tharropoulos · tharropoulos · commit fc0f2055d2f5 · 2025-12-09T11:06:01.000+02:00
- add AsyncOverride class for async individual override operations
- add AsyncOverrides class for async overrides collection operations
- add async tests for override and overrides functionality
- add async fixtures for testing async override operations
diff --git a/src/typesense/async_override.py b/src/typesense/async_override.py
@@ -0,0 +1,112 @@
+"""
+This module provides async functionality for managing individual overrides in Typesense.
+
+Classes:
+    - AsyncOverride: Handles async operations related to a specific override within a collection.
+
+Methods:
+    - __init__: Initializes the AsyncOverride object.
+    - retrieve: Retrieves the details of this specific override.
+    - delete: Deletes this specific override.
+
+Attributes:
+    - _endpoint_path: The API endpoint path for this specific override.
+
+The AsyncOverride class interacts with the Typesense API to manage operations on a
+specific override within a collection. It provides methods to retrieve and delete
+individual overrides.
+
+For more information regarding Overrides, refer to the Curation [documentation]
+(https://typesense.org/docs/27.0/api/curation.html#curation).
+
+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.override import OverrideDeleteSchema, OverrideSchema
+
+
+class AsyncOverride:
+    """
+    Class for managing individual overrides in a Typesense collection (async).
+
+    This class provides methods to interact with a specific override,
+    including retrieving and deleting it.
+
+    Attributes:
+        api_call (AsyncApiCall): The API call object for making requests.
+        collection_name (str): The name of the collection.
+        override_id (str): The ID of the override.
+    """
+
+    def __init__(
+        self,
+        api_call: AsyncApiCall,
+        collection_name: str,
+        override_id: str,
+    ) -> None:
+        """
+        Initialize the AsyncOverride object.
+
+        Args:
+            api_call (AsyncApiCall): The API call object for making requests.
+            collection_name (str): The name of the collection.
+            override_id (str): The ID of the override.
+        """
+        self.api_call = api_call
+        self.collection_name = collection_name
+        self.override_id = override_id
+
+    async def retrieve(self) -> OverrideSchema:
+        """
+        Retrieve this specific override.
+
+        Returns:
+            OverrideSchema: The schema containing the override details.
+        """
+        response: OverrideSchema = await self.api_call.get(
+            self._endpoint_path,
+            entity_type=OverrideSchema,
+            as_json=True,
+        )
+        return response
+
+    async def delete(self) -> OverrideDeleteSchema:
+        """
+        Delete this specific override.
+
+        Returns:
+            OverrideDeleteSchema: The schema containing the deletion response.
+        """
+        response: OverrideDeleteSchema = await self.api_call.delete(
+            self._endpoint_path,
+            entity_type=OverrideDeleteSchema,
+        )
+        return response
+
+    @property
+    @warn_deprecation(  # type: ignore[untyped-decorator]
+        "The override API (collections/{collection}/overrides/{override_id}) is deprecated is removed on v30+. "
+        "Use curation sets (curation_sets) instead.",
+        flag_name="overrides_deprecation",
+    )
+    def _endpoint_path(self) -> str:
+        """
+        Construct the API endpoint path for this specific override.
+
+        Returns:
+            str: The constructed endpoint path.
+        """
+        from typesense.async_collections import AsyncCollections
+        from typesense.async_overrides import AsyncOverrides
+
+        return "/".join(
+            [
+                AsyncCollections.resource_path,
+                self.collection_name,
+                AsyncOverrides.resource_path,
+                self.override_id,
+            ],
+        )
diff --git a/src/typesense/async_overrides.py b/src/typesense/async_overrides.py
@@ -0,0 +1,157 @@
+"""
+This module provides async functionality for managing overrides in Typesense.
+
+Classes:
+    - AsyncOverrides: Handles async operations related to overrides within a collection.
+
+Methods:
+    - __init__: Initializes the AsyncOverrides object.
+    - __getitem__: Retrieves or creates an AsyncOverride object for a given override_id.
+    - _endpoint_path: Constructs the API endpoint path for override operations.
+    - upsert: Creates or updates an override.
+    - retrieve: Retrieves all overrides for the collection.
+
+Attributes:
+    - RESOURCE_PATH: The API resource path for overrides.
+
+The AsyncOverrides class interacts with the Typesense API to manage override operations
+within a specific collection. It provides methods to create, update, and retrieve
+overrides, as well as access individual AsyncOverride objects.
+
+For more information regarding Overrides, refer to the Curation [documentation]
+(https://typesense.org/docs/27.0/api/curation.html#curation).
+
+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_override import AsyncOverride
+from typesense.logger import warn_deprecation
+from typesense.types.override import (
+    OverrideCreateSchema,
+    OverrideRetrieveSchema,
+    OverrideSchema,
+)
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+
+@deprecated("AsyncOverrides is deprecated on v30+. Use client.curation_sets instead.")
+class AsyncOverrides:
+    """
+    Class for managing overrides in a Typesense collection (async).
+
+    This class provides methods to interact with overrides, including
+    retrieving, creating, and updating them.
+
+    Attributes:
+        RESOURCE_PATH (str): The API resource path for overrides.
+        api_call (AsyncApiCall): The API call object for making requests.
+        collection_name (str): The name of the collection.
+        overrides (Dict[str, AsyncOverride]): A dictionary of AsyncOverride objects.
+    """
+
+    resource_path: typing.Final[str] = "overrides"
+
+    def __init__(
+        self,
+        api_call: AsyncApiCall,
+        collection_name: str,
+    ) -> None:
+        """
+        Initialize the AsyncOverrides 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.overrides: typing.Dict[str, AsyncOverride] = {}
+
+    def __getitem__(self, override_id: str) -> AsyncOverride:
+        """
+        Get or create an AsyncOverride object for a given override_id.
+
+        Args:
+            override_id (str): The ID of the override.
+
+        Returns:
+            AsyncOverride: The AsyncOverride object for the given ID.
+        """
+        if not self.overrides.get(override_id):
+            self.overrides[override_id] = AsyncOverride(
+                self.api_call,
+                self.collection_name,
+                override_id,
+            )
+        return self.overrides[override_id]
+
+    async def upsert(
+        self, override_id: str, schema: OverrideCreateSchema
+    ) -> OverrideSchema:
+        """
+        Create or update an override.
+
+        Args:
+            id (str): The ID of the override.
+            schema (OverrideCreateSchema): The schema for creating or updating the override.
+
+        Returns:
+            OverrideSchema: The created or updated override.
+        """
+        response: OverrideSchema = await self.api_call.put(
+            endpoint=self._endpoint_path(override_id),
+            entity_type=OverrideSchema,
+            body=schema,
+        )
+        return response
+
+    async def retrieve(self) -> OverrideRetrieveSchema:
+        """
+        Retrieve all overrides for the collection.
+
+        Returns:
+            OverrideRetrieveSchema: The schema containing all overrides.
+        """
+        response: OverrideRetrieveSchema = await self.api_call.get(
+            self._endpoint_path(),
+            entity_type=OverrideRetrieveSchema,
+            as_json=True,
+        )
+        return response
+
+    @warn_deprecation(  # type: ignore[untyped-decorator]
+        "AsyncOverrides is deprecated on v30+. Use client.curation_sets instead.",
+        flag_name="overrides_deprecation",
+    )
+    def _endpoint_path(self, override_id: typing.Union[str, None] = None) -> str:
+        """
+        Construct the API endpoint path for override operations.
+
+        Args:
+            override_id (Union[str, None], optional): The ID of the override. Defaults to None.
+
+        Returns:
+            str: The constructed endpoint path.
+        """
+        from typesense.async_collections import AsyncCollections
+
+        override_id = override_id or ""
+
+        return "/".join(
+            [
+                AsyncCollections.resource_path,
+                self.collection_name,
+                AsyncOverrides.resource_path,
+                override_id,
+            ],
+        )
diff --git a/tests/fixtures/override_fixtures.py b/tests/fixtures/override_fixtures.py
@@ -4,6 +4,9 @@
 import requests
 
 from typesense.api_call import ApiCall
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_override import AsyncOverride
+from typesense.async_overrides import AsyncOverrides
 from typesense.override import Override
 from typesense.overrides import Overrides
 
@@ -38,3 +41,25 @@ def fake_overrides_fixture(fake_api_call: ApiCall) -> Overrides:
 def fake_override_fixture(fake_api_call: ApiCall) -> Override:
     """Return a Override object with test values."""
     return Override(fake_api_call, "companies", "company_override")
+
+
+@pytest.fixture(scope="function", name="actual_async_overrides")
+def actual_async_overrides_fixture(
+    actual_async_api_call: AsyncApiCall,
+) -> AsyncOverrides:
+    """Return a AsyncOverrides object using a real API."""
+    return AsyncOverrides(actual_async_api_call, "companies")
+
+
+@pytest.fixture(scope="function", name="fake_async_overrides")
+def fake_async_overrides_fixture(
+    fake_async_api_call: AsyncApiCall,
+) -> AsyncOverrides:
+    """Return a AsyncOverrides object with test values."""
+    return AsyncOverrides(fake_async_api_call, "companies")
+
+
+@pytest.fixture(scope="function", name="fake_async_override")
+def fake_async_override_fixture(fake_async_api_call: AsyncApiCall) -> AsyncOverride:
+    """Return a AsyncOverride object with test values."""
+    return AsyncOverride(fake_async_api_call, "companies", "company_override")
diff --git a/tests/override_test.py b/tests/override_test.py
@@ -10,6 +10,9 @@
     assert_to_contain_object,
 )
 from typesense.api_call import ApiCall
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_collections import AsyncCollections
+from typesense.async_override import AsyncOverride
 from typesense.collections import Collections
 from typesense.override import Override, OverrideDeleteSchema
 from typesense.types.override import OverrideSchema
@@ -85,3 +88,60 @@ def test_actual_delete(
     response = actual_collections["companies"].overrides["company_override"].delete()
 
     assert response == {"id": "company_override"}
+
+
+def test_init_async(fake_async_api_call: AsyncApiCall) -> None:
+    """Test that the AsyncOverride object is initialized correctly."""
+    override = AsyncOverride(fake_async_api_call, "companies", "company_override")
+
+    assert override.collection_name == "companies"
+    assert override.override_id == "company_override"
+    assert_match_object(override.api_call, fake_async_api_call)
+    assert_object_lists_match(
+        override.api_call.node_manager.nodes,
+        fake_async_api_call.node_manager.nodes,
+    )
+    assert_match_object(
+        override.api_call.config.nearest_node,
+        fake_async_api_call.config.nearest_node,
+    )
+    assert (
+        override._endpoint_path()  # noqa: WPS437
+        == "/collections/companies/overrides/company_override"
+    )
+
+
+async def test_actual_retrieve_async(
+    actual_async_collections: AsyncCollections,
+    delete_all: None,
+    create_override: None,
+) -> None:
+    """Test that the AsyncOverride object can retrieve an override from Typesense Server."""
+    response = await actual_async_collections["companies"].overrides["company_override"].retrieve()
+
+    assert response["rule"] == {
+        "match": "exact",
+        "query": "companies",
+    }
+    assert response["filter_by"] == "num_employees>10"
+    assert_to_contain_object(
+        response,
+        {
+            "rule": {
+                "match": "exact",
+                "query": "companies",
+            },
+            "filter_by": "num_employees>10",
+        },
+    )
+
+
+async def test_actual_delete_async(
+    actual_async_collections: AsyncCollections,
+    delete_all: None,
+    create_override: None,
+) -> None:
+    """Test that the AsyncOverride object can delete an override from Typesense Server."""
+    response = await actual_async_collections["companies"].overrides["company_override"].delete()
+
+    assert response == {"id": "company_override"}
diff --git a/tests/overrides_test.py b/tests/overrides_test.py
