model2data-studio 0.1.0__py3-none-any.whl

model2data_studio/client.py

@@ -0,0 +1,197 @@
+"""HTTP against a studio, and its failures turned into sentences.
+
+Every request the CLI makes goes through here, so there is one place that knows
+what a status code means to someone standing at a terminal. A CLI failure is
+usually read out of a CI log by whoever did not write the pipeline, hours after
+the fact, so each message says what to change rather than what went wrong.
+
+Authentication is a bearer token and nothing more. The studio accepts a Supabase
+JWT and an `m2d_` API key at the same door, and this client neither knows nor
+cares which it was handed — which is what lets the key format change without
+touching anything here.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+
+DEFAULT_URL = "https://studio.jbanalytica.com"
+
+# Generation happens inside the request, and a large schema at a large row count
+# is genuinely slow. Generous enough that a real export finishes, short enough
+# that a wedged CI job eventually fails instead of burning its whole budget.
+DEFAULT_TIMEOUT = 300.0
+
+# A studio under load asks for a wait; an honest one asks for seconds. Capped so
+# a header saying "an hour" fails the run rather than parking a CI job on it.
+MAX_RETRY_WAIT = 60.0
+DEFAULT_RETRY_WAIT = 5.0
+
+
+class StudioError(Exception):
+    """A failure phrased for the person reading it, not for a stack trace.
+
+    Raised for everything the caller could act on — a refused key, a plan
+    boundary, an unreachable host — so `cli.py` can print it and exit without
+    knowing anything about HTTP.
+    """
+
+
+class StudioClient:
+    """The studio's API, as the four calls this CLI needs.
+
+    `transport` exists for the tests: an `httpx.MockTransport` here means every
+    command can be exercised end to end without a studio to talk to, which is
+    the only way error translation gets covered at all.
+    """
+
+    def __init__(
+        self,
+        url: str = DEFAULT_URL,
+        key: str = "",
+        *,
+        transport: httpx.BaseTransport | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.url = url.rstrip("/")
+        self._sleep = sleep
+        self._http = httpx.Client(
+            base_url=f"{self.url}/api",
+            # The one place the key is used. It is never logged, never echoed
+            # and never included in an error message: a CI log is a public
+            # artifact in more organisations than not.
+            headers={"Authorization": f"Bearer {key}"},
+            transport=transport,
+            timeout=timeout,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> StudioClient:
+        return self
+
+    def __exit__(self, *exception: object) -> None:
+        self.close()
+
+    def list_projects(self) -> list[dict[str, Any]]:
+        return list(self._request("GET", "/projects").json())
+
+    def get_project(self, project_id: str) -> dict[str, Any]:
+        return dict(self._request("GET", f"/projects/{project_id}").json())
+
+    def get_usage(self) -> dict[str, Any]:
+        return dict(self._request("GET", "/usage").json())
+
+    def get_plan(self) -> dict[str, Any] | None:
+        """The caller's plan and its limits, or None if this studio has none.
+
+        `/api/plan` is newer than some deployments, and `whoami` is the command
+        someone runs to check their key works at all. Reporting the plan from
+        `/usage` alone beats failing the one call whose whole job is to say "you
+        are connected", so a 404 here is an absence rather than an error.
+        """
+        response = self._send("GET", "/plan")
+        if response.status_code == httpx.codes.NOT_FOUND:
+            return None
+        return dict(self._checked(response).json())
+
+    def export(self, export_format: str, body: dict[str, Any]) -> bytes:
+        """Generate and return the archive bytes. The server regenerates from
+        the schema in `body`, so the same seed gives back the same rows."""
+        return self._request("POST", f"/export/{export_format}", json=body).content
+
+    def _request(
+        self, method: str, path: str, *, json: dict[str, Any] | None = None
+    ) -> httpx.Response:
+        return self._checked(self._send(method, path, json=json))
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        retried: bool = False,
+    ) -> httpx.Response:
+        """The call itself, with the one retry the API asks for. Status codes
+        are the caller's business; only an unreachable studio raises here."""
+        try:
+            response = self._http.request(method, path, json=json)
+        except httpx.HTTPError as error:
+            # Naming the URL is the whole message: nine times in ten this is a
+            # typo'd MODEL2DATA_STUDIO_URL or a self-hosted studio that is down,
+            # and neither is obvious from a connection error alone.
+            raise StudioError(f"Could not reach the studio at {self.url}: {error}") from error
+
+        if response.status_code == httpx.codes.TOO_MANY_REQUESTS and not retried:
+            # Honoured exactly once. Retrying until it works would turn a
+            # throttled key into a job that hangs; one polite wait covers the
+            # burst of a pipeline that regenerates several projects in a row.
+            self._sleep(_retry_after(response))
+            return self._send(method, path, json=json, retried=True)
+        return response
+
+    @staticmethod
+    def _checked(response: httpx.Response) -> httpx.Response:
+        if response.is_success:
+            return response
+        raise StudioError(_message(response))
+
+
+def _retry_after(response: httpx.Response) -> float:
+    """Seconds to wait, from the header, clamped to something a CI job survives."""
+    try:
+        wait = float(response.headers.get("Retry-After", ""))
+    except ValueError:
+        # An HTTP-date is legal here and rare in practice; a fixed short wait is
+        # a better answer than parsing dates for it.
+        wait = DEFAULT_RETRY_WAIT
+    return min(max(wait, 0.0), MAX_RETRY_WAIT)
+
+
+def _detail(response: httpx.Response) -> str:
+    """The API's own `detail`, which is written to be read by a person."""
+    try:
+        body = response.json()
+    except ValueError:
+        return response.text.strip()[:500]
+    if isinstance(body, dict):
+        detail = body.get("detail")
+        if isinstance(detail, str):
+            return detail
+        if isinstance(detail, list):
+            # FastAPI's validation errors. Flattened rather than dumped, so a
+            # rejected field reads as a sentence.
+            return "; ".join(str(item.get("msg", item)) for item in detail)
+    return str(body)[:500]
+
+
+def _message(response: httpx.Response) -> str:
+    status = response.status_code
+    if status == httpx.codes.UNAUTHORIZED:
+        # Not the API's own wording: signed out of a browser is a different
+        # situation from a key in an environment variable, and the fix here is
+        # always the variable.
+        return "The API key was refused. Check MODEL2DATA_STUDIO_KEY."
+    detail = _detail(response)
+    if status == httpx.codes.PAYMENT_REQUIRED:
+        # Shown as-is, deliberately: the API writes these to name the plan
+        # boundary that was hit, and rephrasing them here would mean two places
+        # describing the same limit and eventually disagreeing.
+        return detail
+    if status == httpx.codes.FORBIDDEN:
+        # Shown as-is, like a 402: the studio's own wording names the access
+        # the key has and the access the request needed, and the fix — a key
+        # created with more access — is not something this side can guess at.
+        return detail or "The studio refused this key's access."
+    if status == httpx.codes.TOO_MANY_REQUESTS:
+        return f"The studio is still rate limiting this key. {detail}".strip()
+    if status == httpx.codes.NOT_FOUND:
+        return detail or "The studio has no such thing."
+    return f"The studio refused the request ({status}). {detail}".strip()

