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

{datalab_api-0.5.2/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.2
+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,9 +118,31 @@ 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
 
+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:
+    # Finds the item even if it belongs to another user
+    item = client.get_item(item_id="someone-elses-sample")
 ```
 
+This sends datalab's `sudo=1` flag on read requests.
+It requires the API key in use to belong to an **admin** account; for any other account the server ignores
+it and normal permissions apply.
+
+The attribute can also be toggled at any point in the client's lifetime:
+
+```python
+client.elevate_permissions = True
+```
+
+Note that objects created while elevated (e.g. uploaded files) are still recorded as belonging to the admin's own account, not the item owner's.
+
 ### Command-line interface (CLI)
 
 There is also an EXPERIMENTAL CLI, exposed via the `datalab` command.

{datalab_api-0.5.2 → 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,9 +71,31 @@ 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
 
+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:
+    # Finds the item even if it belongs to another user
+    item = client.get_item(item_id="someone-elses-sample")
 ```
 
+This sends datalab's `sudo=1` flag on read requests.
+It requires the API key in use to belong to an **admin** account; for any other account the server ignores
+it and normal permissions apply.
+
+The attribute can also be toggled at any point in the client's lifetime:
+
+```python
+client.elevate_permissions = True
+```
+
+Note that objects created while elevated (e.g. uploaded files) are still recorded as belonging to the admin's own account, not the item owner's.
+
 ### Command-line interface (CLI)
 
 There is also an EXPERIMENTAL CLI, exposed via the `datalab` command.

{datalab_api-0.5.2 → 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.2 → 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.
@@ -268,10 +325,14 @@ class DatalabClient(BaseDatalabClient):
             if Path(f["name"]).exists():
                 warnings.warn(f"Will not overwrite existing file {f['name']}")
                 continue
+            # This streams directly from the session rather than going through
+            # `_request`, so the elevation flag has to be applied by hand.
+            stream_kwargs = self._apply_elevation("GET", {})
             with open(f["name"], "wb") as file:
-                with self.session.stream("GET", url, follow_redirects=True) as response:
-                    for chunk in response.iter_bytes(chunk_size=1024):
-                        file.write(chunk)
+                with self.session.stream(
+                    "GET", url, follow_redirects=True, **stream_kwargs
+                ) as response:
+                    file.writelines(response.iter_bytes(chunk_size=1024))
 
     def get_block(
         self,

{datalab_api-0.5.2 → 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,13 +52,28 @@ 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)
     """The minimum supported server version that this client supports."""
 
-    def __init__(self, datalab_api_url: str, log_level: str = "WARNING"):
+    elevate_permissions: bool = False
+    """Whether to make requests in datalab's admin super-user mode, i.e., with
+    access to items belonging to other users.
+
+    This only has an effect if the API key in use belongs to an admin account;
+    for any other account the server ignores the request and normal permissions
+    apply. Can be set at any point in the client's lifetime to toggle the
+    behaviour.
+    """
+
+    def __init__(
+        self,
+        datalab_api_url: str,
+        log_level: str = "WARNING",
+        elevate_permissions: bool = False,
+    ):
         """Creates an authenticated client.
 
         An API key is required to authenticate requests. The client will attempt to load it from a
@@ -72,10 +87,14 @@ class BaseDatalabClient(metaclass=AutoPrettyPrint):
                 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".
+            elevate_permissions: Whether to read items belonging to other users, using
+                datalab's admin super-user mode. Requires the API key in use to belong
+                to an admin account; ignored by the server otherwise. Defaults to False.
 
 
         """
 
+        self.elevate_permissions = elevate_permissions
         self.datalab_api_url = datalab_api_url
         if not self.datalab_api_url:
             raise ValueError("No Datalab API URL provided.")
@@ -94,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()
 
@@ -184,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:
@@ -229,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.
 
@@ -353,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.
 
@@ -367,6 +384,7 @@ This is likely a server-side bug. Please report this issue to the datalab develo
             The JSON response data
         """
         timeout = kwargs.pop("timeout", None)
+        kwargs = self._apply_elevation(method, kwargs)
         try:
             response = self.session.request(
                 method, url, follow_redirects=True, timeout=timeout, **kwargs
@@ -375,13 +393,27 @@ This is likely a server-side bug. Please report this issue to the datalab develo
         except (httpx.RequestError, httpx.HTTPStatusError) as e:
             raise DatalabAPIError(f"Request failed for {url}: {e}")
 
+    def _apply_elevation(self, method: str, kwargs: dict[str, Any]) -> dict[str, Any]:
+        """Add datalab's super-user flag to a read when running elevated.
+
+        datalab treats an admin as an ordinary user on GET requests unless the
+        request opts in with `sudo=1`, but grants them full access on writes
+        with no opt-in at all — so only reads need the flag. Any `params` the
+        caller supplied are preserved.
+        """
+        if not self.elevate_permissions or method.upper() != "GET":
+            return kwargs
+
+        params = dict(kwargs.pop("params", None) or {})
+        params.setdefault("sudo", "1")
+        kwargs["params"] = params
+        return kwargs
+
     def _get(self, url: str, **kwargs) -> dict[str, Any]:
         """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.2 → 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.2 → 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.2 → 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.2
+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,9 +118,31 @@ 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
 
+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:
+    # Finds the item even if it belongs to another user
+    item = client.get_item(item_id="someone-elses-sample")
 ```
 
+This sends datalab's `sudo=1` flag on read requests.
+It requires the API key in use to belong to an **admin** account; for any other account the server ignores
+it and normal permissions apply.
+
+The attribute can also be toggled at any point in the client's lifetime:
+
+```python
+client.elevate_permissions = True
+```
+
+Note that objects created while elevated (e.g. uploaded files) are still recorded as belonging to the admin's own account, not the item owner's.
+
 ### Command-line interface (CLI)
 
 There is also an EXPERIMENTAL CLI, exposed via the `datalab` command.

{datalab_api-0.5.2 → 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.2 → 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
 
 
@@ -123,3 +127,78 @@ def test_upload_file_not_modified(fake_api_url, mocked_api, tmp_path):
     assert result["file_id"] == "6810ab6bb2b13a2be6c1e37f"
     assert result["is_update"] is True
     assert result["not_modified"] is True
+
+
+def test_elevate_permissions_adds_sudo_to_reads(mocked_api, fake_api_url):
+    """An elevated client sends `sudo=1` on GETs (and nothing else)."""
+    with DatalabClient(fake_api_url, elevate_permissions=True) as client:
+        client.get_item("KUVEKJ")
+
+    request = mocked_api["sample-KUVEKJ"].calls.last.request
+    assert request.url.params.get("sudo") == "1"
+
+
+def test_elevate_permissions_is_toggleable(mocked_api, fake_api_url):
+    """`elevate_permissions` can be flipped after construction."""
+    with DatalabClient(fake_api_url) as client:
+        client.get_item("KUVEKJ")
+        assert "sudo" not in mocked_api["sample-KUVEKJ"].calls.last.request.url.params
+
+        client.elevate_permissions = True
+        client.get_item("KUVEKJ")
+        assert mocked_api["sample-KUVEKJ"].calls.last.request.url.params.get("sudo") == "1"
+
+
+def test_elevate_permissions_not_sent_on_writes(mocked_api, fake_api_url):
+    """datalab grants admins full write access with no opt-in, so the flag
+    must not leak onto non-GET requests."""
+    with DatalabClient(fake_api_url, elevate_permissions=True) as client:
+        with pytest.raises(DatalabAPIError):
+            # `/save-item/` is mocked as a 500; we only care about the request
+            client.update_item("KUVEKJ", {"description": "test"})
+
+    request = mocked_api["bad-save"].calls.last.request
+    assert request.method == "POST"
+    assert "sudo" not in request.url.params
+
+
+def test_elevate_permissions_preserves_existing_params(mocked_api, fake_api_url):
+    """A caller-supplied query string must survive elevation."""
+    with DatalabClient(fake_api_url, elevate_permissions=True) as client:
+        client._get(
+            f"{client.datalab_api_url}/get-item-data/KUVEKJ",
+            params={"load_blocks": "false"},
+        )
+
+    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