feat(collection): add async support for collection operations

- add AsyncCollection class for async individual collection operations
- add AsyncCollections class for async collection collection operations
- add async tests for collection and collections functionality
- add async fixtures for testing async collection operations
- remove future annotations imports from test files

Author: tharropoulos

src/typesense/async_collection.py

@@ -0,0 +1,161 @@
+"""
+This module provides async functionality for managing individual collections in the Typesense API.
+
+It contains the AsyncCollection class, which allows for retrieving, updating, and deleting
+collections asynchronously.
+
+Classes:
+    AsyncCollection: Manages async operations on a single collection in the Typesense API.
+
+Dependencies:
+    - typesense.async_api_call: Provides the AsyncApiCall class for making async API requests.
+    - typesense.types.collection: Provides CollectionSchema and CollectionUpdateSchema types.
+    - typesense.types.document: Provides DocumentSchema type.
+
+Note: This module uses conditional imports to support both Python 3.11+ and earlier versions.
+"""
+
+import sys
+
+from typing_extensions import deprecated
+
+from typesense.types.collection import CollectionSchema, CollectionUpdateSchema
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_overrides import AsyncOverrides
+from typesense.async_synonyms import AsyncSynonyms
+from typesense.types.document import DocumentSchema
+
+TDoc = typing.TypeVar("TDoc", bound=DocumentSchema, covariant=True)
+
+
+class AsyncCollection(typing.Generic[TDoc]):
+    """
+    Manages async operations on a single collection in the Typesense API.
+
+    This class provides async methods to retrieve, update, and delete a collection.
+    It is generic over the document type TDoc, which should be a subtype of DocumentSchema.
+
+    Attributes:
+        name (str): The name of the collection.
+        api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+    """
+
+    def __init__(self, api_call: AsyncApiCall, name: str):
+        """
+        Initialize the AsyncCollection instance.
+
+        Args:
+            api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+            name (str): The name of the collection.
+        """
+        self.name = name
+        self.api_call = api_call
+        # Import here to avoid circular imports
+        from typesense.async_overrides import AsyncOverrides
+        from typesense.async_synonyms import AsyncSynonyms
+
+        self._overrides = AsyncOverrides(api_call, name)
+        self._synonyms = AsyncSynonyms(api_call, name)
+
+    async def retrieve(self) -> CollectionSchema:
+        """
+        Retrieve the schema of this collection from Typesense.
+
+        Returns:
+            CollectionSchema: The schema of the collection.
+        """
+        response: CollectionSchema = await self.api_call.get(
+            endpoint=self._endpoint_path,
+            entity_type=CollectionSchema,
+            as_json=True,
+        )
+        return response
+
+    async def update(
+        self, schema_change: CollectionUpdateSchema
+    ) -> CollectionUpdateSchema:
+        """
+        Update the schema of this collection in Typesense.
+
+        Args:
+            schema_change (CollectionUpdateSchema):
+                The changes to apply to the collection schema.
+
+        Returns:
+            CollectionUpdateSchema: The updated schema of the collection.
+        """
+        response: CollectionUpdateSchema = await self.api_call.patch(
+            endpoint=self._endpoint_path,
+            body=schema_change,
+            entity_type=CollectionUpdateSchema,
+        )
+        return response
+
+    async def delete(
+        self,
+        delete_parameters: typing.Union[
+            typing.Dict[str, typing.Union[str, bool]],
+            None,
+        ] = None,
+    ) -> CollectionSchema:
+        """
+        Delete this collection from Typesense.
+
+        Args:
+            delete_parameters (Union[Dict[str, Union[str, bool]], None], optional):
+                Additional parameters for the delete operation. Defaults to None.
+
+        Returns:
+            CollectionSchema: The schema of the deleted collection.
+        """
+        response: CollectionSchema = await self.api_call.delete(
+            self._endpoint_path,
+            entity_type=CollectionSchema,
+            params=delete_parameters,
+        )
+        return response
+
+    @property
+    @deprecated(
+        "Overrides is deprecated on v30+. Use client.curation_sets instead.",
+        category=None,
+    )
+    def overrides(self) -> AsyncOverrides:
+        """Return the AsyncOverrides instance for this collection.
+
+        Returns:
+            AsyncOverrides: The AsyncOverrides instance for this collection.
+        """
+        return self._overrides
+
+    @property
+    @deprecated(
+        "Synonyms is deprecated on v30+. Use client.synonym_sets instead.",
+        category=None,
+    )
+    def synonyms(self) -> AsyncSynonyms:
+        """Return the AsyncSynonyms instance for this collection.
+
+        Returns:
+            AsyncSynonyms: The AsyncSynonyms instance for this collection.
+        """
+        """Return the AsyncSynonyms instance for this collection."""
+        return self._synonyms
+
+    @property
+    def _endpoint_path(self) -> str:
+        """
+        Get the API endpoint path for this collection.
+
+        Returns:
+            str: The full endpoint path for the collection.
+        """
+        from typesense.async_collections import AsyncCollections
+
+        return "/".join([AsyncCollections.resource_path, self.name])

src/typesense/async_collections.py

