datalab-api 0.2.3__tar.gz → 0.2.5__tar.gz

{datalab_api-0.2.3/src/datalab_api.egg-info → datalab_api-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: datalab-api
-Version: 0.2.3
+Version: 0.2.5
 Summary: A Python API for instances of the datalab data management platform (https://github.com/the-grey-group/datalab).
 Author-email: Matthew Evans <matthew@ml-evs.science>
 License: MIT
@@ -38,6 +38,9 @@ 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"
 
@@ -96,7 +99,7 @@ You can generate one for your account for a given *datalab* instance by visiting
 
 This API key can be set via the environment variable `DATALAB_API_KEY`.
 To suport the use case of needing to interact with multiple datalab instances, the client will also check prefixed environment variables that use the [`IDENTIFIER_PREFIX` of the chosen datalab instance](https://the-datalab.readthedocs.io/en/latest/config/#mandatory-settings), e.g., `GREY_DATALAB_API_KEY` or `PUBLIC_DATALAB_API_KEY`.
-Only keys that match will be read (e.g., other environment variables starting with `PUBLIC_` will be ignored, when connecting to the [public demo datalab](https://public.datalab.odbx.science)).
+Only keys that match will be read (e.g., other environment variables starting with `PUBLIC_` will be ignored, when connecting to the [public demo datalab](https://demo.datalab-org.io)).
 
 ### Python API
 
@@ -105,7 +108,7 @@ This package implements basic functionality for displaying and manipulating entr
 ```python
 from datalab_api import DatalabClient
 
-with DatalabClient("https://public.api.odbx.science") as client:
+with DatalabClient("https://demo-api.datalab-org.io") as client:
 
     # List all items of a given type
     items = client.get_items()
@@ -164,7 +167,7 @@ datalab > help get
 │ --help                       Show this message and exit.                                            │
 ╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯
 
-datalab > get samples api.odbx.science --page-limit 2
+datalab > get samples demo-api.datalab-org.io --page-limit 2
                                                     /samples/
 ┏━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
 ┃ type ┃ ID              ┃ refcode     ┃ name                           ┃ nblocks ┃ collections ┃ creators      ┃

{datalab_api-0.2.3 → datalab_api-0.2.5}/README.md

@@ -53,7 +53,7 @@ You can generate one for your account for a given *datalab* instance by visiting
 
 This API key can be set via the environment variable `DATALAB_API_KEY`.
 To suport the use case of needing to interact with multiple datalab instances, the client will also check prefixed environment variables that use the [`IDENTIFIER_PREFIX` of the chosen datalab instance](https://the-datalab.readthedocs.io/en/latest/config/#mandatory-settings), e.g., `GREY_DATALAB_API_KEY` or `PUBLIC_DATALAB_API_KEY`.
-Only keys that match will be read (e.g., other environment variables starting with `PUBLIC_` will be ignored, when connecting to the [public demo datalab](https://public.datalab.odbx.science)).
+Only keys that match will be read (e.g., other environment variables starting with `PUBLIC_` will be ignored, when connecting to the [public demo datalab](https://demo.datalab-org.io)).
 
 ### Python API
 
@@ -62,7 +62,7 @@ This package implements basic functionality for displaying and manipulating entr
 ```python
 from datalab_api import DatalabClient
 
-with DatalabClient("https://public.api.odbx.science") as client:
+with DatalabClient("https://demo-api.datalab-org.io") as client:
 
     # List all items of a given type
     items = client.get_items()
@@ -121,7 +121,7 @@ datalab > help get
 │ --help                       Show this message and exit.                                            │
 ╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯
 
-datalab > get samples api.odbx.science --page-limit 2
+datalab > get samples demo-api.datalab-org.io --page-limit 2
                                                     /samples/
 ┏━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
 ┃ type ┃ ID              ┃ refcode     ┃ name                           ┃ nblocks ┃ collections ┃ creators      ┃

{datalab_api-0.2.3 → datalab_api-0.2.5}/pyproject.toml

@@ -50,6 +50,11 @@ cli = [
     "click-shell ~= 2.1", # REPL-like interface
 ]
 
+cheminventory-helper = [
+    "pandas ~= 2.2",
+    "openpyxl ~= 3.0"
+]
+
 all = [
     "datalab-api[dev,docs,cli]"
 ]
@@ -75,13 +80,96 @@ follow_imports = "skip"
 
 [tool.ruff]
 line-length = 100
-target-version = "py310"
+target-version = "py39"
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "W", "Q"]
-ignore = ["E501", "E402"]
+select = ["ALL"]
+ignore = [
+    "A001",
+    "A002",
+    "ANN",     # TODO fix all ANN errors
+    "ARG",     # TODO fix unused method argument
+    "B007",
+    "B028",
+    "B904",
+    "BLE001",
+    "C408",    # Unnecessary (dict/list/tuple) call - remove call
+    "C416",
+    "C419",
+    "C901",    # function too complex
+    "COM812",  # trailing comma missing
+    "D",
+    "D205",
+    "DTZ",     # datetime-tz-now
+    "E501",    # TODO fix line too long
+    "EM",      # exception message must not use f-string literal
+    "ERA001",  # found commented out code
+    "FA100",   # TODO fix FA errors
+    "FBT001",
+    "FBT002",
+    "FBT003",
+    "FIX002",
+    "G004",    # logging uses fstring
+    "G201",
+    "INP001",
+    "ISC001",
+    "N802",    # TODO maybe fix these
+    "N805",
+    "N818",
+    "PD011",   # pandas-use-of-dot-values
+    "PERF102",
+    "PERF203", # try-except-in-loop
+    "PERF401",
+    "PGH003",
+    "PGH004",
+    "PLR",     # pylint-refactor
+    "PLW0602",
+    "PLW0603",
+    "PLW2901",
+    "PT003",
+    "PT004",   # pytest-missing-fixture-name-underscore
+    "PT006",   # pytest-parametrize-names-wrong-type
+    "PT013",   # pytest-incorrect-pytest-import
+    "PTH",     # prefer Pathlib to os.path
+    "PYI024",
+    "RET",
+    "RET504",
+    "RUF005",
+    "RUF012",
+    "RUF013",  # implicit-optional
+    "RUF015",
+    "S106",
+    "S110",
+    "S112",
+    "S311",
+    "S324",    # use of insecure hash function
+    "S507",    # paramiko auto trust
+    "S602",
+    "S603",
+    "S607",
+    "SIM102",
+    "SIM105",
+    "SIM108",
+    "SIM117",
+    "SLF",     # private member accessed outside class
+    "SLOT000",
+    "T201",
+    "TCH",
+    "TD",      # TODOs
+    "TRY",     # long message outside exception class
+    "UP031",
+]
+pydocstyle.convention = "numpy"
+isort.known-first-party = ["jobflow_remote"]
+isort.split-on-trailing-comma = false
 fixable = ["A", "B", "C", "D", "E", "F", "I"]
 unfixable = []
-per-file-ignores = {}
 # Allow unused variables when underscore-prefixed.
 dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+"**/tests/*" = ["INP001", "S101"]

{datalab_api-0.2.3 → datalab_api-0.2.5}/src/datalab_api/__init__.py

@@ -1,4 +1,7 @@
+from __future__ import annotations
+
 import warnings
+from collections.abc import Iterable
 from pathlib import Path
 from typing import Any, Optional, Union
 
@@ -7,6 +10,10 @@ from ._base import BaseDatalabClient, __version__
 __all__ = ("__version__", "DatalabClient")
 
 
+class DuplicateItemError(ValueError):
+    """Raised when the API operation would create a duplicate item."""
+
+
 class DatalabClient(BaseDatalabClient):
     """A client for the Datalab API.
 
@@ -14,7 +21,7 @@ class DatalabClient(BaseDatalabClient):
     amenable for use as a context manager, e.g.,
 
     ```python
-    with DatalabClient("https://public.api.odbx.science") as client:
+    with DatalabClient("https://demo-api.datalab-org.io") as client:
         client.get_items()
     ```
 
@@ -41,7 +48,7 @@ class DatalabClient(BaseDatalabClient):
             )
         return user_resp.json()
 
-    def get_items(self, item_type: Optional[str] = "samples") -> list[dict[str, Any]]:
+    def get_items(self, item_type: str | None = "samples") -> list[dict[str, Any]]:
         """List items of the given type available to the authenticated user.
 
         Parameters:
@@ -66,7 +73,7 @@ class DatalabClient(BaseDatalabClient):
         return items[item_type]
 
     def search_items(
-        self, query: str, item_types: Union[list[str], str] = ["samples", "cells"]
+        self, query: str, item_types: Iterable[str] | str = ("samples", "cells")
     ) -> list[dict[str, Any]]:
         """Search for items of the given types that match the query.
 
@@ -96,39 +103,55 @@ class DatalabClient(BaseDatalabClient):
         return items["items"]
 
     def create_item(
-        self, item_id: str, item_type: str, item_data: Optional[dict[str, Any]] = None
+        self,
+        item_id: str | None = None,
+        item_type: str = "samples",
+        item_data: dict[str, Any] | None = None,
+        collection_id: str | None = None,
     ) -> dict[str, Any]:
         """Create an item with a given ID and item data.
 
         Parameters:
-            item_id: The ID of the item to create.
+            item_id: The ID of the item to create, if set to `None`, the server will generate one.
             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.
 
         """
         new_item = {}
         if item_data is not None:
             new_item = item_data
-        new_item.update(**{"item_id": item_id, "type": item_type})
+        new_item.update({"item_id": item_id, "type": item_type})
+
+        if collection_id is not None:
+            try:
+                collection_immutable_id = self.get_collection(collection_id)["immutable_id"]
+            except RuntimeError:
+                collection_immutable_id = self.create_collection(collection_id)["immutable_id"]
+            new_item["collections"] = new_item.get("collections", [])
+            new_item["collections"].append({"immutable_id": collection_immutable_id})
 
         create_item_url = f"{self.datalab_api_url}/new-sample/"
         create_item_resp = self.session.post(
             create_item_url,
-            json=new_item,
+            json={"new_sample_data": new_item, "generate_id_automatically": item_id is None},
             follow_redirects=True,
         )
         try:
             created_item = create_item_resp.json()
-            if created_item["status"] != "success":
-                raise RuntimeError(
-                    f"Failed to create item at {create_item_url}: {created_item['status']!r}."
+            if create_item_resp.status_code == 409:
+                raise DuplicateItemError(
+                    f"Item {item_id=} already exists at {create_item_url}: {created_item['status']!r}."
                 )
+            if created_item["status"] != "success":
+                raise RuntimeError(f"Failed to create item at {create_item_url}: {created_item}.")
             return created_item["sample_list_entry"]
 
-        except Exception:
-            raise RuntimeError(
-                f"Failed to create item {item_id=} with data {item_data=} at {create_item_url}: {create_item_resp.status_code=}. Check the item information is correct."
-            )
+        except Exception as exc:
+            raise exc.__class__(
+                f"Failed to create item {item_id=} with data {item_data=} at {create_item_url}: {create_item_resp.status_code=}, {create_item_resp.content}. Check the item information is correct."
+            ) from exc
 
     def update_item(self, item_id: str, item_data: dict[str, Any]) -> dict[str, Any]:
         """Update an item with the given item data.
@@ -161,8 +184,8 @@ class DatalabClient(BaseDatalabClient):
 
     def get_item(
         self,
-        item_id: Optional[str] = None,
-        refcode: Optional[str] = None,
+        item_id: str | None = None,
+        refcode: str | None = None,
         load_blocks: bool = False,
     ) -> dict[str, Any]:
         """Get an item with a given ID or refcode.
@@ -266,7 +289,7 @@ class DatalabClient(BaseDatalabClient):
             raise RuntimeError(f"Failed to get block at {block_url}: {block['status']!r}.")
         return block["new_block_data"]
 
-    def upload_file(self, item_id: str, file_path: Union[Path, str]) -> dict[str, Any]:
+    def upload_file(self, item_id: str, file_path: Path | str) -> dict[str, Any]:
         """Upload a file to an item with a given ID.
 
         Parameters:
@@ -306,8 +329,8 @@ class DatalabClient(BaseDatalabClient):
         self,
         item_id: str,
         block_type: str,
-        file_ids: Optional[Union[str, list[str]]] = None,
-        file_paths: Optional[Union[Path, list[Path]]] = None,
+        file_ids: str | list[str] | None = None,
+        file_paths: Path | list[Path] | None = None,
     ) -> dict[str, Any]:
         """Creates a data block for an item with the given block type and file ID.
 
@@ -364,7 +387,7 @@ class DatalabClient(BaseDatalabClient):
         return block_data
 
     def _update_data_block(
-        self, block_type: str, block_data: dict, file_ids: Optional[Union[str, list[str]]] = None
+        self, block_type: str, block_data: dict, file_ids: str | list[str] | None = None
     ) -> dict[str, Any]:
         """Attaches files to blocks: should only be used via wrapper methods."""
         if file_ids and isinstance(file_ids, str):
@@ -390,3 +413,57 @@ class DatalabClient(BaseDatalabClient):
             raise RuntimeError(f"Failed to update block {block_type=}:\n{resp.text}")
 
         return resp.json()["new_block_data"]
+
+    def get_collection(self, collection_id: str) -> dict[str, Any]:
+        """Get a collection with a given ID.
+
+        Parameters:
+            collection_id: The ID of the collection to search for.
+
+        Returns:
+            A dictionary of collection data for the collection with the given ID.
+
+        """
+        collection_url = f"{self.datalab_api_url}/collections/{collection_id}"
+        collection_resp = self.session.get(collection_url, follow_redirects=True)
+        if collection_resp.status_code != 200:
+            raise RuntimeError(
+                f"Failed to find collection {collection_id=} at {collection_url}: {collection_resp.status_code=}. Check the collection ID is correct."
+            )
+        collection = collection_resp.json()
+        if collection["status"] != "success":
+            raise RuntimeError(
+                f"Failed to get collection at {collection_url}: {collection['status']!r}."
+            )
+        return collection["data"]
+
+    def create_collection(
+        self, collection_id: str, collection_data: dict | None = None
+    ) -> dict[str, Any]:
+        """Create a collection with a given ID and collection data.
+
+        Parameters:
+            collection_id: The ID of the collection to create.
+            collection_data: The data for the collection.
+
+        """
+        collection_url = f"{self.datalab_api_url}/collections"
+
+        new_collection = {}
+        if collection_data is not None:
+            new_collection = collection_data
+        new_collection.update({"collection_id": collection_id, "type": "collections"})
+
+        collection_resp = self.session.put(
+            collection_url,
+            json={"data": new_collection},
+            follow_redirects=True,
+        )
+
+        if collection_resp.status_code != 201 or collection_resp.json()["status"] != "success":
+            raise RuntimeError(
+                f"Failed to create collection {collection_id=} at {collection_url}: {collection_resp.status_code=}. Check the collection information is correct: {collection_resp.content}"
+            )
+
+        created_collection = collection_resp.json()["data"]
+        return created_collection

{datalab_api-0.2.3 → datalab_api-0.2.5}/src/datalab_api/_base.py

@@ -76,10 +76,7 @@ def bokeh_from_json(block_data, show=True):
     from bokeh.io import curdoc
     from bokeh.plotting import show as bokeh_show
 
-    if "bokeh_plot_data" in block_data:
-        bokeh_plot_data = block_data["bokeh_plot_data"]
-    else:
-        bokeh_plot_data = block_data
+    bokeh_plot_data = block_data.get("bokeh_plot_data", block_data)
     curdoc().replace_with_json(bokeh_plot_data["doc"])
     if show:
         bokeh_show(curdoc().roots[0])
@@ -116,8 +113,8 @@ class BaseDatalabClient(metaclass=AutoPrettyPrint):
         Parameters:
             datalab_api_url: The URL of the Datalab API.
                 TODO: If the URL of a datalab *UI* is provided, a request will be made to attempt
-                to resolve the underlying API URL (e.g., `https://public.datalab.odbx.science`
-                will 'redirect' to `https://public.api.odbx.science`).
+                to resolve the underlying API URL (e.g., `https://demo-api.datalab-org.io`
+                will 'redirect' to `https://demo-api.datalab-org.io`).
             log_level: The logging level to use for the client. Defaults to "WARNING".
 
 

datalab_api-0.2.5/src/datalab_api/helpers.py

@@ -0,0 +1,53 @@
+import random
+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
+
+    """
+
+    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=}")

{datalab_api-0.2.3 → datalab_api-0.2.5/src/datalab_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: datalab-api
-Version: 0.2.3
+Version: 0.2.5
 Summary: A Python API for instances of the datalab data management platform (https://github.com/the-grey-group/datalab).
 Author-email: Matthew Evans <matthew@ml-evs.science>
 License: MIT
@@ -38,6 +38,9 @@ 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"
 
@@ -96,7 +99,7 @@ You can generate one for your account for a given *datalab* instance by visiting
 
 This API key can be set via the environment variable `DATALAB_API_KEY`.
 To suport the use case of needing to interact with multiple datalab instances, the client will also check prefixed environment variables that use the [`IDENTIFIER_PREFIX` of the chosen datalab instance](https://the-datalab.readthedocs.io/en/latest/config/#mandatory-settings), e.g., `GREY_DATALAB_API_KEY` or `PUBLIC_DATALAB_API_KEY`.
-Only keys that match will be read (e.g., other environment variables starting with `PUBLIC_` will be ignored, when connecting to the [public demo datalab](https://public.datalab.odbx.science)).
+Only keys that match will be read (e.g., other environment variables starting with `PUBLIC_` will be ignored, when connecting to the [public demo datalab](https://demo.datalab-org.io)).
 
 ### Python API
 
@@ -105,7 +108,7 @@ This package implements basic functionality for displaying and manipulating entr
 ```python
 from datalab_api import DatalabClient
 
-with DatalabClient("https://public.api.odbx.science") as client:
+with DatalabClient("https://demo-api.datalab-org.io") as client:
 
     # List all items of a given type
     items = client.get_items()
@@ -164,7 +167,7 @@ datalab > help get
 │ --help                       Show this message and exit.                                            │
 ╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯
 
-datalab > get samples api.odbx.science --page-limit 2
+datalab > get samples demo-api.datalab-org.io --page-limit 2
                                                     /samples/
 ┏━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
 ┃ type ┃ ID              ┃ refcode     ┃ name                           ┃ nblocks ┃ collections ┃ creators      ┃

{datalab_api-0.2.3 → datalab_api-0.2.5}/src/datalab_api.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ 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.egg-info/PKG-INFO
 src/datalab_api.egg-info/SOURCES.txt
 src/datalab_api.egg-info/dependency_links.txt

{datalab_api-0.2.3 → datalab_api-0.2.5}/src/datalab_api.egg-info/requires.txt

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