Add ability to create an item with a certain group, and group lookup (#91)

Author: ml-evs

src/datalab_api/__init__.py

@@ -127,6 +127,8 @@ def create_item(
         item_type: str = "samples",
         item_data: dict[str, Any] | None = None,
         collection_id: str | None = None,
+        collection_ids: str | Iterable[str] | None = None,  # alias for collection_id
+        group_ids: str | Iterable[str] | None = None,
     ) -> dict[str, Any]:
         """Create an item with a given ID and item data.
 
@@ -135,7 +137,9 @@ def create_item(
             item_type: The type of item to create, e.g., 'samples', 'cells'.
             item_data: The data for the item.
             collection_id: The ID of the collection to add the item to (optional).
-                If such a collection does not exist, one will be made.
+                If such a collection does not exist, one will be made. Deprecated in favor of `collection_ids`.
+            collection_ids: The ID or IDs of the collection(s) to add the item to (optional).
+            group_ids: The ID or IDs of the group(s) to share the item with (optional).
 
         """
         new_item = {}
@@ -147,13 +151,34 @@ def create_item(
             new_item.pop("item_id")
 
         if collection_id is not None:
-            try:
-                collection_immutable_id = self.get_collection(collection_id)[0]["immutable_id"]
-            except (RuntimeError, DatalabAPIError):
-                self.create_collection(collection_id)
-                collection_immutable_id = self.get_collection(collection_id)[0]["immutable_id"]
+            warnings.warn(
+                DeprecationWarning(
+                    "`collection_id` is deprecated, please use `collection_ids` instead."
+                )
+            )
+            if collection_ids is None:
+                collection_ids = [collection_id]
+
+        if collection_ids:
             new_item["collections"] = new_item.get("collections", [])
-            new_item["collections"].append({"immutable_id": collection_immutable_id})
+            for collection_id in collection_ids:
+                try:
+                    collection_immutable_id = self.get_collection(collection_id)[0]["immutable_id"]
+                except (RuntimeError, DatalabAPIError):
+                    self.create_collection(collection_id)
+                    collection_immutable_id = self.get_collection(collection_id)[0]["immutable_id"]
+                new_item["collections"].append({"immutable_id": collection_immutable_id})
+
+        if group_ids:
+            # For now, we have to use the search groups endpoint
+            # until we add a get group by id endpoint that is locked down per user
+            new_item["groups"] = new_item.get("groups", [])
+            for group_id in group_ids:
+                try:
+                    group_immutable_id = self.get_group(group_id)["immutable_id"]
+                    new_item["groups"].append({"immutable_id": group_immutable_id})
+                except (RuntimeError, DatalabAPIError):
+                    pass
 
         create_item_url = f"{self.datalab_api_url}/new-sample/"
         created_item = self._post(
@@ -435,6 +460,32 @@ def get_collection(self, collection_id: str) -> tuple[dict[str, Any], list[dict[
         collection = self._get(collection_url)
         return collection["data"], collection["child_items"]
 
+    def get_group(self, group_id: str) -> dict[str, Any]:
+        """Get a group with a given ID.
+
+        Uses the search groups endpoint under the hood,
+        so will only find groups that the user has access
+        to and that match the query.
+
+        Parameters:
+            group_id: The human-readable ID of the group to search for.
+
+        Returns:
+            A dictionary of group data for the group with the given ID.
+
+        Raises:
+            DatalabAPIError: If no group with the given ID is found.
+
+        """
+        group_url = f"{self.datalab_api_url}/search/groups?query={group_id}"
+        group_resp = self._get(group_url)
+        matching_groups = group_resp["data"]
+        if matching_groups:
+            matching_groups = [g for g in matching_groups if g.get("group_id") == group_id]
+            return matching_groups[0]
+
+        raise DatalabAPIError(f"No group found with ID {group_id!r}")
+
     def create_collection(
         self, collection_id: str, collection_data: dict | None = None
     ) -> dict[str, Any]:

tests/conftest.py

@@ -65,6 +65,51 @@ def mocked_api(
             500, json={"message": "('type',)", "title": "KeyError"}
         )
 
+        fake_group_search_api = respx_mock.get(
+            "/search/groups?query=test_group", name="search-groups"
+        )
+        fake_group_search_api.return_value = Response(
+            200,
+            json={
+                "data": [
+                    {
+                        "description": "test",
+                        "display_name": "Test",
+                        "group_id": "test2",
+                        "immutable_id": "6949ca813a5a8985defeb403",
+                        "last_modified": None,
+                        "managers": [],
+                        "members": None,
+                        "relationships": None,
+                        "type": "groups",
+                    },
+                    {
+                        "description": "test",
+                        "display_name": "testtest",
+                        "group_id": "test-test",
+                        "immutable_id": "696011270060765fbbeb868b",
+                        "last_modified": None,
+                        "managers": [],
+                        "members": None,
+                        "relationships": None,
+                        "type": "groups",
+                    },
+                    {
+                        "description": "Add longer description",
+                        "display_name": "Test group",
+                        "group_id": "test_group",
+                        "immutable_id": "67d0b01e03000cdc75134dbd",
+                        "last_modified": None,
+                        "managers": [],
+                        "members": None,
+                        "relationships": None,
+                        "type": "groups",
+                    },
+                ],
+                "status": "success",
+            },
+        )
+
         yield respx_mock
 
 

tests/test_client.py

@@ -58,3 +58,16 @@ def test_collection_get(fake_api_url, mocked_api):
 
         collection, children = client.get_collection("test_collection", display=True)
         assert mocked_api["collection-test_collection"].called
+
+
+@respx.mock
+def test_group_get(fake_api_url, mocked_api):
+    with DatalabClient("https://api.datalab.industries") as client:
+        assert mocked_api["api"].called
+        assert mocked_api["info"].called
+        assert mocked_api["info-blocks"].called
+
+        group = client.get_group("test_group", display=True)
+        assert mocked_api["search-groups"].called
+        assert group["immutable_id"] == "67d0b01e03000cdc75134dbd"
+        assert group["group_id"] == "test_group"