feat(alias): add async support for alias operations

- add asyncalias class for async individual alias operations
- add asyncaliases class for async alias collection operations
- add async tests for alias and aliases functionality
- add async fixtures for testing async alias operations
- remove future annotations imports from test files

Author: tharropoulos

src/typesense/async_alias.py

@@ -0,0 +1,80 @@
+"""
+This module provides async functionality for managing individual aliases in Typesense.
+
+It contains the AsyncAlias class, which allows for retrieving and deleting
+aliases asynchronously.
+
+Classes:
+    AsyncAlias: Manages async operations on a single alias in the Typesense API.
+
+Dependencies:
+    - typesense.async_api_call: Provides the AsyncApiCall class for making async API requests.
+    - typesense.types.alias: Provides AliasSchema type.
+
+Note: This module uses conditional imports to support both Python 3.11+ and earlier versions.
+"""
+
+from typesense.async_api_call import AsyncApiCall
+from typesense.types.alias import AliasSchema
+
+
+class AsyncAlias:
+    """
+    Manages async operations on a single alias in the Typesense API.
+
+    This class provides async methods to retrieve and delete an alias.
+
+    Attributes:
+        api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+        name (str): The name of the alias.
+    """
+
+    def __init__(self, api_call: AsyncApiCall, name: str):
+        """
+        Initialize the AsyncAlias instance.
+
+        Args:
+            api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+            name (str): The name of the alias.
+        """
+        self.api_call = api_call
+        self.name = name
+
+    async def retrieve(self) -> AliasSchema:
+        """
+        Retrieve this specific alias.
+
+        Returns:
+            AliasSchema: The schema containing the alias details.
+        """
+        response: AliasSchema = await self.api_call.get(
+            self._endpoint_path,
+            entity_type=AliasSchema,
+            as_json=True,
+        )
+        return response
+
+    async def delete(self) -> AliasSchema:
+        """
+        Delete this specific alias.
+
+        Returns:
+            AliasSchema: The schema containing the deletion response.
+        """
+        response: AliasSchema = await self.api_call.delete(
+            self._endpoint_path,
+            entity_type=AliasSchema,
+        )
+        return response
+
+    @property
+    def _endpoint_path(self) -> str:
+        """
+        Construct the API endpoint path for this specific alias.
+
+        Returns:
+            str: The constructed endpoint path.
+        """
+        from typesense.async_aliases import AsyncAliases
+
+        return "/".join([AsyncAliases.resource_path, self.name])

src/typesense/async_aliases.py

@@ -0,0 +1,129 @@
+"""
+This module provides async functionality for managing aliases in Typesense.
+
+It contains the AsyncAliases class, which allows for creating, updating, retrieving, and
+accessing individual aliases asynchronously.
+
+Classes:
+    AsyncAliases: Manages aliases in the Typesense API (async).
+
+Dependencies:
+    - typesense.async_api_call: Provides the AsyncApiCall class for making async API requests.
+    - typesense.async_alias: Provides the AsyncAlias class for individual alias operations.
+    - typesense.types.alias: Provides AliasCreateSchema, AliasSchema, and AliasesResponseSchema types.
+
+Note: This module uses conditional imports to support both Python 3.11+ and earlier versions.
+"""
+
+import sys
+
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_alias import AsyncAlias
+from typesense.types.alias import AliasCreateSchema, AliasSchema, AliasesResponseSchema
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+
+class AsyncAliases:
+    """
+    Manages aliases in the Typesense API (async).
+
+    This class provides async methods to create, update, retrieve, and access individual aliases.
+
+    Attributes:
+        resource_path (str): The API endpoint path for alias operations.
+        api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+        aliases (Dict[str, AsyncAlias]): A dictionary of AsyncAlias instances, keyed by alias name.
+    """
+
+    resource_path: typing.Final[str] = "/aliases"
+
+    def __init__(self, api_call: AsyncApiCall):
+        """
+        Initialize the AsyncAliases instance.
+
+        Args:
+            api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+        """
+        self.api_call = api_call
+        self.aliases: typing.Dict[str, AsyncAlias] = {}
+
+    def __getitem__(self, name: str) -> AsyncAlias:
+        """
+        Get or create an AsyncAlias instance for a given alias name.
+
+        This method allows accessing aliases using dictionary-like syntax.
+        If the AsyncAlias instance doesn't exist, it creates a new one.
+
+        Args:
+            name (str): The name of the alias.
+
+        Returns:
+            AsyncAlias: The AsyncAlias instance for the specified alias name.
+
+        Example:
+            >>> aliases = AsyncAliases(async_api_call)
+            >>> company_alias = aliases["company_alias"]
+        """
+        if not self.aliases.get(name):
+            self.aliases[name] = AsyncAlias(self.api_call, name)
+        return self.aliases.get(name)
+
+    async def upsert(self, name: str, mapping: AliasCreateSchema) -> AliasSchema:
+        """
+        Create or update an alias.
+
+        Args:
+            name (str): The name of the alias.
+            mapping (AliasCreateSchema): The schema for creating or updating the alias.
+
+        Returns:
+            AliasSchema: The created or updated alias.
+
+        Example:
+            >>> aliases = AsyncAliases(async_api_call)
+            >>> alias = await aliases.upsert(
+            ...     "company_alias", {"collection_name": "companies"}
+            ... )
+        """
+        response: AliasSchema = await self.api_call.put(
+            self._endpoint_path(name),
+            body=mapping,
+            entity_type=AliasSchema,
+        )
+        return response
+
+    async def retrieve(self) -> AliasesResponseSchema:
+        """
+        Retrieve all aliases.
+
+        Returns:
+            AliasesResponseSchema: The schema containing all aliases.
+
+        Example:
+            >>> aliases = AsyncAliases(async_api_call)
+            >>> all_aliases = await aliases.retrieve()
+            >>> for alias in all_aliases["aliases"]:
+            ...     print(alias["name"])
+        """
+        response: AliasesResponseSchema = await self.api_call.get(
+            AsyncAliases.resource_path,
+            as_json=True,
+            entity_type=AliasesResponseSchema,
+        )
+        return response
+
+    def _endpoint_path(self, alias_name: str) -> str:
+        """
+        Construct the API endpoint path for alias operations.
+
+        Args:
+            alias_name (str): The name of the alias.
+
+        Returns:
+            str: The constructed endpoint path.
+        """
+        return "/".join([AsyncAliases.resource_path, alias_name])

