datalab-api 0.5.3__tar.gz → 0.6.0__tar.gz

{datalab_api-0.5.3/src/datalab_api.egg-info → datalab_api-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datalab-api
-Version: 0.5.3
+Version: 0.6.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
@@ -9,7 +9,6 @@ Project-URL: repository, https://github.com/datalab-org/datalab-api
 Project-URL: documentation, https://datalab-python-api.readthedocs.io
 Project-URL: changelog, https://github.com/datalab-org/datalab-api/releases
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -18,13 +17,16 @@ Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Information Technology
 Classifier: Topic :: Other/Nonlisted Topic
 Classifier: Topic :: Scientific/Engineering
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: httpx~=0.28
-Requires-Dist: bokeh~=2.4; platform_system != "Emscripten"
+Requires-Dist: httpx2~=2.13
 Requires-Dist: rich<15,>=13
-Requires-Dist: numpy<2
+Provides-Extra: plotting
+Requires-Dist: bokeh~=2.4; platform_system != "Emscripten" and extra == "plotting"
+Requires-Dist: numpy<2; extra == "plotting"
+Provides-Extra: networkx
+Requires-Dist: networkx>=3; extra == "networkx"
 Provides-Extra: dev
 Requires-Dist: pre-commit<5,>=3; extra == "dev"
 Requires-Dist: pytest~=8.0; extra == "dev"
@@ -108,7 +110,6 @@ This package implements basic functionality for displaying and manipulating entr
 from datalab_api import DatalabClient
 
 with DatalabClient("https://demo-api.datalab-org.io") as client:
-
     # List all items of a given type
     items = client.get_items()
 
@@ -117,7 +118,6 @@ with DatalabClient("https://demo-api.datalab-org.io") as client:
 
     # Upload a file to an item
     file_response = client.upload_file(filepath="my_echem_data.mpr", item_id="test")
-
 ```
 
 ### Elevated (admin) permissions
@@ -126,9 +126,7 @@ By default a client can only see items its account owns or has been shared on.
 Admins can opt in to datalab's super-user mode to read items belonging to other users, by passing `elevate_permissions`:
 
 ```python
-with DatalabClient(
-    "https://demo-api.datalab-org.io", elevate_permissions=True
-) as client:
+with DatalabClient("https://demo-api.datalab-org.io", elevate_permissions=True) as client:
     # Finds the item even if it belongs to another user
     item = client.get_item(item_id="someone-elses-sample")
 ```

{datalab_api-0.5.3 → datalab_api-0.6.0}/README.md

@@ -63,7 +63,6 @@ This package implements basic functionality for displaying and manipulating entr
 from datalab_api import DatalabClient
 
 with DatalabClient("https://demo-api.datalab-org.io") as client:
-
     # List all items of a given type
     items = client.get_items()
 
@@ -72,7 +71,6 @@ with DatalabClient("https://demo-api.datalab-org.io") as client:
 
     # Upload a file to an item
     file_response = client.upload_file(filepath="my_echem_data.mpr", item_id="test")
-
 ```
 
 ### Elevated (admin) permissions
@@ -81,9 +79,7 @@ By default a client can only see items its account owns or has been shared on.
 Admins can opt in to datalab's super-user mode to read items belonging to other users, by passing `elevate_permissions`:
 
 ```python
-with DatalabClient(
-    "https://demo-api.datalab-org.io", elevate_permissions=True
-) as client:
+with DatalabClient("https://demo-api.datalab-org.io", elevate_permissions=True) as client:
     # Finds the item even if it belongs to another user
     item = client.get_item(item_id="someone-elses-sample")
 ```

{datalab_api-0.5.3 → datalab_api-0.6.0}/pyproject.toml

@@ -12,7 +12,6 @@ authors = [{ name = "Matthew Evans", email = "matthew@ml-evs.science" }]
 dynamic = ["version"]
 classifiers = [
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -23,16 +22,23 @@ classifiers = [
     "Topic :: Scientific/Engineering",
 ]
 
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 dependencies = [
-    "httpx ~= 0.28",                                 # better HTTP requests
-    'bokeh ~= 2.4; platform_system != "Emscripten"', # interactive plots from datalab directly
+    "httpx2 ~= 2.13",                                 # better HTTP requests
     "rich >= 13,< 15",                                  # nicer terminal output
-    "numpy < 2",                                     # upper pin for numpy due to bad pins in bokeh
 ]
 
 
 [project.optional-dependencies]
+plotting = [
+    "bokeh ~= 2.4; platform_system != 'Emscripten'", # interactive plots from datalab directly
+    "numpy < 2",                                     # upper pin for numpy due to bad pins in bokeh
+]
+
+networkx = [
+    "networkx >= 3",                                 # build graphs of item relationships
+]
+
 dev = [
     "pre-commit >= 3,< 5",
     "pytest ~= 8.0",
@@ -78,7 +84,7 @@ follow_imports = "skip"
 
 [tool.ruff]
 line-length = 100
-target-version = "py39"
+target-version = "py310"
 
 [tool.ruff.lint]
 select = ["ALL"]
@@ -96,6 +102,7 @@ ignore = [
     "C419",
     "C901",    # function too complex
     "COM812",  # trailing comma missing
+    "CPY001",  # missing copyright notice
     "D",
     "D205",
     "DTZ",     # datetime-tz-now
@@ -120,6 +127,7 @@ ignore = [
     "PERF401",
     "PGH003",
     "PGH004",
+    "PLC0415", # import not at top-level (used for lazy optional deps)
     "PLR",     # pylint-refactor
     "PLW0602",
     "PLW0603",
@@ -157,7 +165,7 @@ ignore = [
     "UP031",
 ]
 pydocstyle.convention = "numpy"
-isort.known-first-party = ["jobflow_remote"]
+isort.known-first-party = ["datalab_api"]
 isort.split-on-trailing-comma = false
 fixable = ["A", "B", "C", "D", "E", "F", "I", "PT", "RUF"]
 unfixable = []

{datalab_api-0.5.3 → datalab_api-0.6.0}/src/datalab_api/__init__.py

@@ -3,11 +3,15 @@ from __future__ import annotations
 import warnings
 from collections.abc import Iterable
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import TYPE_CHECKING, Any, Optional, Union
 
 import httpx
 
 from ._base import BaseDatalabClient, DatalabAPIError, DuplicateItemError, __version__
+from .utils import networkx_from_item_graph
+
+if TYPE_CHECKING:
+    import networkx as nx
 
 __all__ = ("DatalabClient", "DuplicateItemError", "__version__")
 
@@ -253,6 +257,59 @@ class DatalabClient(BaseDatalabClient):
 
         return item["item_data"]
 
+    def get_item_graph(
+        self,
+        item_id: str | None = None,
+        collection_id: str | None = None,
+        hide_collections: bool | None = None,
+        max_depth: int | None = None,
+        as_networkx: bool = False,
+    ) -> dict[str, list[dict[str, Any]]] | nx.DiGraph:
+        """Get the graph of relationships between items.
+
+        With no arguments, the global item graph for all items visible to the
+        authenticated user is returned. If `item_id` is provided, only the
+        neighbourhood of that item is returned.
+
+        Parameters:
+            item_id: The ID of the item to centre the graph on (optional).
+                If not provided, the global graph is returned.
+            collection_id: Restrict the global graph to members of this
+                collection (optional; ignored when `item_id` is provided).
+            hide_collections: Whether to omit collections as nodes in the graph.
+                If `None`, the server default is used (hidden, for recent versions).
+            max_depth: The number of relationship hops to follow from `item_id`.
+                If `None`, the server default is used (1). Requires a recent
+                version of datalab.
+            as_networkx: Whether to return the graph as a `networkx.DiGraph`
+                (requires the optional `networkx` dependency).
+
+        Returns:
+            A dictionary with `nodes` and `edges` keys, in the Cytoscape.js
+            format used by the datalab UI, or a `networkx.DiGraph` if
+            `as_networkx` is `True`.
+
+        """
+        graph_url = f"{self.datalab_api_url}/item-graph"
+        if item_id is not None:
+            graph_url += f"/{item_id}"
+
+        params: dict[str, Any] = {}
+        if collection_id is not None:
+            params["collection_id"] = collection_id
+        if hide_collections is not None:
+            params["hide_collections"] = str(hide_collections).lower()
+        if max_depth is not None:
+            params["max_depth"] = max_depth
+
+        graph = self._get(graph_url, params=params)
+        graph = {"nodes": graph.get("nodes", []), "edges": graph.get("edges", [])}
+
+        if as_networkx:
+            return networkx_from_item_graph(graph)
+
+        return graph
+
     def get_item_files(self, item_id: str) -> None:
         """Download all the files for a given item and save them locally
         in the current working directory.
@@ -275,8 +332,7 @@ class DatalabClient(BaseDatalabClient):
                 with self.session.stream(
                     "GET", url, follow_redirects=True, **stream_kwargs
                 ) as response:
-                    for chunk in response.iter_bytes(chunk_size=1024):
-                        file.write(chunk)
+                    file.writelines(response.iter_bytes(chunk_size=1024))
 
     def get_block(
         self,

{datalab_api-0.5.3 → datalab_api-0.6.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, Union
+from typing import Any
 
 import httpx
 from rich.logging import RichHandler
@@ -33,8 +33,8 @@ class BaseDatalabClient(metaclass=AutoPrettyPrint):
     readable by users.
     """
 
-    _api_key: Optional[str] = None
-    _session: Optional[httpx.Client] = None
+    _api_key: str | None = None
+    _session: httpx.Client | None = None
     _headers: dict[str, str]
     _timeout: httpx.Timeout = httpx.Timeout(10.0, read=60.0)
 
@@ -52,7 +52,7 @@ class BaseDatalabClient(metaclass=AutoPrettyPrint):
     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),)
+    bad_server_versions: tuple[tuple[int, int, int]] | None = ((0, 2, 0),)
     """Any known server versions that are not supported by this client."""
 
     min_server_version: tuple[int, int, int] = (0, 1, 0)
@@ -113,9 +113,7 @@ class BaseDatalabClient(metaclass=AutoPrettyPrint):
 
         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"
-        )
+        self._datalab_instance_prefix: str | None = self.info["attributes"].get("identifier_prefix")
 
         self._find_api_key()
 
@@ -203,7 +201,7 @@ class BaseDatalabClient(metaclass=AutoPrettyPrint):
         if self._api_key is None:
             key_env_var = "DATALAB_API_KEY"
 
-            api_key: Optional[str] = None
+            api_key: str | None = None
 
             # probe the prefixed environment variable first
             if self._datalab_instance_prefix is not None:
@@ -248,7 +246,7 @@ class BaseDatalabClient(metaclass=AutoPrettyPrint):
             self._session.close()
 
     def _handle_response(
-        self, response: httpx.Response, url: str, expected_status: Union[int, list[int]] = 200
+        self, response: httpx.Response, url: str, expected_status: int | list[int] = 200
     ) -> dict[str, Any]:
         """Handle HTTP response with consistent error handling.
 
@@ -372,7 +370,7 @@ This is likely a server-side bug. Please report this issue to the datalab develo
         return completed_tasks, error_tasks
 
     def _request(
-        self, method: str, url: str, expected_status: Union[int, list[int]] = 200, **kwargs
+        self, method: str, url: str, expected_status: int | list[int] = 200, **kwargs
     ) -> dict[str, Any]:
         """Make an HTTP request with consistent error handling.
 
@@ -415,9 +413,7 @@ 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: Union[int, list[int]] = 200, **kwargs
-    ) -> dict[str, Any]:
+    def _post(self, url: str, expected_status: 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.5.3 → datalab_api-0.6.0}/src/datalab_api/cli.py

@@ -1,5 +1,6 @@
+import random
 import time
-from typing import Annotated, Optional
+from typing import Annotated
 
 import typer
 from click_shell import make_click_shell
@@ -23,7 +24,7 @@ console = Console()
 @app.callback(invoke_without_command=True)
 def launch(
     ctx: typer.Context,
-    instance_url: Annotated[Optional[str], typer.Argument()] = None,
+    instance_url: Annotated[str | None, typer.Argument()] = None,
     animate_intro: bool = True,
 ):
     """Makes an interactive REPL-style interface using the subcommands below."""
@@ -68,7 +69,7 @@ def launch(
 
 def _get_client(
     ctx: typer.Context,
-    instance_url: Optional[str] = None,
+    instance_url: str | None = None,
     log_level: str = "WARNING",
 ):
     client = getattr(ctx, "client", None)
@@ -91,7 +92,7 @@ def _get_instance_url(ctx: typer.Context):
 @app.command()
 def authenticate(
     ctx: typer.Context,
-    instance_url: Annotated[Optional[str], typer.Argument()] = None,
+    instance_url: Annotated[str | None, typer.Argument()] = None,
     log_level: str = "WARNING",
 ):
     client = _get_client(ctx, instance_url, log_level)
@@ -105,7 +106,7 @@ def authenticate(
 def get(
     ctx: typer.Context,
     item_type: str,
-    instance_url: Annotated[Optional[str], typer.Argument()] = None,
+    instance_url: Annotated[str | None, typer.Argument()] = None,
     page_limit: int = 10,
     log_level: str = "WARNING",
 ):
@@ -143,8 +144,6 @@ def info(ctx: typer.Context, instance_url: str, log_level: str = "WARNING"):
 
 def _make_fancy_intro(animate=True):
     """Bit of fun, make an animated datalab logo intro to the CLI."""
-    import random
-
     intro_ascii = """
               oooo              o8              o888             oooo
            ooooo888    ooooooo o888oo  ooooooo    888   ooooooo    888ooooo

{datalab_api-0.5.3 → datalab_api-0.6.0}/src/datalab_api/utils.py

@@ -4,7 +4,7 @@ from rich.console import Console
 from rich.pretty import pprint
 from rich.table import Table
 
-__all__ = ("AutoPrettyPrint", "bokeh_from_json", "pretty_displayer")
+__all__ = ("AutoPrettyPrint", "bokeh_from_json", "networkx_from_item_graph", "pretty_displayer")
 
 
 def pretty_displayer(method):
@@ -77,3 +77,39 @@ def bokeh_from_json(block_data, show=True):
         bokeh_show(curdoc().roots[0])
 
     return curdoc()
+
+
+def networkx_from_item_graph(graph):
+    """Convert an item graph, as returned by the `/item-graph` endpoint,
+    into a `networkx.DiGraph`.
+
+    Nodes are keyed by their ID (item ID, or `"Collection: <collection_id>"`
+    for collections), with all other node data stored as attributes.
+    Edges point from parent to child.
+
+    Parameters:
+        graph: A dictionary with `nodes` and `edges` keys in Cytoscape.js format.
+
+    Returns:
+        A `networkx.DiGraph` of the item relationships.
+
+    """
+    try:
+        import networkx as nx
+    except ImportError as exc:
+        raise ImportError(
+            "The `networkx` package is required to create a graph; "
+            "install it with `pip install datalab-api[networkx]`."
+        ) from exc
+
+    nx_graph = nx.DiGraph()
+    for node in graph.get("nodes", []):
+        data = dict(node["data"])
+        nx_graph.add_node(data.pop("id"), **data)
+    for edge in graph.get("edges", []):
+        data = dict(edge["data"])
+        source, target = data.pop("source"), data.pop("target")
+        data.pop("id", None)
+        nx_graph.add_edge(source, target, **data)
+
+    return nx_graph

{datalab_api-0.5.3 → datalab_api-0.6.0/src/datalab_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datalab-api
-Version: 0.5.3
+Version: 0.6.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
@@ -9,7 +9,6 @@ Project-URL: repository, https://github.com/datalab-org/datalab-api
 Project-URL: documentation, https://datalab-python-api.readthedocs.io
 Project-URL: changelog, https://github.com/datalab-org/datalab-api/releases
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -18,13 +17,16 @@ Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Information Technology
 Classifier: Topic :: Other/Nonlisted Topic
 Classifier: Topic :: Scientific/Engineering
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: httpx~=0.28
-Requires-Dist: bokeh~=2.4; platform_system != "Emscripten"
+Requires-Dist: httpx2~=2.13
 Requires-Dist: rich<15,>=13
-Requires-Dist: numpy<2
+Provides-Extra: plotting
+Requires-Dist: bokeh~=2.4; platform_system != "Emscripten" and extra == "plotting"
+Requires-Dist: numpy<2; extra == "plotting"
+Provides-Extra: networkx
+Requires-Dist: networkx>=3; extra == "networkx"
 Provides-Extra: dev
 Requires-Dist: pre-commit<5,>=3; extra == "dev"
 Requires-Dist: pytest~=8.0; extra == "dev"
@@ -108,7 +110,6 @@ This package implements basic functionality for displaying and manipulating entr
 from datalab_api import DatalabClient
 
 with DatalabClient("https://demo-api.datalab-org.io") as client:
-
     # List all items of a given type
     items = client.get_items()
 
@@ -117,7 +118,6 @@ with DatalabClient("https://demo-api.datalab-org.io") as client:
 
     # Upload a file to an item
     file_response = client.upload_file(filepath="my_echem_data.mpr", item_id="test")
-
 ```
 
 ### Elevated (admin) permissions
@@ -126,9 +126,7 @@ By default a client can only see items its account owns or has been shared on.
 Admins can opt in to datalab's super-user mode to read items belonging to other users, by passing `elevate_permissions`:
 
 ```python
-with DatalabClient(
-    "https://demo-api.datalab-org.io", elevate_permissions=True
-) as client:
+with DatalabClient("https://demo-api.datalab-org.io", elevate_permissions=True) as client:
     # Finds the item even if it belongs to another user
     item = client.get_item(item_id="someone-elses-sample")
 ```

{datalab_api-0.5.3 → datalab_api-0.6.0}/src/datalab_api.egg-info/requires.txt

@@ -1,9 +1,5 @@
-httpx~=0.28
+httpx2~=2.13
 rich<15,>=13
-numpy<2
-
-[:platform_system != "Emscripten"]
-bokeh~=2.4
 
 [all]
 datalab-api[cli,dev,docs]
@@ -24,3 +20,12 @@ mkdocs-material
 mkdocstrings[python-legacy]
 mkdocs-awesome-pages-plugin
 mkdocs-jupyter
+
+[networkx]
+networkx>=3
+
+[plotting]
+numpy<2
+
+[plotting:platform_system != "Emscripten"]
+bokeh~=2.4

{datalab_api-0.5.3 → datalab_api-0.6.0}/tests/test_client.py

@@ -1,3 +1,5 @@
+import re
+
 import pytest
 import respx
 from httpx import Response
@@ -40,7 +42,9 @@ def test_sample_operations(mocked_api, fake_api_url):
         # Check that the full server error message is shown for a missing item
         with pytest.raises(
             DatalabAPIError,
-            match="No matching items for match={'item_id': 'TEST'} with current authorization",
+            match=re.escape(
+                "No matching items for match={'item_id': 'TEST'} with current authorization"
+            ),
         ):
             client.get_item("TEST", display=True)
         assert mocked_api["sample-missing-TEST"].called
@@ -57,7 +61,7 @@ def test_collection_get(fake_api_url, mocked_api):
         assert mocked_api["info"].called
         assert mocked_api["info-blocks"].called
 
-        collection, children = client.get_collection("test_collection", display=True)
+        _collection, _children = client.get_collection("test_collection", display=True)
         assert mocked_api["collection-test_collection"].called
 
 
@@ -169,3 +173,32 @@ def test_elevate_permissions_preserves_existing_params(mocked_api, fake_api_url)
     request = mocked_api["sample-KUVEKJ"].calls.last.request
     assert request.url.params.get("load_blocks") == "false"
     assert request.url.params.get("sudo") == "1"
+
+
+def test_get_item_graph(mocked_api, fake_api_url):
+    with DatalabClient(fake_api_url) as client:
+        graph = client.get_item_graph(display=True)
+        assert mocked_api["item-graph"].called
+        assert not mocked_api["item-graph"].calls.last.request.url.params
+        assert len(graph["nodes"]) == 3
+        assert len(graph["edges"]) == 2
+
+        graph = client.get_item_graph(
+            "KUVEKJ", hide_collections=False, max_depth=2, collection_id="test_collection"
+        )
+        params = mocked_api["item-graph-KUVEKJ"].calls.last.request.url.params
+        assert params["hide_collections"] == "false"
+        assert params["max_depth"] == "2"
+        assert params["collection_id"] == "test_collection"
+        assert set(graph) == {"nodes", "edges"}
+
+
+def test_get_item_graph_networkx(mocked_api, fake_api_url):
+    nx = pytest.importorskip("networkx")
+    with DatalabClient(fake_api_url) as client:
+        graph = client.get_item_graph("KUVEKJ", as_networkx=True)
+        assert isinstance(graph, nx.DiGraph)
+        assert set(graph.nodes) == {"parent", "KUVEKJ", "sibling"}
+        assert set(graph.successors("parent")) == {"KUVEKJ", "sibling"}
+        assert graph.nodes["KUVEKJ"]["name"] == "Child"
+        assert graph.nodes["KUVEKJ"]["special"] is True