feat: add items accessors to synonym sets and curation sets

src/typesense/async_/curation_set.py

@@ -22,7 +22,9 @@
     import typing_extensions as typing
 
 from .api_call import AsyncApiCall
+from .curation_set_items import AsyncCurationSetItems
 from typesense.types.curation_set import (
+    CurationItemCreateSchema,
     CurationItemDeleteSchema,
     CurationItemSchema,
     CurationSetDeleteSchema,
@@ -42,6 +44,7 @@ class AsyncCurationSet:
     Attributes:
         api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
         name (str): The name of the curation set.
+        items (AsyncCurationSetItems): The items of the curation set.
     """
 
     def __init__(self, api_call: AsyncApiCall, name: str) -> None:
@@ -54,6 +57,7 @@ def __init__(self, api_call: AsyncApiCall, name: str) -> None:
         """
         self.api_call = api_call
         self.name = name
+        self.items = AsyncCurationSetItems(api_call, name)
 
     @property
     def _endpoint_path(self) -> str:
@@ -114,17 +118,6 @@ async def upsert(
         )
         return response
 
-    # Items sub-resource
-    @property
-    def _items_path(self) -> str:
-        """
-        Get the API endpoint path for items in this curation set.
-
-        Returns:
-            str: The full endpoint path for items (e.g., /curation_sets/{name}/items).
-        """
-        return "/".join([self._endpoint_path, "items"])
-
     async def list_items(
         self,
         *,
@@ -141,21 +134,7 @@ async def list_items(
         Returns:
             CurationSetListItemResponseSchema: The list of items in the curation set.
         """
-        params: typing.Dict[str, typing.Union[int, None]] = {
-            "limit": limit,
-            "offset": offset,
-        }
-        # Filter out None values to avoid sending them
-        clean_params: typing.Dict[str, int] = {
-            k: v for k, v in params.items() if v is not None
-        }
-        response: CurationSetListItemResponseSchema = await self.api_call.get(
-            self._items_path,
-            as_json=True,
-            entity_type=CurationSetListItemResponseSchema,
-            params=clean_params or None,
-        )
-        return response
+        return await self.items.retrieve(limit=limit, offset=offset)
 
     async def get_item(self, item_id: str) -> CurationItemSchema:
         """
@@ -167,32 +146,24 @@ async def get_item(self, item_id: str) -> CurationItemSchema:
         Returns:
             CurationItemSchema: The item schema.
         """
-        response: CurationItemSchema = await self.api_call.get(
-            "/".join([self._items_path, item_id]),
-            as_json=True,
-            entity_type=CurationItemSchema,
-        )
-        return response
+        return await self.items[item_id].retrieve()
 
     async def upsert_item(
-        self, item_id: str, item: CurationItemSchema
+        self,
+        item_id: str,
+        item: typing.Union[CurationItemSchema, CurationItemCreateSchema],
     ) -> CurationItemSchema:
         """
         Create or update an item in this curation set.
 
         Args:
             item_id (str): The ID of the item.
-            item (CurationItemSchema): The item schema.
+            item (Union[CurationItemSchema, CurationItemCreateSchema]): The item schema.
 
         Returns:
             CurationItemSchema: The created or updated item.
         """
-        response: CurationItemSchema = await self.api_call.put(
-            "/".join([self._items_path, item_id]),
-            body=item,
-            entity_type=CurationItemSchema,
-        )
-        return response
+        return await self.items[item_id].upsert(item)
 
     async def delete_item(self, item_id: str) -> CurationItemDeleteSchema:
         """
@@ -204,8 +175,4 @@ async def delete_item(self, item_id: str) -> CurationItemDeleteSchema:
         Returns:
             CurationItemDeleteSchema: The deletion response.
         """
-        response: CurationItemDeleteSchema = await self.api_call.delete(
-            "/".join([self._items_path, item_id]),
-            entity_type=CurationItemDeleteSchema,
-        )
-        return response
+        return await self.items[item_id].delete()

src/typesense/async_/curation_set_item.py

@@ -0,0 +1,88 @@
+"""
+This module provides async functionality for managing a single curation set item in Typesense.
+
+Classes:
+    AsyncCurationSetItem: Retrieves, upserts and deletes one item of a curation set (async).
+"""
+
+from .api_call import AsyncApiCall
+from typesense.types.curation_set import (
+    CurationItemCreateSchema,
+    CurationItemDeleteSchema,
+    CurationItemSchema,
+)
+
+
+class AsyncCurationSetItem:
+    """
+    Manages a single item of a curation set in the Typesense API (async).
+
+    Attributes:
+        api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+        curation_set_name (str): The name of the curation set.
+        item_id (str): The ID of the item.
+    """
+
+    def __init__(
+        self, api_call: AsyncApiCall, curation_set_name: str, item_id: str
+    ) -> None:
+        self.api_call = api_call
+        self.curation_set_name = curation_set_name
+        self.item_id = item_id
+
+    @property
+    def _endpoint_path(self) -> str:
+        from .curation_sets import AsyncCurationSets
+
+        return "/".join(
+            [
+                AsyncCurationSets.resource_path,
+                self.curation_set_name,
+                "items",
+                self.item_id,
+            ]
+        )
+
+    async def retrieve(self) -> CurationItemSchema:
+        """
+        Retrieve this item.
+
+        Returns:
+            CurationItemSchema: The item schema.
+        """
+        response: CurationItemSchema = await self.api_call.get(
+            self._endpoint_path,
+            as_json=True,
+            entity_type=CurationItemSchema,
+        )
+        return response
+
+    async def upsert(self, item: CurationItemCreateSchema) -> CurationItemSchema:
+        """
+        Create or update this item.
+
+        Args:
+            item (CurationItemCreateSchema): The item schema.
+
+        Returns:
+            CurationItemSchema: The created or updated item.
+        """
+        response: CurationItemSchema = await self.api_call.put(
+            self._endpoint_path,
+            body=item,
+            entity_type=CurationItemSchema,
+        )
+        return response
+
+    async def delete(self) -> CurationItemDeleteSchema:
+        """
+        Delete this item.
+
+        Returns:
+            CurationItemDeleteSchema: The deletion response.
+        """
+        response: CurationItemDeleteSchema = await self.api_call.delete(
+            self._endpoint_path,
+            entity_type=CurationItemDeleteSchema,
+        )
+        return response

src/typesense/async_/curation_set_items.py

@@ -0,0 +1,98 @@
+"""
+This module provides async functionality for managing the items of a curation set in Typesense.
+
+Classes:
+    AsyncCurationSetItems: Lists, upserts and accesses items of a single curation set (async).
+"""
+
+import sys
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+from .api_call import AsyncApiCall
+from .curation_set_item import AsyncCurationSetItem
+from typesense.types.curation_set import (
+    CurationItemCreateSchema,
+    CurationItemSchema,
+    CurationSetListItemResponseSchema,
+)
+
+
+class AsyncCurationSetItems:
+    """
+    Manages the items of a single curation set in the Typesense API (async).
+
+    Attributes:
+        api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+        curation_set_name (str): The name of the curation set.
+    """
+
+    def __init__(self, api_call: AsyncApiCall, curation_set_name: str) -> None:
+        self.api_call = api_call
+        self.curation_set_name = curation_set_name
+
+    def __getitem__(self, item_id: str) -> AsyncCurationSetItem:
+        """
+        Get an AsyncCurationSetItem instance for a given item ID.
+
+        Example:
+            >>> item = curation_sets["products"].items["rule-1"]
+        """
+        return AsyncCurationSetItem(self.api_call, self.curation_set_name, item_id)
+
+    @property
+    def _endpoint_path(self) -> str:
+        from .curation_sets import AsyncCurationSets
+
+        return "/".join(
+            [AsyncCurationSets.resource_path, self.curation_set_name, "items"]
+        )
+
+    async def retrieve(
+        self,
+        *,
+        limit: typing.Union[int, None] = None,
+        offset: typing.Union[int, None] = None,
+    ) -> CurationSetListItemResponseSchema:
+        """
+        List items in this curation set.
+
+        Args:
+            limit (Union[int, None], optional): Maximum number of items to return. Defaults to None.
+            offset (Union[int, None], optional): Number of items to skip. Defaults to None.
+
+        Returns:
+            CurationSetListItemResponseSchema: The list of items in the curation set.
+        """
+        params: typing.Dict[str, typing.Union[int, None]] = {
+            "limit": limit,
+            "offset": offset,
+        }
+        clean_params: typing.Dict[str, int] = {
+            k: v for k, v in params.items() if v is not None
+        }
+        response: CurationSetListItemResponseSchema = await self.api_call.get(
+            self._endpoint_path,
+            as_json=True,
+            entity_type=CurationSetListItemResponseSchema,
+            params=clean_params or None,
+        )
+        return response
+
+    async def upsert(
+        self, item_id: str, item: CurationItemCreateSchema
+    ) -> CurationItemSchema:
+        """
+        Create or update an item in this curation set.
+
+        Args:
+            item_id (str): The ID of the item.
+            item (CurationItemCreateSchema): The item schema.
+
+        Returns:
+            CurationItemSchema: The created or updated item.
+        """
+        return await self[item_id].upsert(item)

src/typesense/async_/synonym_set.py

@@ -8,9 +8,11 @@
     import typing_extensions as typing
 
 from .api_call import AsyncApiCall
+from .synonym_set_items import AsyncSynonymSetItems
 from typesense.types.synonym_set import (
     SynonymItemDeleteSchema,
     SynonymItemSchema,
+    SynonymItemUpsertSchema,
     SynonymSetCreateSchema,
     SynonymSetDeleteSchema,
     SynonymSetRetrieveSchema,
@@ -21,6 +23,7 @@ class AsyncSynonymSet:
     def __init__(self, api_call: AsyncApiCall, name: str) -> None:
         self.api_call = api_call
         self.name = name
+        self.items = AsyncSynonymSetItems(api_call, name)
 
     @property
     def _endpoint_path(self) -> str:
@@ -51,52 +54,23 @@ async def delete(self) -> SynonymSetDeleteSchema:
         )
         return response
 
-    @property
-    def _items_path(self) -> str:
-        return "/".join([self._endpoint_path, "items"])  # /synonym_sets/{name}/items
-
     async def list_items(
         self,
         *,
         limit: typing.Union[int, None] = None,
         offset: typing.Union[int, None] = None,
     ) -> typing.List[SynonymItemSchema]:
-        params: typing.Dict[str, typing.Union[int, None]] = {
-            "limit": limit,
-            "offset": offset,
-        }
-        clean_params: typing.Dict[str, int] = {
-            k: v for k, v in params.items() if v is not None
-        }
-        response: typing.List[SynonymItemSchema] = await self.api_call.get(
-            self._items_path,
-            as_json=True,
-            entity_type=typing.List[SynonymItemSchema],
-            params=clean_params or None,
-        )
-        return response
+        return await self.items.retrieve(limit=limit, offset=offset)
 
     async def get_item(self, item_id: str) -> SynonymItemSchema:
-        response: SynonymItemSchema = await self.api_call.get(
-            "/".join([self._items_path, item_id]),
-            as_json=True,
-            entity_type=SynonymItemSchema,
-        )
-        return response
+        return await self.items[item_id].retrieve()
 
     async def upsert_item(
-        self, item_id: str, item: SynonymItemSchema
+        self,
+        item_id: str,
+        item: typing.Union[SynonymItemSchema, SynonymItemUpsertSchema],
     ) -> SynonymItemSchema:
-        response: SynonymItemSchema = await self.api_call.put(
-            "/".join([self._items_path, item_id]),
-            body=item,
-            entity_type=SynonymItemSchema,
-        )
-        return response
+        return await self.items[item_id].upsert(item)
 
     async def delete_item(self, item_id: str) -> SynonymItemDeleteSchema:
-        # API returns {"id": "..."} for delete; openapi defines SynonymItemDeleteResponse with name but for items it's id
-        response: SynonymItemDeleteSchema = await self.api_call.delete(
-            "/".join([self._items_path, item_id]), entity_type=SynonymItemDeleteSchema
-        )
-        return response
+        return await self.items[item_id].delete()