feat(stopwords): add async support for stopwords operations

- add AsyncStopwords class for async stopwords collection operations
- add AsyncStopwordsSet class for async individual stopwords set operations
- add async tests for stopwords and stopwords set functionality
- add async fixtures for testing async stopwords operations

Author: tharropoulos

src/typesense/async_stopwords.py

@@ -0,0 +1,117 @@
+"""
+This module provides async functionality for managing stopwords in Typesense.
+
+Classes:
+    - AsyncStopwords: Handles async operations related to stopwords and stopword sets.
+
+Methods:
+    - __init__: Initializes the AsyncStopwords object.
+    - __getitem__: Retrieves or creates an AsyncStopwordsSet object for a given stopwords_set_id.
+    - upsert: Creates or updates a stopwords set.
+    - retrieve: Retrieves all stopwords sets.
+
+Attributes:
+    - RESOURCE_PATH: The API resource path for stopwords operations.
+
+The AsyncStopwords class interacts with the Typesense API to manage stopwords operations.
+It provides methods to create, update, and retrieve stopwords sets, as well as access
+individual AsyncStopwordsSet objects.
+
+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
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_stopwords_set import AsyncStopwordsSet
+from typesense.types.stopword import (
+    StopwordCreateSchema,
+    StopwordSchema,
+    StopwordsRetrieveSchema,
+)
+
+
+class AsyncStopwords:
+    """
+    Class for managing stopwords in Typesense (async).
+
+    This class provides methods to interact with stopwords and stopwords sets, including
+    creating, updating, retrieving, and accessing individual stopwords sets.
+
+    Attributes:
+        RESOURCE_PATH (str): The API resource path for stopwords operations.
+        api_call (AsyncApiCall): The API call object for making requests.
+        stopwords_sets (Dict[str, AsyncStopwordsSet]): A dictionary of AsyncStopwordsSet objects.
+    """
+
+    resource_path: typing.Final[str] = "/stopwords"
+
+    def __init__(self, api_call: AsyncApiCall):
+        """
+        Initialize the AsyncStopwords object.
+
+        Args:
+            api_call (AsyncApiCall): The API call object for making requests.
+        """
+        self.api_call = api_call
+        self.stopwords_sets: typing.Dict[str, AsyncStopwordsSet] = {}
+
+    def __getitem__(self, stopwords_set_id: str) -> AsyncStopwordsSet:
+        """
+        Get or create an AsyncStopwordsSet object for a given stopwords_set_id.
+
+        Args:
+            stopwords_set_id (str): The ID of the stopwords set.
+
+        Returns:
+            AsyncStopwordsSet: The AsyncStopwordsSet object for the given ID.
+        """
+        if not self.stopwords_sets.get(stopwords_set_id):
+            self.stopwords_sets[stopwords_set_id] = AsyncStopwordsSet(
+                self.api_call,
+                stopwords_set_id,
+            )
+        return self.stopwords_sets[stopwords_set_id]
+
+    async def upsert(
+        self,
+        stopwords_set_id: str,
+        stopwords_set: StopwordCreateSchema,
+    ) -> StopwordSchema:
+        """
+        Create or update a stopwords set.
+
+        Args:
+            stopwords_set_id (str): The ID of the stopwords set to upsert.
+            stopwords_set (StopwordCreateSchema):
+                The schema for creating or updating the stopwords set.
+
+        Returns:
+            StopwordSchema: The created or updated stopwords set.
+        """
+        response: StopwordSchema = await self.api_call.put(
+            "/".join([AsyncStopwords.resource_path, stopwords_set_id]),
+            body=stopwords_set,
+            entity_type=StopwordSchema,
+        )
+        return response
+
+    async def retrieve(self) -> StopwordsRetrieveSchema:
+        """
+        Retrieve all stopwords sets.
+
+        Returns:
+            StopwordsRetrieveSchema: The schema containing all stopwords sets.
+        """
+        response: StopwordsRetrieveSchema = await self.api_call.get(
+            AsyncStopwords.resource_path,
+            as_json=True,
+            entity_type=StopwordsRetrieveSchema,
+        )
+        return response

src/typesense/async_stopwords_set.py

@@ -0,0 +1,87 @@
+"""
+This module provides async functionality for managing individual stopwords sets in Typesense.
+
+Classes:
+    - AsyncStopwordsSet: Handles async operations related to a specific stopwords set.
+
+Methods:
+    - __init__: Initializes the AsyncStopwordsSet object.
+    - retrieve: Retrieves the details of this specific stopwords set.
+    - delete: Deletes this specific stopwords set.
+    - _endpoint_path: Constructs the API endpoint path for this specific stopwords set.
+
+The AsyncStopwordsSet class interacts with the Typesense API to manage operations on a
+specific stopwords set. It provides methods to retrieve and delete individual stopwords sets.
+
+For more information regarding Stopwords, refer to the Stopwords [documentation]
+(https://typesense.org/docs/27.0/api/stopwords.html).
+
+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.types.stopword import StopwordDeleteSchema, StopwordsSingleRetrieveSchema
+
+
+class AsyncStopwordsSet:
+    """
+    Class for managing individual stopwords sets in Typesense (async).
+
+    This class provides methods to interact with a specific stopwords set,
+    including retrieving and deleting it.
+
+    Attributes:
+        stopwords_set_id (str): The ID of the stopwords set.
+        api_call (AsyncApiCall): The API call object for making requests.
+    """
+
+    def __init__(self, api_call: AsyncApiCall, stopwords_set_id: str) -> None:
+        """
+        Initialize the AsyncStopwordsSet object.
+
+        Args:
+            api_call (AsyncApiCall): The API call object for making requests.
+            stopwords_set_id (str): The ID of the stopwords set.
+        """
+        self.stopwords_set_id = stopwords_set_id
+        self.api_call = api_call
+
+    async def retrieve(self) -> StopwordsSingleRetrieveSchema:
+        """
+        Retrieve this specific stopwords set.
+
+        Returns:
+            StopwordsSingleRetrieveSchema: The schema containing the stopwords set details.
+        """
+        response: StopwordsSingleRetrieveSchema = await self.api_call.get(
+            self._endpoint_path,
+            entity_type=StopwordsSingleRetrieveSchema,
+            as_json=True,
+        )
+        return response
+
+    async def delete(self) -> StopwordDeleteSchema:
+        """
+        Delete this specific stopwords set.
+
+        Returns:
+            StopwordDeleteSchema: The schema containing the deletion response.
+        """
+        response: StopwordDeleteSchema = await self.api_call.delete(
+            self._endpoint_path,
+            entity_type=StopwordDeleteSchema,
+        )
+        return response
+
+    @property
+    def _endpoint_path(self) -> str:
+        """
+        Construct the API endpoint path for this specific stopwords set.
+
+        Returns:
+            str: The constructed endpoint path.
+        """
+        from typesense.async_stopwords import AsyncStopwords
+
+        return "/".join([AsyncStopwords.resource_path, self.stopwords_set_id])

tests/fixtures/stopword_fixtures.py

@@ -4,6 +4,9 @@
 import requests
 
 from typesense.api_call import ApiCall
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_stopwords import AsyncStopwords
+from typesense.async_stopwords_set import AsyncStopwordsSet
 from typesense.stopwords import Stopwords
 from typesense.stopwords_set import StopwordsSet
 
@@ -67,3 +70,27 @@ def fake_stopwords_fixture(fake_api_call: ApiCall) -> Stopwords:
 def fake_stopwords_set_fixture(fake_api_call: ApiCall) -> StopwordsSet:
     """Return a Collection object with test values."""
     return StopwordsSet(fake_api_call, "company_stopwords")
+
+
+@pytest.fixture(scope="function", name="actual_async_stopwords")
+def actual_async_stopwords_fixture(actual_async_api_call: AsyncApiCall) -> AsyncStopwords:
+    """Return a AsyncStopwords object using a real API."""
+    return AsyncStopwords(actual_async_api_call)
+
+
+@pytest.fixture(scope="function", name="actual_async_stopwords_set")
+def actual_async_stopwords_set_fixture(actual_async_api_call: AsyncApiCall) -> AsyncStopwordsSet:
+    """Return a AsyncStopwordsSet object using a real API."""
+    return AsyncStopwordsSet(actual_async_api_call, "company_stopwords")
+
+
+@pytest.fixture(scope="function", name="fake_async_stopwords")
+def fake_async_stopwords_fixture(fake_async_api_call: AsyncApiCall) -> AsyncStopwords:
+    """Return a AsyncStopwords object with test values."""
+    return AsyncStopwords(fake_async_api_call)
+
+
+@pytest.fixture(scope="function", name="fake_async_stopwords_set")
+def fake_async_stopwords_set_fixture(fake_async_api_call: AsyncApiCall) -> AsyncStopwordsSet:
+    """Return a AsyncStopwordsSet object with test values."""
+    return AsyncStopwordsSet(fake_async_api_call, "company_stopwords")

tests/stopwords_set_test.py

@@ -1,9 +1,9 @@
 """Tests for the StopwordsSet class."""
 
-
-
 from tests.utils.object_assertions import assert_match_object, assert_object_lists_match
 from typesense.api_call import ApiCall
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_stopwords import AsyncStopwords
 from typesense.stopwords import Stopwords
 from typesense.stopwords_set import StopwordsSet
 from typesense.types.stopword import StopwordDeleteSchema, StopwordSchema
@@ -51,3 +51,49 @@ def test_actual_delete(
     response = actual_stopwords["company_stopwords"].delete()
 
     assert response == {"id": "company_stopwords"}
+
+
+def test_init_async(fake_async_api_call: AsyncApiCall) -> None:
+    """Test that the AsyncStopwordsSet object is initialized correctly."""
+    from typesense.async_stopwords_set import AsyncStopwordsSet
+
+    stopword_set = AsyncStopwordsSet(fake_async_api_call, "company_stopwords")
+
+    assert stopword_set.stopwords_set_id == "company_stopwords"
+    assert_match_object(stopword_set.api_call, fake_async_api_call)
+    assert_object_lists_match(
+        stopword_set.api_call.node_manager.nodes,
+        fake_async_api_call.node_manager.nodes,
+    )
+    assert_match_object(
+        stopword_set.api_call.config.nearest_node,
+        fake_async_api_call.config.nearest_node,
+    )
+    assert stopword_set._endpoint_path == "/stopwords/company_stopwords"  # noqa: WPS437
+
+
+async def test_actual_retrieve_async(
+    actual_async_stopwords: AsyncStopwords,
+    delete_all_stopwords: None,
+    delete_all: None,
+    create_stopword: None,
+) -> None:
+    """Test that the AsyncStopwordsSet object can retrieve an stopword_set from Typesense Server."""
+    response = await actual_async_stopwords["company_stopwords"].retrieve()
+
+    assert response == {
+        "stopwords": {
+            "id": "company_stopwords",
+            "stopwords": ["and", "is", "the"],
+        },
+    }
+
+
+async def test_actual_delete_async(
+    actual_async_stopwords: AsyncStopwords,
+    create_stopword: None,
+) -> None:
+    """Test that the AsyncStopwordsSet object can delete an stopword_set from Typesense Server."""
+    response = await actual_async_stopwords["company_stopwords"].delete()
+
+    assert response == {"id": "company_stopwords"}