feat(apiclient): add CRUD methods for instantiated entities

Author: gegnew

.flake8

@@ -1,4 +1,4 @@
 [flake8]
-ignore = E226,E302,E41,W503
+ignore = E226,E302,E41,W503,E704
 max-line-length = 88
 exclude = tests/*

.github/workflows/push.yml

@@ -25,7 +25,7 @@ jobs:
         uses: TrueBrain/actions-flake8@master
         with:
           max_line_length: 88
-          extend-ignore: E203
+          extend-ignore: E203, E704
   test:
     runs-on: ubuntu-latest
     strategy:

cellengine/utils/api_client/APIClient.py

@@ -1,15 +1,18 @@
 from __future__ import annotations
-import os
+from functools import lru_cache
+from getpass import getpass
 import json
+import os
+from typing import Any, Dict, List, Optional, TypeVar, Union, overload
+
 import pandas
-from getpass import getpass
-from typing import Any, Dict, List, Union, Optional
-from functools import lru_cache
 from requests_toolbelt.multipart.encoder import MultipartEncoder
 
-from cellengine.utils.api_client.BaseAPIClient import BaseAPIClient
+from cellengine.utils import converter
 from cellengine.utils.api_client.APIError import APIError
+from cellengine.utils.api_client.BaseAPIClient import BaseAPIClient
 from cellengine.utils.singleton import Singleton
+
 from ...resources.attachment import Attachment
 from ...resources.compensation import Compensation
 from ...resources.experiment import Experiment
@@ -20,6 +23,14 @@
 from ...resources.scaleset import ScaleSet
 
 
+CE = TypeVar(
+    "CE",
+    bound=Union[
+        Attachment, Compensation, Experiment, FcsFile, Gate, Plot, Population, ScaleSet
+    ],
+)
+
+
 class APIClient(BaseAPIClient, metaclass=Singleton):
     _API_NAME = "CellEngine Python Toolkit"
 
@@ -119,6 +130,85 @@ def update_entity(self, experiment_id, _id, entity_type, body) -> dict:
             json=body,
         )
 
+    def _get_path(self, entity: CE) -> str:
+        fullpath = f"{self.base_url}/{entity.path}"
+        return fullpath
+
+    # fmt: off
+    # temporary fix for https://github.com/psf/black/issues/1797
+    @overload
+    def create(self, entity: Attachment, **kwargs) -> Attachment: ...
+    @overload
+    def create(self, entity: Compensation, **kwargs) -> Compensation: ...
+    @overload
+    def create(self, entity: Experiment, **kwargs) -> Experiment: ...
+    @overload
+    def create(self, entity: FcsFile, **kwargs) -> FcsFile: ...
+    @overload
+    def create(self, entity: Gate, **kwargs) -> Gate: ...
+    @overload
+    def create(self, entity: Population, **kwargs) -> Population: ...
+    @overload
+    def create(self, entity: ScaleSet, **kwargs) -> ScaleSet: ...
+    # fmt: on
+
+    def create(
+        self, entity, **kwargs
+    ) -> Union[
+        Attachment,
+        Compensation,
+        Experiment,
+        FcsFile,
+        Gate,
+        Population,
+        ScaleSet,
+    ]:
+        """Create a local entity on CellEngine."""
+
+        def unstructure_and_clean(entity, **kwargs):
+            (cls, path, body) = (
+                entity.__class__,
+                entity.path,
+                converter.unstructure(entity),
+            )
+            if body["_id"] == "None" or body["_id"] is None:
+                del body["_id"]  # https://github.com/primitybio/cellengine/issues/5800
+            return (cls, path, body)
+
+        def post_and_restructure(cls, path, body, **kwargs):
+            res = self._post(f"{self.base_url}/{path}", json=body, params=kwargs)
+            return converter.structure(res, cls)
+
+        if isinstance(entity, list):
+            body = [unstructure_and_clean(thing) for thing in entity]
+            # group [(class), (path), (body)]
+            unzipped = list(zip(*body))
+            # remove duplicates to ensure all entities are of the same type
+            (cls, path, body) = (set(unzipped[0]), set(unzipped[1]), unzipped[2])
+
+            if len(cls) == 1 and len(path) == 1:
+                # then post to bulk endpoint
+                res = post_and_restructure(
+                    List[cls.pop()], path.pop(), list(body)  # type: ignore
+                )
+            else:
+                # post each item individually
+                res = [post_and_restructure(*thing) for thing in body]
+        else:
+            body = unstructure_and_clean(entity)
+            res = post_and_restructure(*body)
+        return res  # type: ignore
+
+    def update(self, entity, params: Dict = None):
+        path = self._get_path(entity)
+        data = converter.unstructure(entity)
+        res = self._patch(path, json=data, params=params)
+        return converter.structure(res, entity.__class__)
+
+    def delete(self, entity, params: Dict = None) -> None:
+        path = self._get_path(entity)
+        self._delete(path, params=params)
+
     def delete_entity(self, experiment_id, entity_type, _id):
         url = f"{self.base_url}/experiments/{experiment_id}/{entity_type}/{_id}"
         self._delete(url)