model2data_studio/export.py

@@ -0,0 +1,191 @@
+"""What a saved project plus a set of overrides adds up to, as a request body.
+
+Extracted from `cli.py` when the MCP server arrived, for one reason: both of
+them have to resolve a generation the same way, and the rules are not obvious
+enough to write twice. The seed falls back to the project's and then to a random
+one that gets reported; the anchor day falls back to the project's and then to
+today; a single time-profile flag overrides one field and leaves the other two
+as the project saved them; `adapter` and `skew` are sent only when there is
+something to say, so this keeps working against a studio that predates them.
+
+Every one of those is a decision about *reproducibility*, and a second copy of
+them that drifted would mean the CLI and an agent generating from the same
+project, with the same arguments, getting different rows.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import random
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from .client import StudioError
+
+# Seeds are only useful if a person can read one back out of a log and retype
+# it, so they stay inside a signed 32-bit int rather than being as wide as the
+# engine would allow.
+MAX_RANDOM_SEED = 2**31 - 1
+
+
+def anchor_from(as_of: str | None) -> dt.datetime:
+    """The instant dates and timestamps are generated relative to.
+
+    A day rather than an instant, and midnight rather than the current time: the
+    anchor is something a person reads out of a CI log and retypes into a flag,
+    the same as a seed, and two runs on the same day should agree without
+    anyone having pinned anything yet. Today is the local date, since that is
+    the day the person reading the log calls today. The studio stores the same
+    `YYYY-MM-DD` on the project and sends the same midnight, so a day pinned
+    there and a day pinned here name the same rows.
+    """
+    if as_of is None:
+        return dt.datetime.combine(dt.date.today(), dt.time.min)
+    try:
+        return dt.datetime.combine(dt.date.fromisoformat(as_of), dt.time.min)
+    except ValueError:
+        raise StudioError(f"A day is wanted as YYYY-MM-DD, not {as_of!r}.") from None
+
+
+@dataclass(frozen=True)
+class Overrides:
+    """What the caller said, as opposed to what the project already says.
+
+    `None` everywhere means "the project decides", which is the point: a
+    pipeline passing nothing but a project id keeps producing whatever the
+    studio last previewed.
+    """
+
+    rows: int | None = None
+    row_overrides: Mapping[str, int] = field(default_factory=dict)
+    seed: int | None = None
+    as_of: str | None = None
+    locale: str | None = None
+    business_hours: bool | None = None
+    growth: float | None = None
+    seasonality: float | None = None
+    skew: float | None = None
+    project_name: str | None = None
+    adapter: str | None = None
+
+
+@dataclass(frozen=True)
+class Resolved:
+    """The request, and the two things about it worth telling the caller.
+
+    `picked_seed` and `picked_anchor` are true when nothing pinned them and
+    this run chose: both callers report what was chosen, because a run nobody
+    can reproduce afterwards is the failure mode this whole tool exists to
+    avoid.
+    """
+
+    body: dict[str, Any]
+    seed: int
+    anchor: dt.datetime
+    picked_seed: bool
+    picked_anchor: bool
+
+
+def resolve(
+    saved: Mapping[str, Any],
+    overrides: Overrides | None = None,
+    *,
+    choose_seed: Any = None,
+) -> Resolved:
+    """Turn a saved project into an export request body.
+
+    `choose_seed` is the random seed picker, injectable so a test can have a
+    predictable one.
+    """
+    overrides = overrides or Overrides()
+    pick = choose_seed or (lambda: random.randrange(1, MAX_RANDOM_SEED))
+
+    schema = saved.get("schema")
+    if schema is None:
+        # Nothing on the server can turn the project's DBML into tables -- the
+        # browser is the only parser there is. Saying so plainly beats a 422
+        # about a missing field.
+        raise StudioError(
+            "Open this project in the studio once so it saves its schema, then try again."
+        )
+
+    resolved_seed = overrides.seed if overrides.seed is not None else saved.get("seed")
+    picked_seed = resolved_seed is None
+    if picked_seed:
+        # An unpinned project generates different rows every run, which is fine
+        # in a browser and miserable in CI: a diff on every build with no way
+        # back to yesterday's data.
+        resolved_seed = pick()
+
+    # The argument, then the day the project itself is pinned on, then today --
+    # the same order as the seed. With the project's own day this run
+    # reproduces the rows the studio previewed, not merely the same rows as
+    # yesterday's run.
+    pinned = anchor_from(overrides.as_of) if overrides.as_of is not None else None
+    anchor = pinned or anchor_from(saved.get("asOf"))
+    picked_anchor = pinned is None and saved.get("asOf") is None
+
+    body: dict[str, Any] = {
+        "schema": schema,
+        "rows": overrides.rows if overrides.rows is not None else saved.get("rows", 100),
+        # Merged rather than replaced: naming one table's row count is not a
+        # request to drop the project's settings for every other table.
+        "rowOverrides": {**(saved.get("rowOverrides") or {}), **dict(overrides.row_overrides)},
+        "seed": resolved_seed,
+        "locale": overrides.locale if overrides.locale is not None else saved.get("locale"),
+        "projectName": overrides.project_name or saved.get("name") or "my_project",
+        # The day every date and timestamp is placed relative to. Left to the
+        # server, it would be the wall clock at the moment of the request, and
+        # a pinned seed would then reproduce its rows only until midnight --
+        # which is exactly when a nightly check runs.
+        "generatedAt": anchor.isoformat(),
+    }
+
+    # The argument wins; absent, the project's own saved target does. Only sent
+    # when one of the two says something, so this still works against a studio
+    # old enough to have never saved a target on the project at all.
+    adapter = overrides.adapter if overrides.adapter is not None else saved.get("adapter")
+    if adapter is not None:
+        body["adapter"] = adapter
+
+    saved_time_profile = saved.get("timeProfile") or {}
+    named = (overrides.business_hours, overrides.growth, overrides.seasonality)
+    if any(value is not None for value in named):
+        # Naming one field of the profile leaves the other two as the project
+        # saved them, the same way naming one table's row count does.
+        body["timeProfile"] = {
+            "businessHours": (
+                overrides.business_hours
+                if overrides.business_hours is not None
+                else saved_time_profile.get("businessHours", False)
+            ),
+            "growth": (
+                overrides.growth
+                if overrides.growth is not None
+                else saved_time_profile.get("growth", 0.0)
+            ),
+            "seasonality": (
+                overrides.seasonality
+                if overrides.seasonality is not None
+                else saved_time_profile.get("seasonality", 0.0)
+            ),
+        }
+    elif saved_time_profile:
+        body["timeProfile"] = saved_time_profile
+
+    skew = overrides.skew if overrides.skew is not None else saved.get("skew")
+    if skew:
+        # Only sent when there is something to shape, like `adapter`: this keeps
+        # working against a studio that does not know the field yet, and 0 means
+        # the same thing as leaving it out.
+        body["skew"] = skew
+
+    assert resolved_seed is not None
+    return Resolved(
+        body=body,
+        seed=int(resolved_seed),
+        anchor=anchor,
+        picked_seed=picked_seed,
+        picked_anchor=picked_anchor,
+    )