@@ -0,0 +1,163 @@
+"""
+This module provides async functionality for managing collections in the Typesense API.
+
+It contains the AsyncCollections class, which allows for creating, retrieving, and
+accessing individual collections asynchronously.
+
+Classes:
+    AsyncCollections: Manages collections in the Typesense API (async).
+
+Dependencies:
+    - typesense.async_api_call: Provides the AsyncApiCall class for making async API requests.
+    - typesense.async_collection: Provides the AsyncCollection class for individual collection operations.
+    - typesense.types.collection: Provides CollectionCreateSchema and CollectionSchema types.
+    - typesense.types.document: Provides DocumentSchema type.
+
+Note: This module uses conditional imports to support both Python 3.11+ and earlier versions.
+"""
+
+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_collection import AsyncCollection
+from typesense.types.collection import CollectionCreateSchema, CollectionSchema
+from typesense.types.document import DocumentSchema
+
+TDoc = typing.TypeVar("TDoc", bound=DocumentSchema, covariant=True)
+
+
+class AsyncCollections(typing.Generic[TDoc]):
+    """
+    Manages collections in the Typesense API (async).
+
+    This class provides async methods to create, retrieve, and access individual collections.
+    It is generic over the document type TDoc, which should be a subtype of DocumentSchema.
+
+    Attributes:
+        resource_path (str): The API endpoint path for collections operations.
+        api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+        collections (Dict[str, AsyncCollection[TDoc]]):
+           A dictionary of AsyncCollection instances, keyed by collection name.
+    """
+
+    resource_path: typing.Final[str] = "/collections"
+
+    def __init__(self, api_call: AsyncApiCall):
+        """
+        Initialize the AsyncCollections instance.
+
+        Args:
+            api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+        """
+        self.api_call = api_call
+        self.collections: typing.Dict[str, AsyncCollection[TDoc]] = {}
+
+    async def __contains__(self, collection_name: str) -> bool:
+        """
+        Check if a collection exists in Typesense.
+
+        This method tries to retrieve the specified collection to check for its existence,
+        utilizing the AsyncCollection.retrieve() method but without caching non-existent collections.
+
+        Args:
+            collection_name (str): The name of the collection to check.
+
+        Returns:
+            bool: True if the collection exists, False otherwise.
+        """
+        if collection_name in self.collections:
+            try:
+                await self.collections[collection_name].retrieve()
+                return True
+            except Exception:
+                self.collections.pop(collection_name, None)
+                return False
+
+        try:
+            await AsyncCollection(self.api_call, collection_name).retrieve()
+            return True
+        except Exception:
+            return False
+
+    def __getitem__(self, collection_name: str) -> AsyncCollection[TDoc]:
+        """
+        Get or create an AsyncCollection instance for a given collection name.
+
+        This method allows accessing collections using dictionary-like syntax.
+        If the AsyncCollection instance doesn't exist, it creates a new one.
+
+        Args:
+            collection_name (str): The name of the collection to access.
+
+        Returns:
+            AsyncCollection[TDoc]: The AsyncCollection instance for the specified collection name.
+
+        Example:
+            >>> collections = AsyncCollections(async_api_call)
+            >>> fruits_collection = collections["fruits"]
+        """
+        if not self.collections.get(collection_name):
+            self.collections[collection_name] = AsyncCollection(
+                self.api_call,
+                collection_name,
+            )
+        return self.collections[collection_name]
+
+    async def create(self, schema: CollectionCreateSchema) -> CollectionSchema:
+        """
+        Create a new collection in Typesense.
+
+        Args:
+            schema (CollectionCreateSchema):
+               The schema defining the structure of the new collection.
+
+        Returns:
+            CollectionSchema:
+                The schema of the created collection, as returned by the API.
+
+        Example:
+            >>> collections = AsyncCollections(async_api_call)
+            >>> schema = {
+            ...     "name": "companies",
+            ...     "fields": [
+            ...         {"name": "company_name", "type": "string"},
+            ...         {"name": "num_employees", "type": "int32"},
+            ...         {"name": "country", "type": "string", "facet": True},
+            ...     ],
+            ...     "default_sorting_field": "num_employees",
+            ... }
+            >>> created_schema = await collections.create(schema)
+        """
+        call: CollectionSchema = await self.api_call.post(
+            endpoint=AsyncCollections.resource_path,
+            entity_type=CollectionSchema,
+            as_json=True,
+            body=schema,
+        )
+        return call
+
+    async def retrieve(self) -> typing.List[CollectionSchema]:
+        """
+        Retrieve all collections from Typesense.
+
+        Returns:
+            List[CollectionSchema]:
+               A list of schemas for all collections in the Typesense instance.
+
+        Example:
+            >>> collections = AsyncCollections(async_api_call)
+            >>> all_collections = await collections.retrieve()
+            >>> for collection in all_collections:
+            ...     print(collection["name"])
+        """
+        call: typing.List[CollectionSchema] = await self.api_call.get(
+            endpoint=AsyncCollections.resource_path,
+            as_json=True,
+            entity_type=typing.List[CollectionSchema],
+        )
+        return call

tests/collection_test.py

@@ -1,7 +1,5 @@
 """Tests for the Collection class."""
 
-from __future__ import annotations
-
 from tests.utils.object_assertions import (
     assert_match_object,
     assert_object_lists_match,