datalab-api 0.2.6__tar.gz → 0.2.8__tar.gz

{datalab_api-0.2.6/src/datalab_api.egg-info → datalab_api-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: datalab-api
-Version: 0.2.6
+Version: 0.2.8
 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
@@ -24,10 +24,11 @@ License-File: LICENSE
 Requires-Dist: httpx~=0.27
 Requires-Dist: bokeh~=2.4
 Requires-Dist: rich~=13.0
+Requires-Dist: numpy<2
 Provides-Extra: dev
-Requires-Dist: pre-commit~=3.0; extra == "dev"
+Requires-Dist: pre-commit<5,>=3; extra == "dev"
 Requires-Dist: pytest~=8.0; extra == "dev"
-Requires-Dist: pytest-cov~=5.0; extra == "dev"
+Requires-Dist: pytest-cov<7,>=5; extra == "dev"
 Requires-Dist: respx~=0.21; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs; extra == "docs"
@@ -56,11 +57,11 @@ Requires-Dist: datalab-api[cli,dev,docs]; extra == "all"
 <a href="https://pypi.org/datalab-api"><img src="https://img.shields.io/pypi/pyversions/datalab-api?logo=python&label=Python%20versions" /></a>
 </div>
 
-A simple Python API that can interact with [*datalab*](https://github.com/the-grey-group/datalab) instances.
+A simple Python API that can interact with [*datalab*](https://github.com/datalab-org/datalab) instances.
 
 The idea here is to provide a set of utility functions and models for manipulating samples, cells, inventory, files, users and metadata associated with *datalab* entries in an automated way.
 
-This API may not expose all the functionality available in a given *datalab* instance, and the idea would be that this package can support multiple versions of the underlying [*datalab* REST API](https://the-datalab.readthedocs.io/en/latest/rest_api/).
+This API may not expose all the functionality available in a given *datalab* instance, and the idea would be that this package can support multiple versions of the underlying [*datalab* REST API](https://docs.datalab-org.io/en/stable/rest_api/).
 This means that the API is primarily *functional* in nature, as opposed to object-oriented, since *datalab* instances are free to use their own custom data models.
 The available schemas are reported as instance metadata and in the future object-oriented models may be able to be genereated directly in the client (so e.g., the returned data would be Python objects like `Sample` rather than JSON data).
 
@@ -88,9 +89,9 @@ pip install .
 ## Usage
 
 Example usage as a Jupyter notebook can be found in the `examples` directory or
-in the [online documentation](https://datalab-api.readthedocs.io/), as
+in the [online documentation](https://api-docs.datalab-org.io), as
 well as the full [API
-documentation](https://datalab-api.readthedocs.io/en/latest/reference/).
+documentation](https://api-docs.datalab-org.io/en/stable/reference/).
 
 ### Authentication
 
@@ -98,7 +99,7 @@ Currently the only supported authentication method is via an API key.
 You can generate one for your account for a given *datalab* instance by visiting the `/get-api-key` endpoint of your chosen instance, or, if using a recent version of *datalab*, by visiting your account settings in the browser.
 
 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`.
+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://docs.datalab-org.io/en/stable/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://demo.datalab-org.io)).
 
 ### Python API

{datalab_api-0.2.6 → datalab_api-0.2.8}/README.md

@@ -10,11 +10,11 @@
 <a href="https://pypi.org/datalab-api"><img src="https://img.shields.io/pypi/pyversions/datalab-api?logo=python&label=Python%20versions" /></a>
 </div>
 
-A simple Python API that can interact with [*datalab*](https://github.com/the-grey-group/datalab) instances.
+A simple Python API that can interact with [*datalab*](https://github.com/datalab-org/datalab) instances.
 
 The idea here is to provide a set of utility functions and models for manipulating samples, cells, inventory, files, users and metadata associated with *datalab* entries in an automated way.
 
-This API may not expose all the functionality available in a given *datalab* instance, and the idea would be that this package can support multiple versions of the underlying [*datalab* REST API](https://the-datalab.readthedocs.io/en/latest/rest_api/).
+This API may not expose all the functionality available in a given *datalab* instance, and the idea would be that this package can support multiple versions of the underlying [*datalab* REST API](https://docs.datalab-org.io/en/stable/rest_api/).
 This means that the API is primarily *functional* in nature, as opposed to object-oriented, since *datalab* instances are free to use their own custom data models.
 The available schemas are reported as instance metadata and in the future object-oriented models may be able to be genereated directly in the client (so e.g., the returned data would be Python objects like `Sample` rather than JSON data).
 
@@ -42,9 +42,9 @@ pip install .
 ## Usage
 
 Example usage as a Jupyter notebook can be found in the `examples` directory or
-in the [online documentation](https://datalab-api.readthedocs.io/), as
+in the [online documentation](https://api-docs.datalab-org.io), as
 well as the full [API
-documentation](https://datalab-api.readthedocs.io/en/latest/reference/).
+documentation](https://api-docs.datalab-org.io/en/stable/reference/).
 
 ### Authentication
 
@@ -52,7 +52,7 @@ Currently the only supported authentication method is via an API key.
 You can generate one for your account for a given *datalab* instance by visiting the `/get-api-key` endpoint of your chosen instance, or, if using a recent version of *datalab*, by visiting your account settings in the browser.
 
 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`.
+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://docs.datalab-org.io/en/stable/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://demo.datalab-org.io)).
 
 ### Python API

{datalab_api-0.2.6 → datalab_api-0.2.8}/pyproject.toml

@@ -26,14 +26,15 @@ dependencies =[
     "httpx ~= 0.27", # better HTTP requests
     "bokeh ~= 2.4",  # interactive plots from datalab directly
     "rich ~= 13.0",  # nicer terminal output
+    "numpy < 2", # upper pin for numpy due to bad pins in bokeh
 ]
 
 
 [project.optional-dependencies]
 dev = [
-    "pre-commit ~= 3.0",
+    "pre-commit >= 3,< 5",
     "pytest ~= 8.0",
-    "pytest-cov ~= 5.0",
+    "pytest-cov >= 5,< 7",
     "respx ~= 0.21",
 ]
 
@@ -68,11 +69,13 @@ repository = "https://github.com/datalab-org/datalab-api"
 documentation = "https://datalab-python-api.readthedocs.io"
 changelog = "https://github.com/datalab-org/datalab-api/releases"
 
+[tool.uv]
+cache-keys = [{ git = true }]
+
 [tool.versioningit.vcs]
 method = "git"
 default-tag = "0.0.1"
 
-
 [tool.mypy]
 # plugins = "pydantic.mypy"
 ignore_missing_imports = true

{datalab_api-0.2.6 → datalab_api-0.2.8}/src/datalab_api/__init__.py

@@ -30,13 +30,17 @@ class DatalabClient(BaseDatalabClient):
     def get_info(self) -> dict[str, Any]:
         """Fetch metadata associated with this datalab instance.
 
+        The server information is stored on the client and can be accessed
+        by the `info` attribute.
+
         Returns:
             dict: The JSON response from the `/info` endpoint of the Datalab API.
 
         """
         info_url = f"{self.datalab_api_url}/info"
         info_resp = self.session.get(info_url, follow_redirects=True)
-        return info_resp.json()
+        self.info = info_resp.json()["data"]
+        return self.info
 
     def authenticate(self):
         """Tests authentication of the client with the Datalab API."""
@@ -48,6 +52,26 @@ class DatalabClient(BaseDatalabClient):
             )
         return user_resp.json()
 
+    def get_block_info(self) -> list[dict[str, Any]]:
+        """Return the list of available data blocks types for this instance,
+        including some details and descriptions of their usage.
+
+        The block information is stored on the client and can be accessed
+        by the `block_info` attribute.
+
+        Returns:
+            A list of dictionary of block types.
+
+        """
+        block_info_url = f"{self.datalab_api_url}/info/blocks"
+        block_info_resp = self.session.get(block_info_url, follow_redirects=True)
+        if block_info_resp.status_code != 200:
+            raise RuntimeError(
+                f"Failed to list block information at {block_info_url}: {block_info_resp.status_code=}."
+            )
+        self.block_info = block_info_resp.json()["data"]
+        return self.block_info
+
     def get_items(self, item_type: str | None = "samples") -> list[dict[str, Any]]:
         """List items of the given type available to the authenticated user.
 
@@ -131,7 +155,8 @@ class DatalabClient(BaseDatalabClient):
             try:
                 collection_immutable_id = self.get_collection(collection_id)["immutable_id"]
             except RuntimeError:
-                collection_immutable_id = self.create_collection(collection_id)["immutable_id"]
+                self.create_collection(collection_id)
+                collection_immutable_id = self.get_collection(collection_id)["immutable_id"]
             new_item["collections"] = new_item.get("collections", [])
             new_item["collections"].append({"immutable_id": collection_immutable_id})
 
@@ -252,8 +277,7 @@ class DatalabClient(BaseDatalabClient):
 
         item_data = self.get_item(item_id)
         for f in item_data.get("files", []):
-            file_location = f["location"]
-            url = file_location.replace("/app", self.datalab_api_url)
+            url = f"{self.datalab_api_url}/files/{f['immutable_id']}/{f['name']}"
             if Path(f["name"]).exists():
                 warnings.warn(f"Will not overwrite existing file {f['name']}")
                 continue
@@ -389,6 +413,33 @@ class DatalabClient(BaseDatalabClient):
 
         return block_data
 
+    def update_data_block(
+        self, item_id: str, block_id: str, block_type: str, block_data: dict
+    ) -> dict[str, Any]:
+        """Attempts to update a block with the given payload of data,
+        returning the updated block.
+
+        Parameters:
+            item_id: The ID of the item that the block is attached to.
+            block_id: The ID of existing block.
+            block_type: The type of block to update.
+            block_data: The payload of block data to update; will be used to selectively update
+                any fields present, with validation performed by the remote block code itself.
+
+        Returns:
+            If successful, the updated block data.
+
+        Raises:
+            RuntimeError: If the block update fails.
+
+        """
+        payload = {k: v for k, v in block_data.items()}
+        payload["block_id"] = block_id
+        payload["blocktype"] = block_type
+        payload["item_id"] = item_id
+
+        return self._update_data_block(block_type=block_type, block_data=payload)
+
     def _update_data_block(
         self, block_type: str, block_data: dict, file_ids: str | list[str] | None = None
     ) -> dict[str, Any]:
@@ -401,7 +452,6 @@ class DatalabClient(BaseDatalabClient):
                 raise RuntimeError(
                     "API does not currently support attaching multiple files in a block."
                 )
-
             block_data["file_id"] = file_ids[0]
 
         blocks_url = f"{self.datalab_api_url}/update-block/"

{datalab_api-0.2.6 → datalab_api-0.2.8}/src/datalab_api/_base.py

@@ -43,21 +43,24 @@ def pretty_displayer(method):
                 if result:
                     pprint(result, max_length=None, max_string=100, max_depth=3)
             elif isinstance(result, list):
-                table = Table(show_lines=True)
-                table.add_column("type", overflow="crop", justify="center")
-                table.add_column("ID", style="cyan", no_wrap=True)
-                table.add_column("refcode", style="magenta", no_wrap=True)
-                table.add_column("name", width=30, overflow="ellipsis", no_wrap=True)
-                for item in result[:page_limit]:
-                    table.add_row(
-                        item["type"][0].upper(),
-                        item["item_id"],
-                        item["refcode"],
-                        item["name"],
-                        end_section=True,
-                    )
-                console = Console()
-                console.print(table)
+                try:
+                    table = Table(show_lines=True)
+                    table.add_column("type", overflow="crop", justify="center")
+                    table.add_column("ID", style="cyan", no_wrap=True)
+                    table.add_column("refcode", style="magenta", no_wrap=True)
+                    table.add_column("name", width=30, overflow="ellipsis", no_wrap=True)
+                    for item in result[:page_limit]:
+                        table.add_row(
+                            item["type"][0].upper(),
+                            item["item_id"],
+                            item["refcode"],
+                            item["name"],
+                            end_section=True,
+                        )
+                    console = Console()
+                    console.print(table)
+                except Exception:
+                    pprint(result, max_length=None, max_string=100, max_depth=3)
 
         return result
 
@@ -95,6 +98,13 @@ class BaseDatalabClient(metaclass=AutoPrettyPrint):
     _api_key: Optional[str] = None
     _session: Optional[httpx.Client] = None
     _headers: dict[str, str] = {}
+    _timeout: httpx.Timeout = httpx.Timeout(10.0, read=60.0)
+
+    info: dict[str, Any] = {}
+    """The `data` response from the `/info` endpoint of the Datalab API."""
+
+    block_info: list[dict[str, Any]] = []
+    """The `data` response from the `/info/blocks` endpoint of the Datalab API."""
 
     bad_server_versions: Optional[tuple[tuple[int, int, int]]] = ((0, 2, 0),)
     """Any known server versions that are not supported by this client."""
@@ -133,13 +143,12 @@ class BaseDatalabClient(metaclass=AutoPrettyPrint):
 
         self._detect_api_url()
 
-        info_json = self.get_info()
+        self.get_info()
+        self.get_block_info()
 
-        self._datalab_api_versions: list[str] = info_json["data"]["attributes"][
-            "available_api_versions"
-        ]
-        self._datalab_server_version: str = info_json["data"]["attributes"]["server_version"]
-        self._datalab_instance_prefix: Optional[str] = info_json["data"]["attributes"].get(
+        self._datalab_api_versions: list[str] = self.info["attributes"]["available_api_versions"]
+        self._datalab_server_version: str = self.info["attributes"]["server_version"]
+        self._datalab_instance_prefix: Optional[str] = self.info["attributes"].get(
             "identifier_prefix"
         )
 
@@ -169,16 +178,25 @@ class BaseDatalabClient(metaclass=AutoPrettyPrint):
     def get_info(self) -> dict[str, Any]:
         raise NotImplementedError
 
+    def get_block_info(self) -> list[dict[str, Any]]:
+        raise NotImplementedError
+
     @property
     def session(self) -> httpx.Client:
         if self._session is None:
-            return self._http_client(headers=self.headers)
+            return self._http_client(headers=self.headers, timeout=self.timeout)
         return self._session
 
     @property
-    def headers(self):
+    def headers(self) -> dict[str, str]:
+        """Any headers to send with each request to the datalab API."""
         return self._headers
 
+    @property
+    def timeout(self) -> httpx.Timeout:
+        """A timeout object to use for the datalab API session."""
+        return self._timeout
+
     def _version_negotiation(self):
         """Check whether this client is expected to work with this instance.
 

{datalab_api-0.2.6 → datalab_api-0.2.8/src/datalab_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: datalab-api
-Version: 0.2.6
+Version: 0.2.8
 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
@@ -24,10 +24,11 @@ License-File: LICENSE
 Requires-Dist: httpx~=0.27
 Requires-Dist: bokeh~=2.4
 Requires-Dist: rich~=13.0
+Requires-Dist: numpy<2
 Provides-Extra: dev
-Requires-Dist: pre-commit~=3.0; extra == "dev"
+Requires-Dist: pre-commit<5,>=3; extra == "dev"
 Requires-Dist: pytest~=8.0; extra == "dev"
-Requires-Dist: pytest-cov~=5.0; extra == "dev"
+Requires-Dist: pytest-cov<7,>=5; extra == "dev"
 Requires-Dist: respx~=0.21; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs; extra == "docs"
@@ -56,11 +57,11 @@ Requires-Dist: datalab-api[cli,dev,docs]; extra == "all"
 <a href="https://pypi.org/datalab-api"><img src="https://img.shields.io/pypi/pyversions/datalab-api?logo=python&label=Python%20versions" /></a>
 </div>
 
-A simple Python API that can interact with [*datalab*](https://github.com/the-grey-group/datalab) instances.
+A simple Python API that can interact with [*datalab*](https://github.com/datalab-org/datalab) instances.
 
 The idea here is to provide a set of utility functions and models for manipulating samples, cells, inventory, files, users and metadata associated with *datalab* entries in an automated way.
 
-This API may not expose all the functionality available in a given *datalab* instance, and the idea would be that this package can support multiple versions of the underlying [*datalab* REST API](https://the-datalab.readthedocs.io/en/latest/rest_api/).
+This API may not expose all the functionality available in a given *datalab* instance, and the idea would be that this package can support multiple versions of the underlying [*datalab* REST API](https://docs.datalab-org.io/en/stable/rest_api/).
 This means that the API is primarily *functional* in nature, as opposed to object-oriented, since *datalab* instances are free to use their own custom data models.
 The available schemas are reported as instance metadata and in the future object-oriented models may be able to be genereated directly in the client (so e.g., the returned data would be Python objects like `Sample` rather than JSON data).
 
@@ -88,9 +89,9 @@ pip install .
 ## Usage
 
 Example usage as a Jupyter notebook can be found in the `examples` directory or
-in the [online documentation](https://datalab-api.readthedocs.io/), as
+in the [online documentation](https://api-docs.datalab-org.io), as
 well as the full [API
-documentation](https://datalab-api.readthedocs.io/en/latest/reference/).
+documentation](https://api-docs.datalab-org.io/en/stable/reference/).
 
 ### Authentication
 
@@ -98,7 +99,7 @@ Currently the only supported authentication method is via an API key.
 You can generate one for your account for a given *datalab* instance by visiting the `/get-api-key` endpoint of your chosen instance, or, if using a recent version of *datalab*, by visiting your account settings in the browser.
 
 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`.
+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://docs.datalab-org.io/en/stable/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://demo.datalab-org.io)).
 
 ### Python API

{datalab_api-0.2.6 → datalab_api-0.2.8}/src/datalab_api.egg-info/requires.txt

@@ -1,6 +1,7 @@
 httpx~=0.27
 bokeh~=2.4
 rich~=13.0
+numpy<2
 
 [all]
 datalab-api[cli,dev,docs]
@@ -14,9 +15,9 @@ typer~=0.9
 click-shell~=2.1
 
 [dev]
-pre-commit~=3.0
+pre-commit<5,>=3
 pytest~=8.0
-pytest-cov~=5.0
+pytest-cov<7,>=5
 respx~=0.21
 
 [docs]

{datalab_api-0.2.6 → datalab_api-0.2.8}/tests/test_client.py

@@ -5,18 +5,22 @@ from httpx import Response
 
 
 @respx.mock
-def test_redirect_url(fake_ui_html, fake_info_json):
+def test_redirect_url(fake_ui_html, fake_info_json, fake_block_info_json):
     fake_ui = respx.get("https://ui.datalab.industries").mock(
         return_value=Response(200, content=fake_ui_html)
     )
-    fake_api = respx.get("https://api.datalab.industries/info").mock(
+    fake_info_api = respx.get("https://api.datalab.industries/info").mock(
         return_value=Response(200, json=fake_info_json)
     )
+    fake_block_info_api = respx.get("https://api.datalab.industries/info/blocks").mock(
+        return_value=Response(200, json=fake_block_info_json)
+    )
     with pytest.warns(
         UserWarning,
         match="^Found API URL https://api.datalab.industries in HTML meta tag. Creating client with this URL instead.$",
     ):
         client = DatalabClient("https://ui.datalab.industries")
     assert fake_ui.called
-    assert fake_api.called
+    assert fake_info_api.called
+    assert fake_block_info_api.called
     assert client.datalab_api_url == "https://api.datalab.industries"