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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datalab-api
-Version: 0.5.1
+Version: 0.5.3
 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
@@ -120,6 +120,31 @@ with DatalabClient("https://demo-api.datalab-org.io") as client:
 
 ```
 
+### 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.1 → datalab_api-0.5.3}/README.md

@@ -75,6 +75,31 @@ with DatalabClient("https://demo-api.datalab-org.io") as client:
 
 ```
 
+### 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.1 → datalab_api-0.5.3}/src/datalab_api/__init__.py

@@ -268,8 +268,13 @@ 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:
+                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)
 
@@ -322,7 +327,12 @@ class DatalabClient(BaseDatalabClient):
                 If provided, the new file will take the place of the old file in any blocks it was attached to.
 
         Returns:
-            A dictionary of the uploaded file data.
+            A dictionary of the uploaded file data, with an additional
+            `not_modified` key. If `replace_file_id` was provided and the
+            server already holds identical content (compared by hash), the
+            update is a no-op: the server replies `304 Not Modified` and
+            `not_modified` is `True`. Servers older than datalab#1744 never
+            report this, so `not_modified` is always `False` against them.
 
         """
         if isinstance(file_path, str):
@@ -341,10 +351,23 @@ class DatalabClient(BaseDatalabClient):
                 upload_url,
                 files=files,
                 data={"item_id": item_id, "replace_file": replace_file_id},
-                expected_status=201,
+                expected_status=[201, 304],
                 timeout=upload_timeout,
             )
-        return upload
+
+        # A 201 always carries a body describing the stored file, so an
+        # empty dict here can only be the 304: the server compared hashes,
+        # found it already holds this content, and made no update. That is
+        # a success, so report it rather than raising.
+        if not upload:
+            return {
+                "status": "success",
+                "file_id": replace_file_id,
+                "is_update": True,
+                "not_modified": True,
+            }
+
+        return {**upload, "not_modified": False}
 
     def create_data_block(
         self,

{datalab_api-0.5.1 → datalab_api-0.5.3}/src/datalab_api/_base.py

@@ -58,7 +58,22 @@ class BaseDatalabClient(metaclass=AutoPrettyPrint):
     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.")
@@ -317,6 +336,12 @@ This is likely a server-side bug. Please report this issue to the datalab develo
                     f"HTTP {response.status_code} error at {url}: {error_message}"
                 )
 
+        # 204 and 304 carry no entity body by definition
+        # Where such a status is expected, an empty body
+        # is the success case rather than a parse failure.
+        if response.status_code in (204, 304):
+            return {}
+
         # Parse JSON response
         try:
             data = response.json()
@@ -361,6 +386,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
@@ -369,6 +395,22 @@ 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)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datalab-api
-Version: 0.5.1
+Version: 0.5.3
 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
@@ -120,6 +120,31 @@ with DatalabClient("https://demo-api.datalab-org.io") as client:
 
 ```
 
+### 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.3/tests/test_client.py

@@ -0,0 +1,171 @@
+import pytest
+import respx
+from httpx import Response
+
+from datalab_api import DatalabClient
+from datalab_api._base import DatalabAPIError
+
+
+def test_redirect_url(mocked_api, mocked_ui, fake_api_url, fake_ui_url):
+    with pytest.warns(
+        UserWarning,
+        match="^Found API URL https://api.datalab.industries in HTML meta tag. Creating client with this URL instead.$",
+    ):
+        client = DatalabClient(fake_ui_url)
+
+    assert mocked_ui["ui-redirect"].called
+    assert mocked_api["info"].called
+    assert mocked_api["info-blocks"].called
+    assert client.datalab_api_url == fake_api_url
+
+
+def test_sample_operations(mocked_api, fake_api_url):
+    with DatalabClient(fake_api_url) as client:
+        assert mocked_api["api"].called
+        assert mocked_api["info"].called
+        assert mocked_api["info-blocks"].called
+
+        client.authenticate()
+        assert mocked_api["current_user"].called
+
+        samples = client.get_items(display=True)
+        assert mocked_api["samples"].called
+        assert len(samples)
+        assert samples[0]["item_id"] == "test"
+
+        sample = client.get_item("KUVEKJ", display=True)
+        assert mocked_api["sample-KUVEKJ"].called
+        assert sample["item_id"] == "KUVEKJ"
+
+        # 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",
+        ):
+            client.get_item("TEST", display=True)
+        assert mocked_api["sample-missing-TEST"].called
+
+        with pytest.raises(DatalabAPIError, match="KeyError"):
+            client.update_item(item_id="TEST", item_data={"name": "test"})
+        assert mocked_api["bad-save"].called
+
+
+@respx.mock
+def test_collection_get(fake_api_url, mocked_api):
+    with DatalabClient("https://api.datalab.industries") as client:
+        assert mocked_api["api"].called
+        assert mocked_api["info"].called
+        assert mocked_api["info-blocks"].called
+
+        collection, children = client.get_collection("test_collection", display=True)
+        assert mocked_api["collection-test_collection"].called
+
+
+@respx.mock
+def test_group_get(fake_api_url, mocked_api):
+    with DatalabClient("https://api.datalab.industries") as client:
+        assert mocked_api["api"].called
+        assert mocked_api["info"].called
+        assert mocked_api["info-blocks"].called
+
+        group = client.get_group("test_group", display=True)
+        assert mocked_api["search-groups"].called
+        assert group["immutable_id"] == "67d0b01e03000cdc75134dbd"
+        assert group["group_id"] == "test_group"
+
+
+@respx.mock
+def test_upload_file(fake_api_url, mocked_api, tmp_path):
+    """A new upload is stored by the server and reported as modified."""
+    fake_upload = mocked_api.post("/upload-file/", name="upload")
+    fake_upload.return_value = Response(
+        201,
+        json={
+            "status": "success",
+            "file_id": "6810ab6bb2b13a2be6c1e37f",
+            "file_information": {"name": "data.csv"},
+            "is_update": False,
+        },
+    )
+
+    test_file = tmp_path / "data.csv"
+    test_file.write_text("a,b\n1,2\n")
+
+    with DatalabClient(fake_api_url) as client:
+        result = client.upload_file(item_id="KUVEKJ", file_path=test_file)
+
+    assert mocked_api["upload"].called
+    assert result["file_id"] == "6810ab6bb2b13a2be6c1e37f"
+    assert result["not_modified"] is False
+
+
+@respx.mock
+def test_upload_file_not_modified(fake_api_url, mocked_api, tmp_path):
+    """When replacing a file whose content the server already holds, it
+    replies 304 with an empty body. That is a successful no-op, so the
+    existing file ID is returned with `not_modified` set, rather than
+    the empty body being treated as an error."""
+    fake_upload = mocked_api.post("/upload-file/", name="upload")
+    fake_upload.return_value = Response(304, content=b"")
+
+    test_file = tmp_path / "data.csv"
+    test_file.write_text("a,b\n1,2\n")
+
+    with DatalabClient(fake_api_url) as client:
+        result = client.upload_file(
+            item_id="KUVEKJ",
+            file_path=test_file,
+            replace_file_id="6810ab6bb2b13a2be6c1e37f",
+        )
+
+    assert mocked_api["upload"].called
+    assert result["status"] == "success"
+    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"

datalab_api-0.5.1/tests/test_client.py

@@ -1,73 +0,0 @@
-import pytest
-import respx
-
-from datalab_api import DatalabClient
-from datalab_api._base import DatalabAPIError
-
-
-def test_redirect_url(mocked_api, mocked_ui, fake_api_url, fake_ui_url):
-    with pytest.warns(
-        UserWarning,
-        match="^Found API URL https://api.datalab.industries in HTML meta tag. Creating client with this URL instead.$",
-    ):
-        client = DatalabClient(fake_ui_url)
-
-    assert mocked_ui["ui-redirect"].called
-    assert mocked_api["info"].called
-    assert mocked_api["info-blocks"].called
-    assert client.datalab_api_url == fake_api_url
-
-
-def test_sample_operations(mocked_api, fake_api_url):
-    with DatalabClient(fake_api_url) as client:
-        assert mocked_api["api"].called
-        assert mocked_api["info"].called
-        assert mocked_api["info-blocks"].called
-
-        client.authenticate()
-        assert mocked_api["current_user"].called
-
-        samples = client.get_items(display=True)
-        assert mocked_api["samples"].called
-        assert len(samples)
-        assert samples[0]["item_id"] == "test"
-
-        sample = client.get_item("KUVEKJ", display=True)
-        assert mocked_api["sample-KUVEKJ"].called
-        assert sample["item_id"] == "KUVEKJ"
-
-        # 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",
-        ):
-            client.get_item("TEST", display=True)
-        assert mocked_api["sample-missing-TEST"].called
-
-        with pytest.raises(DatalabAPIError, match="KeyError"):
-            client.update_item(item_id="TEST", item_data={"name": "test"})
-        assert mocked_api["bad-save"].called
-
-
-@respx.mock
-def test_collection_get(fake_api_url, mocked_api):
-    with DatalabClient("https://api.datalab.industries") as client:
-        assert mocked_api["api"].called
-        assert mocked_api["info"].called
-        assert mocked_api["info-blocks"].called
-
-        collection, children = client.get_collection("test_collection", display=True)
-        assert mocked_api["collection-test_collection"].called
-
-
-@respx.mock
-def test_group_get(fake_api_url, mocked_api):
-    with DatalabClient("https://api.datalab.industries") as client:
-        assert mocked_api["api"].called
-        assert mocked_api["info"].called
-        assert mocked_api["info-blocks"].called
-
-        group = client.get_group("test_group", display=True)
-        assert mocked_api["search-groups"].called
-        assert group["immutable_id"] == "67d0b01e03000cdc75134dbd"
-        assert group["group_id"] == "test_group"