calkit-python 0.37.6__tar.gz → 0.38.0__tar.gz

calkit_python-0.38.0/AGENTS.md

@@ -0,0 +1,13 @@
+# Agent instructions for working on Calkit
+
+## Repo structure
+
+- The main Python package/CLI lives in `calkit`
+- The JupyterLab extension lives in `src`
+- The VS Code extension lives in `vscode-ext`
+
+## Working
+
+See `CONTRIBUTING.md` for tool usage, style guidelines, etc.
+
+To run tests, use `uv run pytest`.

{calkit_python-0.37.6 → calkit_python-0.38.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: calkit-python
-Version: 0.37.6
+Version: 0.38.0
 Summary: Reproducibility simplified.
 Project-URL: Homepage, https://calkit.org
 Project-URL: Issues, https://github.com/calkit/calkit/issues
@@ -174,7 +174,11 @@ You may also want to install [Docker](https://docker.com),
 since that is the default method by which LaTeX environments are created.
 If you want to use the [Calkit Cloud](https://calkit.io)
 for collaboration and backup as a DVC remote,
-you can [set up cloud integration](https://docs.calkit.org/cloud-integration).
+you can [set up cloud integration](https://docs.calkit.org/cloud-integration) with:
+
+```sh
+calkit cloud login
+```
 
 ### Use without installing
 

{calkit_python-0.37.6 → calkit_python-0.38.0}/README.md

@@ -115,7 +115,11 @@ You may also want to install [Docker](https://docker.com),
 since that is the default method by which LaTeX environments are created.
 If you want to use the [Calkit Cloud](https://calkit.io)
 for collaboration and backup as a DVC remote,
-you can [set up cloud integration](https://docs.calkit.org/cloud-integration).
+you can [set up cloud integration](https://docs.calkit.org/cloud-integration) with:
+
+```sh
+calkit cloud login
+```
 
 ### Use without installing
 

{calkit_python-0.37.6 → calkit_python-0.38.0}/calkit/cli/check.py

@@ -250,7 +250,7 @@ def check_repro(
 ) -> None:
     """Check the reproducibility of a project."""
     res = check_reproducibility(wdir=wdir, log_func=typer.echo)
-    typer.echo(res.to_pretty().encode("utf-8", errors="replace"))
+    calkit.echo(res.to_pretty())
 
 
 @check_app.command(
@@ -1251,7 +1251,7 @@ def check_dependencies(
     except Exception as e:
         raise_error(str(e))
     message = "✅ All set!"
-    typer.echo(message.encode("utf-8", errors="replace"))
+    calkit.echo(message)
 
 
 @check_app.command(name="env-vars")
@@ -1296,7 +1296,7 @@ def check_env_vars(
         with open(".gitignore", "a") as f:
             f.write("\n.env\n")
     message = "✅ All set!"
-    typer.echo(message.encode("utf-8", errors="replace"))
+    calkit.echo(message)
 
 
 @check_app.command(name="pipeline")
@@ -1326,7 +1326,7 @@ def check_pipeline(
         if stage_name.startswith("_"):
             raise_error("Stage names cannot start with an underscore")
     message = "✅ This project's pipeline is defined correctly!"
-    typer.echo(message.encode("utf-8", errors="replace"))
+    calkit.echo(message)
     if compile_to_dvc:
         typer.echo("Attempting to compile to DVC stages")
         try:

calkit_python-0.38.0/calkit/cli/cloud.py

@@ -0,0 +1,125 @@
+"""CLI for interacting with Calkit Cloud instances."""
+
+from __future__ import annotations
+
+import socket
+import time
+import webbrowser
+from typing import Annotated
+
+import typer
+from requests.exceptions import HTTPError
+
+import calkit
+from calkit.cli import raise_error
+
+cloud_app = typer.Typer(no_args_is_help=True)
+
+
+@cloud_app.command(name="get")
+def get(endpoint: Annotated[str, typer.Argument(help="API endpoint")]):
+    """Get a resource from the Cloud API."""
+    if not endpoint.startswith("/"):
+        endpoint = "/" + endpoint
+    try:
+        resp = calkit.cloud.get(endpoint)
+        typer.echo(resp)
+    except Exception as e:
+        raise_error(str(e))
+
+
+@cloud_app.command(name="login")
+def login(
+    force: Annotated[
+        bool,
+        typer.Option(
+            "--force",
+            "-f",
+            help=(
+                "Force logging in again even if already authenticated. "
+                "Will store a new token in your local config."
+            ),
+        ),
+    ] = False,
+):
+    """Login to the Calkit Cloud.
+
+    First try a GET request to the /user endpoint to check if the user is
+    already logged in. If not, perform OAuth device flow.
+    """
+    try:
+        calkit.cloud.get("/user")
+        calkit.echo("Authenticated successfully ✅")
+        if not force:
+            return
+    except (ValueError, HTTPError) as e:
+        if isinstance(e, HTTPError) and "401" not in str(e):
+            raise_error(str(e))
+    # Now perform the OAuth device flow
+    try:
+        hostname = socket.gethostname()
+    except Exception:
+        hostname = None
+    try:
+        calkit.echo("Initiating device login flow")
+        resp = calkit.cloud.post(
+            "/login/device",
+            json={"hostname": hostname},
+            auth=False,
+        )
+        device_code = resp["device_code"]
+        verification_uri = resp["verification_uri"]
+        expires_in = int(resp["expires_in"])
+        interval = int(resp["interval"])
+    except Exception as e:
+        raise_error(f"Failed to initiate device login flow: {e}")
+    calkit.echo("Authorize this device by opening this URL:")
+    calkit.echo(verification_uri)
+    calkit.echo("Waiting for authorization")
+    try:
+        webbrowser.open(verification_uri)
+    except Exception:
+        # If auto-open fails, user can still copy-paste the URL.
+        pass
+    deadline = time.monotonic() + expires_in
+    while time.monotonic() < deadline:
+        try:
+            token_resp = calkit.cloud.post(
+                "/login/device/token",
+                json={"device_code": device_code},
+                auth=False,
+            )
+        except Exception as e:
+            txt = str(e)
+            if "Device code has expired" in txt:
+                raise_error(
+                    "Device code has expired; Run 'calkit cloud login' again"
+                )
+            if "Device code not found" in txt:
+                raise_error(
+                    "Device code not found; Run 'calkit cloud login' again"
+                )
+            raise_error(f"Error while polling for device authorization: {e}")
+        access_token = token_resp.get("access_token")
+        if access_token:
+            refresh_token = token_resp.get("refresh_token")
+            try:
+                cfg = calkit.config.read()
+                cfg.access_token = access_token
+                if refresh_token:
+                    cfg.refresh_token = refresh_token
+                cfg.write()
+                calkit.cloud._tokens[calkit.cloud.get_base_url()] = (
+                    access_token
+                )
+            except Exception as e:
+                raise_error(f"Failed to save token in config: {e}")
+            calkit.echo("Logged in successfully ✅")
+            return
+        sleep_seconds = min(interval, max(0.0, deadline - time.monotonic()))
+        if sleep_seconds > 0:
+            time.sleep(sleep_seconds)
+    raise_error(
+        "Timed out waiting for device authorization; "
+        "Run 'calkit cloud login' again"
+    )

{calkit_python-0.37.6 → calkit_python-0.38.0}/calkit/cli/config.py

@@ -142,7 +142,10 @@ def config_github_ssh():
     # First check if we can already connect to GitHub
     ssh_test_cmd = ["ssh", "-T", "git@github.com"]
     p = subprocess.run(ssh_test_cmd, capture_output=True, text=True)
-    if "successfully authenticated" in p.stderr:
+    if (
+        "successfully authenticated" in p.stdout
+        or "successfully authenticated" in p.stderr
+    ):
         typer.echo("You can already connect to GitHub via SSH")
         go_on = typer.confirm("Do you want to add a new SSH key anyway?")
         if not go_on:

{calkit_python-0.37.6 → calkit_python-0.38.0}/calkit/cli/main/core.py

@@ -1564,12 +1564,7 @@ def run(
     if failed:
         raise_error("Pipeline failed")
     else:
-        _enc = sys.stdout.encoding or "utf-8"
-        typer.echo(
-            "Pipeline completed successfully ✅".encode(
-                _enc, errors="replace"
-            ).decode(_enc)
-        )
+        calkit.echo("Pipeline completed successfully ✅")
     if save_after_run or save_message is not None:
         if save_message is None:
             save_message = "Run pipeline"

calkit_python-0.38.0/calkit/cloud.py

@@ -0,0 +1,232 @@
+"""The REST API client."""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import threading
+import time
+from functools import partial
+from typing import Literal
+
+import requests
+from requests.exceptions import HTTPError
+
+from . import config
+
+logger = logging.getLogger(__name__)
+
+# A dictionary of tokens keyed by base URL
+_tokens = {}
+
+# Single lock guarding all token-refresh operations to prevent thundering herds
+# (e.g., many concurrent fsspec threads all attempting to refresh at once).
+_refresh_lock = threading.Lock()
+
+# Seconds before JWT expiry at which we proactively refresh.
+_REFRESH_BUFFER_SECONDS = 60
+
+
+def get_base_url() -> str:
+    """Get the API base URL."""
+    urls = {
+        "local": "http://api.localhost",
+        "staging": "https://api.staging.calkit.io",
+        "production": "https://api.calkit.io",
+        "test": "http://api.localhost",
+    }
+    return urls[config.get_env()]
+
+
+def _jwt_exp(token: str) -> float | None:
+    """Return the ``exp`` claim of a JWT as a UTC timestamp, or ``None``.
+
+    Does not verify the signature — only used for proactive expiry checks.
+    """
+    try:
+        # JWTs are <header>.<payload>.<sig>, all base64url-encoded
+        payload_b64 = token.split(".")[1]
+        # Pad to a multiple of 4 for standard base64 decoding
+        padding = 4 - len(payload_b64) % 4
+        if padding != 4:
+            payload_b64 += "=" * padding
+        payload = json.loads(base64.urlsafe_b64decode(payload_b64))
+        return float(payload["exp"])
+    except Exception:
+        return None
+
+
+def _token_is_expiring(token: str) -> bool:
+    """Return True if ``token`` is a JWT that expires within the refresh
+    buffer.
+    """
+    exp = _jwt_exp(token)
+    if exp is None:
+        return False  # Not a JWT (e.g. a PAT) — never proactively refresh
+    return time.time() >= exp - _REFRESH_BUFFER_SECONDS
+
+
+def get_token() -> str:
+    """Return a valid bearer token.
+
+    Priority: in-memory cache (refreshed proactively if expiring), then PAT
+    (``token`` / ``CALKIT_TOKEN`` env var), then short-lived ``access_token``
+    from device login.
+
+    For access tokens, expiry is read from the JWT ``exp`` claim and a refresh
+    is attempted before the token expires.  Only one thread performs the
+    refresh at a time; all others wait behind ``_refresh_lock`` and then use
+    the new token that was stored in the cache.
+    """
+    base_url = get_base_url()
+    cached = _tokens.get(base_url)
+    if cached is not None and not _token_is_expiring(cached):
+        return cached
+    # Token missing or expiring — acquire the lock so only one thread refreshes
+    with _refresh_lock:
+        # Re-check after acquiring lock; another thread may have refreshed
+        cached = _tokens.get(base_url)
+        if cached is not None and not _token_is_expiring(cached):
+            return cached
+        # If we have a refresh token, try to get a new access token now
+        if cached is not None and _token_is_expiring(cached):
+            new_token = _do_refresh()
+            if new_token is not None:
+                return new_token
+        # No usable cached token — load from config
+        cfg = config.read()
+        # Prefer long-lived PAT if present (env var CALKIT_TOKEN or config)
+        if cfg.token is not None:
+            _tokens[base_url] = cfg.token
+            return cfg.token
+        # Fall back to short-lived access token from device login
+        if cfg.access_token is not None:
+            if not _token_is_expiring(cfg.access_token):
+                _tokens[base_url] = cfg.access_token
+                return cfg.access_token
+            # Config token is also expiring — attempt refresh
+            new_token = _do_refresh()
+            if new_token is not None:
+                return new_token
+        raise ValueError(
+            "No token found; Run 'calkit cloud login' to authenticate"
+        )
+
+
+def _do_refresh() -> str | None:
+    """Perform a token refresh request.
+
+    Must be called with ``_refresh_lock`` already held (or from within
+    ``_try_refresh`` which acquires it).  Returns the new access token on
+    success or ``None`` on failure.
+    """
+    cfg = config.read()
+    if cfg.refresh_token is None:
+        return None
+    base_url = get_base_url()
+    try:
+        resp = requests.post(
+            base_url + "/login/refresh",
+            json={"refresh_token": cfg.refresh_token},
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        new_access = data["access_token"]
+        new_refresh = data.get("refresh_token", cfg.refresh_token)
+        cfg.access_token = new_access
+        cfg.refresh_token = new_refresh
+        cfg.write()
+        _tokens[base_url] = new_access
+        return new_access
+    except Exception as exc:
+        logger.debug("Token refresh failed: %s", exc)
+        return None
+
+
+def _try_refresh() -> str | None:
+    """Attempt a token refresh from outside the normal request cycle.
+
+    Acquires ``_refresh_lock`` to prevent concurrent refresh storms.
+    Returns the new access token on success, or ``None``.
+    """
+    with _refresh_lock:
+        return _do_refresh()
+
+
+def get_headers(headers: dict | None = None, auth: bool = True) -> dict:
+    if auth:
+        base_headers = {"Authorization": f"Bearer {get_token()}"}
+    else:
+        base_headers = {}
+    if headers is not None:
+        return base_headers | headers
+    else:
+        return base_headers
+
+
+def _request(
+    kind: Literal["get", "post", "put", "patch", "delete"],
+    path: str,
+    params: dict | None = None,
+    json: dict | None = None,
+    data: dict | None = None,
+    headers: dict | None = None,
+    as_json=True,
+    auth: bool = True,
+    base_url: str | None = None,
+    **kwargs,
+):
+    max_retries = 10
+    base_delay_seconds = 0.25
+    max_delay_seconds = 30
+    func = getattr(requests, kind)
+    if base_url is None:
+        base_url = get_base_url()
+    refresh_attempted = False
+    for retry_num in range(max_retries + 1):
+        resp = func(
+            base_url + path,
+            params=params,
+            json=json,
+            data=data,
+            headers=get_headers(headers, auth=auth),
+            **kwargs,
+        )
+        if resp.status_code == 502 and retry_num < max_retries:
+            wait = min(base_delay_seconds * (2**retry_num), max_delay_seconds)
+            time.sleep(wait)
+            continue
+        # On 401, attempt a token refresh once (only for access_token sessions,
+        # not PATs — _try_refresh returns None when no refresh_token is stored).
+        # get_headers() re-calls get_token() on the next iteration, so it will
+        # automatically pick up the new token stored in _tokens by _try_refresh.
+        if resp.status_code == 401 and auth and not refresh_attempted:
+            refresh_attempted = True
+            new_token = _try_refresh()
+            if new_token is not None:
+                continue
+        try:
+            resp.raise_for_status()
+        except HTTPError as e:
+            try:
+                detail = resp.json()["detail"]
+            except Exception:
+                raise e
+            raise HTTPError(f"{resp.status_code}: {detail}")
+        break
+    if as_json:
+        return resp.json()
+    else:
+        return resp
+
+
+get = partial(_request, "get")
+post = partial(_request, "post")
+patch = partial(_request, "patch")
+put = partial(_request, "put")
+delete = partial(_request, "delete")
+
+
+def get_current_user() -> dict:
+    return get("/user")

{calkit_python-0.37.6 → calkit_python-0.38.0}/calkit/config.py

@@ -165,10 +165,10 @@ class Settings(BaseSettings):
         env_file=".env",
         env_file_encoding="utf-8",
     )
-    username: str | None = None
     email: str | None = None
-    password: KeyringOptionalSecret | None = None
     token: KeyringOptionalSecret | None = None
+    access_token: KeyringOptionalSecret | None = None
+    refresh_token: KeyringOptionalSecret | None = None
     dvc_token: KeyringOptionalSecret | None = None
     dataframe_engine: Literal["pandas", "polars"] = "pandas"
     github_token: KeyringOptionalSecret | None = None

{calkit_python-0.37.6 → calkit_python-0.38.0}/calkit/core.py

@@ -14,6 +14,7 @@ import platform
 import re
 import socket
 import subprocess
+import sys
 import uuid
 import warnings
 from os import PathLike
@@ -93,6 +94,16 @@ DVC_EXTENSIONS = [
 DVC_SIZE_THRESH_BYTES = 5_000_000
 
 
+def echo(message: str) -> None:
+    """Print a message safely, replacing unencodable characters
+    (e.g., emoji).
+    """
+    import typer
+
+    enc = sys.stdout.encoding or "utf-8"
+    typer.echo(message.encode(enc, errors="replace").decode(enc))
+
+
 def find_project_dirs(relative=False, max_depth=3) -> list[str]:
     """Find all Calkit project directories."""
     if relative:

calkit_python-0.38.0/calkit/tests/cli/test_cloud.py

@@ -0,0 +1,170 @@
+"""Tests for the cloud CLI."""
+
+import pytest
+import typer
+from requests.exceptions import HTTPError
+
+import calkit.cli.cloud as cloud_cli
+
+
+def test_cloud_login_already_logged_in(monkeypatch, capsys):
+    def _get(path):
+        assert path == "/user"
+        return {"email": "user@example.com"}
+
+    monkeypatch.setattr(cloud_cli.calkit.cloud, "get", _get)
+    cloud_cli.login()
+    out = capsys.readouterr().out
+    assert "Authenticated successfully" in out
+
+
+def test_cloud_login_device_flow_success(monkeypatch, capsys):
+    call_counts = {"token_polls": 0}
+    post_calls = []
+
+    class DummyConfig:
+        def __init__(self):
+            self.token = None
+            self.access_token = None
+            self.refresh_token = None
+            self.written = False
+
+        def write(self):
+            self.written = True
+
+    cfg = DummyConfig()
+
+    def _get(path):
+        assert path == "/user"
+        raise HTTPError("401: Not authenticated")
+
+    def _post(path, **kwargs):
+        post_calls.append((path, kwargs))
+        if path == "/login/device":
+            return {
+                "device_code": "dev-123",
+                "verification_uri": (
+                    "https://app.example.com/cli-auth?device_code=dev-123"
+                ),
+                "expires_in": 60,
+                "interval": 1,
+            }
+        if path == "/login/device/token":
+            call_counts["token_polls"] += 1
+            if call_counts["token_polls"] < 2:
+                return {"detail": "Authorization pending"}
+            return {
+                "access_token": "ckp_test_access",
+                "refresh_token": "ckp_test_refresh",
+            }
+        raise AssertionError(f"Unexpected path: {path}")
+
+    monkeypatch.setattr(cloud_cli.calkit.cloud, "get", _get)
+    monkeypatch.setattr(cloud_cli.calkit.cloud, "post", _post)
+    monkeypatch.setattr(cloud_cli.calkit.config, "read", lambda: cfg)
+    monkeypatch.setattr(cloud_cli.webbrowser, "open", lambda _url: True)
+    monkeypatch.setattr(cloud_cli.time, "sleep", lambda _seconds: None)
+    cloud_cli.login()
+    out = capsys.readouterr().out
+    assert "Authorize this device by opening this URL:" in out
+    assert "Waiting for authorization" in out
+    assert "Logged in successfully" in out
+    assert cfg.access_token == "ckp_test_access"
+    assert cfg.refresh_token == "ckp_test_refresh"
+    assert cfg.token is None  # PAT field must not be touched by device login
+    assert cfg.written is True
+    assert post_calls[0][0] == "/login/device"
+    assert post_calls[0][1].get("auth") is False
+    assert post_calls[1][0] == "/login/device/token"
+    assert post_calls[1][1].get("auth") is False
+
+
+def test_cloud_login_force_re_authenticates(monkeypatch, capsys):
+    """--force should start the device flow even when already authenticated."""
+
+    class DummyConfig:
+        def __init__(self):
+            self.token = None
+            self.access_token = None
+            self.refresh_token = None
+
+        def write(self):
+            pass
+
+    cfg = DummyConfig()
+
+    def _get(path):
+        return {"email": "user@example.com"}
+
+    def _post(path, **kwargs):
+        if path == "/login/device":
+            return {
+                "device_code": "dev-force",
+                "verification_uri": "https://example.com/auth",
+                "expires_in": 60,
+                "interval": 1,
+            }
+        if path == "/login/device/token":
+            return {
+                "access_token": "ckp_new_access",
+                "refresh_token": "ckp_new_refresh",
+            }
+        raise AssertionError(f"Unexpected path: {path}")
+
+    monkeypatch.setattr(cloud_cli.calkit.cloud, "get", _get)
+    monkeypatch.setattr(cloud_cli.calkit.cloud, "post", _post)
+    monkeypatch.setattr(cloud_cli.calkit.config, "read", lambda: cfg)
+    monkeypatch.setattr(cloud_cli.webbrowser, "open", lambda _url: True)
+    monkeypatch.setattr(cloud_cli.time, "sleep", lambda _s: None)
+    cloud_cli.login(force=True)
+    out = capsys.readouterr().out
+    assert "Logged in successfully" in out
+    assert cfg.access_token == "ckp_new_access"
+
+
+def test_cloud_login_device_code_expired(monkeypatch):
+    """Expired device code during polling should raise Exit."""
+
+    def _get(path):
+        raise HTTPError("401: Not authenticated")
+
+    def _post(path, **kwargs):
+        if path == "/login/device":
+            return {
+                "device_code": "dev-exp",
+                "verification_uri": "https://example.com/auth",
+                "expires_in": 60,
+                "interval": 1,
+            }
+        raise Exception("401: Device code has expired")
+
+    monkeypatch.setattr(cloud_cli.calkit.cloud, "get", _get)
+    monkeypatch.setattr(cloud_cli.calkit.cloud, "post", _post)
+    monkeypatch.setattr(cloud_cli.webbrowser, "open", lambda _url: True)
+    monkeypatch.setattr(cloud_cli.time, "sleep", lambda _s: None)
+    with pytest.raises(typer.Exit):
+        cloud_cli.login()
+
+
+def test_cloud_login_device_code_not_found(monkeypatch):
+    """Not-found device code during polling should raise Exit."""
+
+    def _get(path):
+        raise HTTPError("401: Not authenticated")
+
+    def _post(path, **kwargs):
+        if path == "/login/device":
+            return {
+                "device_code": "dev-nf",
+                "verification_uri": "https://example.com/auth",
+                "expires_in": 60,
+                "interval": 1,
+            }
+        raise Exception("404: Device code not found")
+
+    monkeypatch.setattr(cloud_cli.calkit.cloud, "get", _get)
+    monkeypatch.setattr(cloud_cli.calkit.cloud, "post", _post)
+    monkeypatch.setattr(cloud_cli.webbrowser, "open", lambda _url: True)
+    monkeypatch.setattr(cloud_cli.time, "sleep", lambda _s: None)
+    with pytest.raises(typer.Exit):
+        cloud_cli.login()