datalab-python-sdk 0.6.0__tar.gz → 0.7.0__tar.gz

{datalab_python_sdk-0.6.0 → datalab_python_sdk-0.7.0}/CHANGELOG.md

@@ -3,6 +3,17 @@
 The newest release is at the top. Each export to this repository uses the
 top section as its commit message.
 
+## 0.7.0
+
+New:
+
+- `datalab login`: sign in from a terminal or a coding agent with a device
+  code. Approve it in the browser, type the emailed 6-digit code, and the SDK
+  saves an API key to `~/.config/datalab/config.json` (mode 0600).
+  `datalab logout` deletes it.
+- The clients use the saved key when no `api_key` is passed and
+  `DATALAB_API_KEY` is not set.
+
 ## 0.6.0
 
 Breaking changes:

{datalab_python_sdk-0.6.0 → datalab_python_sdk-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: datalab-python-sdk
-Version: 0.6.0
+Version: 0.7.0
 Summary: SDK for the Datalab document intelligence API
 Project-URL: Homepage, https://www.datalab.to
 Project-URL: Documentation, https://documentation.datalab.to
@@ -41,6 +41,14 @@ pip install datalab-python-sdk
 export DATALAB_API_KEY="your_api_key_here"
 ```
 
+Or sign in from a terminal, which also works for coding agents:
+
+```bash
+datalab login
+```
+
+It shows a code and a link. Open the link, sign in or sign up, approve the code, and type the 6-digit code that we email you. The SDK saves the key to `~/.config/datalab/config.json`, readable only by your user, and uses it when `DATALAB_API_KEY` is not set. `datalab logout` deletes it.
+
 ### Basic Usage
 
 ```python

{datalab_python_sdk-0.6.0 → datalab_python_sdk-0.7.0}/README.md

@@ -20,6 +20,14 @@ pip install datalab-python-sdk
 export DATALAB_API_KEY="your_api_key_here"
 ```
 
+Or sign in from a terminal, which also works for coding agents:
+
+```bash
+datalab login
+```
+
+It shows a code and a link. Open the link, sign in or sign up, approve the code, and type the 6-digit code that we email you. The SDK saves the key to `~/.config/datalab/config.json`, readable only by your user, and uses it when `DATALAB_API_KEY` is not set. `datalab logout` deletes it.
+
 ### Basic Usage
 
 ```python

datalab_python_sdk-0.7.0/datalab_sdk/auth.py

@@ -0,0 +1,130 @@
+"""Sign in from a terminal with a device code (`datalab login`), and keep the API key on disk.
+
+The flow (server side: /api/auth/device/code, /app/device, /api/auth/device/token):
+1. Ask the server for a code. Show the human the code and a URL, and open the browser.
+2. The human approves in the browser, where they are signed in as usual.
+3. Poll until the server returns a new API key, then save it to the config file.
+
+The key is saved to $XDG_CONFIG_HOME/datalab/config.json (default ~/.config/datalab/config.json)
+with mode 0600. DATALAB_API_KEY in the environment always wins over the saved key.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import time
+import urllib.error
+import urllib.request
+import webbrowser
+from pathlib import Path
+from typing import Callable, Optional
+
+from datalab_sdk.exceptions import DatalabAPIError
+
+KEYS_PAGE = "https://www.datalab.to/app/keys"
+
+
+def config_path() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or os.path.join(Path.home(), ".config")
+    return Path(base) / "datalab" / "config.json"
+
+
+def load_saved_api_key() -> Optional[str]:
+    try:
+        return json.loads(config_path().read_text()).get("api_key") or None
+    except (OSError, ValueError):
+        return None
+
+
+def save_api_key(api_key: str, host: str, team_name: Optional[str] = None) -> Path:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps({"api_key": api_key, "host": host, "team_name": team_name}, indent=2)
+    )
+    os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+    return path
+
+
+def delete_saved_api_key() -> bool:
+    try:
+        config_path().unlink()
+        return True
+    except FileNotFoundError:
+        return False
+
+
+def _post(url: str, payload: dict, headers: dict) -> tuple[int, dict]:
+    req = urllib.request.Request(
+        url,
+        data=json.dumps(payload).encode(),
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            **headers,
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as res:
+            return res.status, json.loads(res.read() or b"{}")
+    except urllib.error.HTTPError as e:
+        try:
+            return e.code, json.loads(e.read() or b"{}")
+        except ValueError:
+            return e.code, {}
+
+
+def device_login(
+    host: str = "https://www.datalab.to",
+    client_name: str = "Datalab CLI",
+    open_browser: bool = True,
+    extra_headers: Optional[dict] = None,
+    on_code: Optional[Callable[[dict], None]] = None,
+    sleep: Callable[[float], None] = time.sleep,
+) -> dict:
+    """Run the device flow and return {"api_key", "team_name", "key_name"}. Raises DatalabAPIError."""
+    host = host.rstrip("/")
+    headers = extra_headers or {}
+    status, code = _post(
+        f"{host}/api/auth/device/code", {"client_name": client_name}, headers
+    )
+    if status != 200:
+        raise DatalabAPIError(
+            f"Could not start the sign-in ({status}): {code.get('detail', code)}"
+        )
+    if on_code:
+        on_code(code)
+    if open_browser:
+        try:
+            webbrowser.open(code["verification_uri_complete"])
+        except Exception:
+            pass
+
+    interval = float(code.get("interval", 5))
+    deadline = time.monotonic() + float(code.get("expires_in", 600))
+    while time.monotonic() < deadline:
+        sleep(interval)
+        status, body = _post(
+            f"{host}/api/auth/device/token",
+            {"device_code": code["device_code"]},
+            headers,
+        )
+        if status == 200 and body.get("api_key"):
+            return body
+        error = body.get("error")
+        if error == "authorization_pending":
+            continue
+        if error == "slow_down":
+            interval += 5
+            continue
+        if error == "access_denied":
+            raise DatalabAPIError("The sign-in was denied in the browser.")
+        if error == "expired_token":
+            raise DatalabAPIError(
+                "The sign-in code expired. Run `datalab login` again."
+            )
+        raise DatalabAPIError(f"Sign-in failed ({status}): {body}")
+    raise DatalabAPIError("The sign-in code expired. Run `datalab login` again.")

{datalab_python_sdk-0.6.0 → datalab_python_sdk-0.7.0}/datalab_sdk/cli.py

@@ -495,6 +495,55 @@ def cli():
     pass
 
 
+@click.command()
+@click.option(
+    "--host",
+    default=None,
+    help="API host (default: DATALAB_HOST or https://www.datalab.to)",
+)
+@click.option(
+    "--no-browser",
+    is_flag=True,
+    help="Print the sign-in URL instead of opening a browser",
+)
+def login(host: Optional[str], no_browser: bool):
+    """Sign in from this terminal and save an API key (device code)."""
+    from datalab_sdk.auth import device_login, save_api_key
+
+    host = (host or settings.DATALAB_HOST).rstrip("/")
+
+    def show(code: dict):
+        click.echo("To sign in, open this page and approve the code:")
+        click.echo(f"  {code['verification_uri_complete']}")
+        click.echo(f"  Code: {code['user_code']}")
+        click.echo("Then type the 6-digit code that we email you.")
+        click.echo("Waiting for approval...")
+
+    try:
+        result = device_login(host=host, open_browser=not no_browser, on_code=show)
+    except DatalabError as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+    path = save_api_key(result["api_key"], host, result.get("team_name"))
+    click.echo(f"Signed in to team {result.get('team_name')}. API key saved to {path}.")
+    click.echo(
+        "DATALAB_API_KEY in your environment still takes priority over the saved key."
+    )
+
+
+@click.command()
+def logout():
+    """Delete the API key that `datalab login` saved. The key itself stays valid until you revoke it."""
+    from datalab_sdk.auth import config_path, delete_saved_api_key
+
+    if delete_saved_api_key():
+        click.echo(
+            f"Removed {config_path()}. Revoke the key at https://www.datalab.to/app/keys if you no longer need it."
+        )
+    else:
+        click.echo("No saved API key.")
+
+
 @click.command()
 @click.argument("path", type=click.Path(exists=True))
 @common_options
@@ -1584,6 +1633,8 @@ def _render_dag_simple(layers, children, step_map):
 
 
 # Add commands to CLI group
+cli.add_command(login)
+cli.add_command(logout)
 cli.add_command(convert)
 cli.add_command(extract)
 cli.add_command(segment)

{datalab_python_sdk-0.6.0 → datalab_python_sdk-0.7.0}/datalab_sdk/client.py

@@ -201,9 +201,13 @@ class AsyncDatalabClient:
         """
         if api_key is None:
             api_key = settings.DATALAB_API_KEY
+        if api_key is None:
+            from datalab_sdk.auth import load_saved_api_key
+
+            api_key = load_saved_api_key()
         if api_key is None:
             raise DatalabAPIError(
-                "You must pass in an api_key or set DATALAB_API_KEY. "
+                "No API key. Run `datalab login`, set DATALAB_API_KEY, or pass api_key. "
                 "Get a free API key at https://www.datalab.to/app/keys"
             )
 

{datalab_python_sdk-0.6.0 → datalab_python_sdk-0.7.0}/pyproject.toml

@@ -7,7 +7,7 @@ readme = "README.md"
 license = "MIT"
 repository = "https://github.com/datalab-to/sdk"
 keywords = ["datalab", "sdk", "document-intelligence", "api"]
-version = "0.6.0"
+version = "0.7.0"
 description = "SDK for the Datalab document intelligence API"
 requires-python = ">=3.11"
 dependencies = [

datalab_python_sdk-0.7.0/tests/test_device_login.py

@@ -0,0 +1,143 @@
+"""`datalab login` (device code) against a small fake server, plus the saved-key fallback."""
+
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import pytest
+from click.testing import CliRunner
+
+from datalab_sdk import auth
+from datalab_sdk.exceptions import DatalabAPIError
+
+
+class FakeServer:
+    """Answers /api/auth/device/code once, then `pending` polls, then the final reply."""
+
+    def __init__(self, pending_polls=1, final=None):
+        self.pending_polls = pending_polls
+        self.final = final or (
+            200,
+            {"api_key": "key_123", "team_name": "Acme", "key_name": "Datalab CLI"},
+        )
+        self.polls = 0
+        outer = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, *args):
+                pass
+
+            def _send(self, status, body):
+                data = json.dumps(body).encode()
+                self.send_response(status)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(data)))
+                self.end_headers()
+                self.wfile.write(data)
+
+            def do_POST(self):
+                self.rfile.read(int(self.headers.get("Content-Length") or 0))
+                if self.path == "/api/auth/device/code":
+                    host = f"http://127.0.0.1:{outer.port}"
+                    return self._send(
+                        200,
+                        {
+                            "device_code": "dc",
+                            "user_code": "BCDF-GHJK",
+                            "verification_uri": f"{host}/app/device",
+                            "verification_uri_complete": f"{host}/app/device?code=BCDF-GHJK",
+                            "expires_in": 600,
+                            "interval": 0,
+                        },
+                    )
+                outer.polls += 1
+                if outer.polls <= outer.pending_polls:
+                    return self._send(400, {"error": "authorization_pending"})
+                return self._send(*outer.final)
+
+        self.httpd = HTTPServer(("127.0.0.1", 0), Handler)
+        self.port = self.httpd.server_address[1]
+        self.url = f"http://127.0.0.1:{self.port}"
+        threading.Thread(target=self.httpd.serve_forever, daemon=True).start()
+
+    def close(self):
+        self.httpd.shutdown()
+
+
+@pytest.fixture
+def config_home(tmp_path, monkeypatch):
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+    return tmp_path
+
+
+def test_device_login_returns_key_after_pending():
+    server = FakeServer(pending_polls=2)
+    try:
+        shown = []
+        result = auth.device_login(
+            host=server.url,
+            open_browser=False,
+            on_code=shown.append,
+            sleep=lambda s: None,
+        )
+    finally:
+        server.close()
+    assert result["api_key"] == "key_123"
+    assert shown[0]["user_code"] == "BCDF-GHJK"
+    assert server.polls == 3
+
+
+@pytest.mark.parametrize(
+    "error,message", [("access_denied", "denied"), ("expired_token", "expired")]
+)
+def test_device_login_errors(error, message):
+    server = FakeServer(pending_polls=0, final=(400, {"error": error}))
+    try:
+        with pytest.raises(DatalabAPIError, match=message):
+            auth.device_login(host=server.url, open_browser=False, sleep=lambda s: None)
+    finally:
+        server.close()
+
+
+def test_save_load_delete_key(config_home):
+    path = auth.save_api_key("key_abc", "https://www.datalab.to", "Acme")
+    assert path == config_home / "datalab" / "config.json"
+    assert oct(path.stat().st_mode & 0o777) == "0o600"
+    assert auth.load_saved_api_key() == "key_abc"
+    assert auth.delete_saved_api_key() is True
+    assert auth.load_saved_api_key() is None
+
+
+def test_client_falls_back_to_saved_key(config_home, monkeypatch):
+    from datalab_sdk.client import DatalabClient
+    from datalab_sdk.settings import settings
+
+    monkeypatch.setattr(settings, "DATALAB_API_KEY", None)
+    auth.save_api_key("key_saved", "https://www.datalab.to")
+    assert DatalabClient()._async_client.api_key == "key_saved"
+    monkeypatch.setattr(settings, "DATALAB_API_KEY", "key_env")
+    assert DatalabClient()._async_client.api_key == "key_env"
+
+
+def test_client_error_names_login_and_keys_page(config_home, monkeypatch):
+    from datalab_sdk.client import DatalabClient
+    from datalab_sdk.settings import settings
+
+    monkeypatch.setattr(settings, "DATALAB_API_KEY", None)
+    with pytest.raises(DatalabAPIError, match="datalab login"):
+        DatalabClient()
+
+
+def test_cli_login_saves_key(config_home):
+    from datalab_sdk.cli import cli
+
+    server = FakeServer(pending_polls=0)
+    try:
+        res = CliRunner().invoke(cli, ["login", "--host", server.url, "--no-browser"])
+    finally:
+        server.close()
+    assert res.exit_code == 0, res.output
+    assert "BCDF-GHJK" in res.output and "Signed in to team Acme" in res.output
+    assert auth.load_saved_api_key() == "key_123"
+    out = CliRunner().invoke(cli, ["logout"])
+    assert out.exit_code == 0 and auth.load_saved_api_key() is None

{datalab_python_sdk-0.6.0 → datalab_python_sdk-0.7.0}/uv.lock

@@ -234,7 +234,7 @@ wheels = [
 
 [[package]]
 name = "datalab-python-sdk"
-version = "0.6.0"
+version = "0.7.0"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },