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

{datalab_api-0.5.2/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.2
+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.2 → 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.2 → 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)
 

{datalab_api-0.5.2 → 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.")
@@ -367,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
@@ -375,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.2 → 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.2
+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.2 → datalab_api-0.5.3}/tests/test_client.py

@@ -123,3 +123,49 @@ 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"