datalab-api 0.3.2__tar.gz → 0.5.0__tar.gz

{datalab_api-0.3.2/src/datalab_api.egg-info → datalab_api-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datalab-api
-Version: 0.3.2
+Version: 0.5.0
 Summary: A Python API for instances of the datalab data management platform (https://github.com/datalab-org/datalab).
 Author-email: Matthew Evans <matthew@ml-evs.science>
 License-Expression: MIT
@@ -13,6 +13,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Information Technology
 Classifier: Topic :: Other/Nonlisted Topic
@@ -38,9 +39,6 @@ Requires-Dist: mkdocs-jupyter; extra == "docs"
 Provides-Extra: cli
 Requires-Dist: typer~=0.9; extra == "cli"
 Requires-Dist: click-shell~=2.1; extra == "cli"
-Provides-Extra: cheminventory-helper
-Requires-Dist: pandas~=2.2; extra == "cheminventory-helper"
-Requires-Dist: openpyxl~=3.0; extra == "cheminventory-helper"
 Provides-Extra: all
 Requires-Dist: datalab-api[cli,dev,docs]; extra == "all"
 Dynamic: license-file

{datalab_api-0.3.2 → datalab_api-0.5.0}/pyproject.toml

@@ -16,6 +16,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Intended Audience :: Science/Research",
     "Intended Audience :: Information Technology",
     "Topic :: Other/Nonlisted Topic",
@@ -52,8 +53,6 @@ cli = [
     "click-shell ~= 2.1", # REPL-like interface
 ]
 
-cheminventory-helper = ["pandas ~= 2.2", "openpyxl ~= 3.0"]
-
 all = ["datalab-api[dev,docs,cli]"]
 
 [project.scripts]

{datalab_api-0.3.2 → datalab_api-0.5.0}/src/datalab_api/__init__.py

@@ -5,6 +5,8 @@ from collections.abc import Iterable
 from pathlib import Path
 from typing import Any, Optional, Union
 
+import httpx
+
 from ._base import BaseDatalabClient, DatalabAPIError, DuplicateItemError, __version__
 
 __all__ = ("DatalabClient", "DuplicateItemError", "__version__")
@@ -125,6 +127,8 @@ class DatalabClient(BaseDatalabClient):
         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.
 
@@ -133,7 +137,9 @@ class DatalabClient(BaseDatalabClient):
             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 = {}
@@ -145,16 +151,34 @@ class DatalabClient(BaseDatalabClient):
             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:
-                self.create_collection(collection_id)
-                collection_immutable_id = self.get_collection(collection_id)[0]["immutable_id"]
-            except 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(
@@ -272,12 +296,16 @@ class DatalabClient(BaseDatalabClient):
         block = self._post(block_url, json=block_request)
         return block["new_block_data"]
 
-    def upload_file(self, item_id: str, file_path: Path | str) -> dict[str, Any]:
+    def upload_file(
+        self, item_id: str, file_path: Path | str, replace_file_id: str | None = None
+    ) -> dict[str, Any]:
         """Upload a file to an item with a given ID.
 
         Parameters:
             item_id: The ID of the item to upload the file to.
             file_path: The path to the file to upload.
+            replace_file_id: The ID of an existing file to replace with the uploaded file, if any.
+                If provided, the new file will take the place of the old file in any blocks it was attached to.
 
         Returns:
             A dictionary of the uploaded file data.
@@ -288,14 +316,19 @@ class DatalabClient(BaseDatalabClient):
         if not file_path.exists():
             raise FileNotFoundError(f"File {file_path=} does not exist.")
 
+        # Use a longer read timeout for uploads, as the server may do
+        # significant processing before responding
+        upload_timeout = httpx.Timeout(self._timeout.connect, read=600.0, pool=self._timeout.pool)
+
         upload_url = f"{self.datalab_api_url}/upload-file/"
         with open(file_path, "rb") as file:
             files = {"file": (file_path.name, file)}
             upload = self._post(
                 upload_url,
                 files=files,
-                data={"item_id": item_id, "replace_file": None},
+                data={"item_id": item_id, "replace_file": replace_file_id},
                 expected_status=201,
+                timeout=upload_timeout,
             )
         return upload
 
@@ -403,8 +436,18 @@ class DatalabClient(BaseDatalabClient):
             "save_to_db": True,
         }
 
-        resp = self._post(blocks_url, json=payload)
-        return resp["new_block_data"]
+        resp = self._post(blocks_url, expected_status=[200, 202], json=payload)
+
+        # If block is created synchronously, return the block data
+        if "new_block_data" in resp:
+            return resp["new_block_data"]
+
+        # Otherwise, we return the response which may contain information about the asynchronous block creation process
+        task_id = resp.get("task_id")
+        if task_id:
+            self.triggered_block_task_ids.add(task_id)
+
+        return resp
 
     def get_collection(self, collection_id: str) -> tuple[dict[str, Any], list[dict[str, Any]]]:
         """Get a collection with a given ID.
@@ -421,6 +464,32 @@ class DatalabClient(BaseDatalabClient):
         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]:

{datalab_api-0.3.2 → datalab_api-0.5.0}/src/datalab_api/_base.py

@@ -4,7 +4,7 @@ import re
 import warnings
 from getpass import getpass
 from importlib.metadata import version
-from typing import Any, Optional
+from typing import Any, Optional, Union
 
 import httpx
 from rich.logging import RichHandler
@@ -35,7 +35,7 @@ class BaseDatalabClient(metaclass=AutoPrettyPrint):
 
     _api_key: Optional[str] = None
     _session: Optional[httpx.Client] = None
-    _headers: dict[str, str] = {}
+    _headers: dict[str, str]
     _timeout: httpx.Timeout = httpx.Timeout(10.0, read=60.0)
 
     interactive: bool = True
@@ -43,6 +43,9 @@ class BaseDatalabClient(metaclass=AutoPrettyPrint):
     Set to false if you want the script to error if no API key is found in the environment variables,
     rather than prompting for input."""
 
+    triggered_block_task_ids: set[str] = set()
+    """A set of block task IDs that have been triggered during the lifetime of this client instance."""
+
     info: dict[str, Any] = {}
     """The `data` response from the `/info` endpoint of the Datalab API."""
 
@@ -82,7 +85,7 @@ class BaseDatalabClient(metaclass=AutoPrettyPrint):
         self.log = logging.getLogger(__name__)
 
         self._http_client = httpx.Client
-        self._headers["User-Agent"] = f"Datalab Python API/{__version__}"
+        self._headers = {"User-Agent": f"Datalab Python API/{__version__}"}
 
         self._detect_api_url()
 
@@ -226,14 +229,14 @@ class BaseDatalabClient(metaclass=AutoPrettyPrint):
             self._session.close()
 
     def _handle_response(
-        self, response: httpx.Response, url: str, expected_status: int = 200
+        self, response: httpx.Response, url: str, expected_status: Union[int, list[int]] = 200
     ) -> dict[str, Any]:
         """Handle HTTP response with consistent error handling.
 
         Args:
             response: The HTTP response object
             url: The URL that was requested
-            expected_status: The expected HTTP status code (default: 200)
+            expected_status: The expected HTTP status code(s) (default: 200)
 
         Returns:
             The JSON response data
@@ -259,7 +262,10 @@ class BaseDatalabClient(metaclass=AutoPrettyPrint):
             )
 
         # Handle other HTTP status code errors
-        if response.status_code != expected_status:
+        if isinstance(expected_status, int):
+            expected_status = [expected_status]
+
+        if response.status_code not in expected_status:
             try:
                 error_data = response.json()
                 error_message = error_data.get("message", str(response.content))
@@ -321,8 +327,27 @@ This is likely a server-side bug. Please report this issue to the datalab develo
 
         return data
 
+    def check_tasks(self) -> tuple[set[str], set[str]]:
+        """Check the status of any triggered tasks, returning any that have completed."""
+        completed_tasks = set()
+        error_tasks = set()
+
+        for task_id in self.triggered_block_task_ids:
+            try:
+                response = self._get(f"{self.datalab_api_url}/blocks/{task_id}/status")
+                task_status = response["status"]
+                if task_status == "ready":
+                    completed_tasks.add(task_id)
+            except DatalabAPIError:
+                error_tasks.add(task_id)
+
+        self.triggered_block_task_ids -= completed_tasks
+        self.triggered_block_task_ids -= error_tasks
+
+        return completed_tasks, error_tasks
+
     def _request(
-        self, method: str, url: str, expected_status: int = 200, **kwargs
+        self, method: str, url: str, expected_status: Union[int, list[int]] = 200, **kwargs
     ) -> dict[str, Any]:
         """Make an HTTP request with consistent error handling.
 
@@ -335,8 +360,11 @@ This is likely a server-side bug. Please report this issue to the datalab develo
         Returns:
             The JSON response data
         """
+        timeout = kwargs.pop("timeout", None)
         try:
-            response = self.session.request(method, url, follow_redirects=True, **kwargs)
+            response = self.session.request(
+                method, url, follow_redirects=True, timeout=timeout, **kwargs
+            )
             return self._handle_response(response, url, expected_status)
         except (httpx.RequestError, httpx.HTTPStatusError) as e:
             raise DatalabAPIError(f"Request failed for {url}: {e}")
@@ -345,7 +373,9 @@ This is likely a server-side bug. Please report this issue to the datalab develo
         """Make a GET request with error handling."""
         return self._request("GET", url, **kwargs)
 
-    def _post(self, url: str, expected_status: int = 200, **kwargs) -> dict[str, Any]:
+    def _post(
+        self, url: str, expected_status: Union[int, list[int]] = 200, **kwargs
+    ) -> dict[str, Any]:
         """Make a POST request with error handling."""
         return self._request("POST", url, expected_status, **kwargs)
 

{datalab_api-0.3.2 → datalab_api-0.5.0/src/datalab_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datalab-api
-Version: 0.3.2
+Version: 0.5.0
 Summary: A Python API for instances of the datalab data management platform (https://github.com/datalab-org/datalab).
 Author-email: Matthew Evans <matthew@ml-evs.science>
 License-Expression: MIT
@@ -13,6 +13,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Information Technology
 Classifier: Topic :: Other/Nonlisted Topic
@@ -38,9 +39,6 @@ Requires-Dist: mkdocs-jupyter; extra == "docs"
 Provides-Extra: cli
 Requires-Dist: typer~=0.9; extra == "cli"
 Requires-Dist: click-shell~=2.1; extra == "cli"
-Provides-Extra: cheminventory-helper
-Requires-Dist: pandas~=2.2; extra == "cheminventory-helper"
-Requires-Dist: openpyxl~=3.0; extra == "cheminventory-helper"
 Provides-Extra: all
 Requires-Dist: datalab-api[cli,dev,docs]; extra == "all"
 Dynamic: license-file

{datalab_api-0.3.2 → datalab_api-0.5.0}/src/datalab_api.egg-info/SOURCES.txt

@@ -4,7 +4,6 @@ pyproject.toml
 src/datalab_api/__init__.py
 src/datalab_api/_base.py
 src/datalab_api/cli.py
-src/datalab_api/helpers.py
 src/datalab_api/utils.py
 src/datalab_api.egg-info/PKG-INFO
 src/datalab_api.egg-info/SOURCES.txt

{datalab_api-0.3.2 → datalab_api-0.5.0}/src/datalab_api.egg-info/requires.txt

@@ -8,10 +8,6 @@ bokeh~=2.4
 [all]
 datalab-api[cli,dev,docs]
 
-[cheminventory-helper]
-pandas~=2.2
-openpyxl~=3.0
-
 [cli]
 typer~=0.9
 click-shell~=2.1

{datalab_api-0.3.2 → datalab_api-0.5.0}/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"

datalab_api-0.3.2/src/datalab_api/helpers.py

@@ -1,60 +0,0 @@
-import random
-import warnings
-from pathlib import Path
-
-from datalab_api import DatalabClient, DuplicateItemError
-
-
-def import_cheminventory(filename: Path, client: DatalabClient):
-    """Helper function to import a ChemInventory xlsx export into datalab, using the
-    'starting_materials' item type.
-
-    Migrated from the original version in the main datalab repository:
-        https://github.com/the-grey-group/datalab/blob/43764fb494c2cc1bf9f7dc90c25594aeb79d5767/pydatalab/tasks.py#L350-L413
-
-    """
-
-    warnings.warn(
-        DeprecationWarning(
-            "This helper is deprecated in favour of the full-fledged plugin at: https://github.com/datalab-industries/datalab-cheminventory-plugin"
-        )
-    )
-
-    def _generate_random_startingmaterial_id():
-        """Generate 'XX' + a random 15-length string for use as an id for starting materials
-        that don't have a barcode.
-        """
-        yield "".join(["XX"] + random.choices("abcdefghijklmnopqrstuvwxyz0123456789", k=15))
-
-    try:
-        import pandas as pd
-
-        inventory_df = pd.read_excel(filename)
-    except ImportError as exc:
-        raise ImportError(
-            "Please install pandas + openpyxl to use this helper function, via `pip install datalab-api[cheminventory-helper]`"
-        ) from exc
-    inventory_df["type"] = "starting_materials"
-    inventory_df["item_id"] = inventory_df["Barcode"]
-    # Fill missing barcodes
-    inventory_df["item_id"] = inventory_df["item_id"].fillna(
-        inventory_df["item_id"].apply(lambda _: next(_generate_random_startingmaterial_id()))
-    )
-    inventory_df["Molecular Weight"] = inventory_df["Molecular Weight"].replace(" ", float("nan"))
-
-    counts = {"success": 0, "duplicate": 0, "failed": 0}
-
-    for item in inventory_df.to_dict(orient="records"):
-        try:
-            client.create_item(
-                item["item_id"], item["type"], item, collection_id="jul24-inventory-import"
-            )
-            counts["success"] += 1
-        except DuplicateItemError:
-            counts["duplicate"] += 1
-        except Exception as exc:
-            counts["failed"] += 1
-            print(f"Failed to import item: {item}. Error: {exc}")
-            continue
-
-    print(f"Done: {counts=}")