tests/alias_test.py

@@ -1,6 +1,5 @@
 """Tests for the Alias class."""
 
-from __future__ import annotations
 from tests.utils.object_assertions import (
     assert_match_object,
     assert_object_lists_match,
@@ -9,6 +8,9 @@
 from typesense.alias import Alias
 from typesense.aliases import Aliases
 from typesense.api_call import ApiCall
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_alias import AsyncAlias
+from typesense.async_aliases import AsyncAliases
 
 
 def test_init(fake_api_call: ApiCall) -> None:
@@ -28,6 +30,23 @@ def test_init(fake_api_call: ApiCall) -> None:
     assert alias._endpoint_path == "/aliases/company_alias"  # noqa: WPS437
 
 
+def test_init_async(fake_async_api_call: AsyncApiCall) -> None:
+    """Test that the AsyncAlias object is initialized correctly."""
+    alias = AsyncAlias(fake_async_api_call, "company_alias")
+
+    assert alias.name == "company_alias"
+    assert_match_object(alias.api_call, fake_async_api_call)
+    assert_object_lists_match(
+        alias.api_call.node_manager.nodes,
+        fake_async_api_call.node_manager.nodes,
+    )
+    assert_match_object(
+        alias.api_call.config.nearest_node,
+        fake_async_api_call.config.nearest_node,
+    )
+    assert alias._endpoint_path == "/aliases/company_alias"  # noqa: WPS437
+
+
 def test_actual_retrieve(
     actual_aliases: Aliases,
     delete_all_aliases: None,
@@ -62,3 +81,39 @@ def test_actual_delete(
         "collection_name": "companies",
         "name": "company_alias",
     }
+
+
+async def test_actual_retrieve_async(
+    actual_async_aliases: AsyncAliases,
+    delete_all_aliases: None,
+    delete_all: None,
+    create_alias: None,
+) -> None:
+    """Test that the AsyncAlias object can retrieve an alias from Typesense Server."""
+    response = await actual_async_aliases["company_alias"].retrieve()
+
+    assert response["collection_name"] == "companies"
+    assert response["name"] == "company_alias"
+
+    assert_to_contain_object(
+        response,
+        {
+            "collection_name": "companies",
+            "name": "company_alias",
+        },
+    )
+
+
+async def test_actual_delete_async(
+    actual_async_aliases: AsyncAliases,
+    delete_all_aliases: None,
+    delete_all: None,
+    create_alias: None,
+) -> None:
+    """Test that the AsyncAlias object can delete an alias from Typesense Server."""
+    response = await actual_async_aliases["company_alias"].delete()
+
+    assert response == {
+        "collection_name": "companies",
+        "name": "company_alias",
+    }