hyperstudy 0.2.2__tar.gz → 0.2.3__tar.gz

{hyperstudy-0.2.2 → hyperstudy-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperstudy
-Version: 0.2.2
+Version: 0.2.3
 Summary: Python SDK for the HyperStudy experiment platform API
 Project-URL: Homepage, https://hyperstudy.io
 Project-URL: Documentation, https://docs.hyperstudy.io/developers/python-sdk

{hyperstudy-0.2.2 → hyperstudy-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hyperstudy"
-version = "0.2.2"
+version = "0.2.3"
 description = "Python SDK for the HyperStudy experiment platform API"
 readme = "README.md"
 license = "MIT"

{hyperstudy-0.2.2 → hyperstudy-0.2.3}/src/hyperstudy/__init__.py

@@ -19,7 +19,7 @@ from .exceptions import (
     ValidationError,
 )
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 __all__ = [
     "HyperStudy",

{hyperstudy-0.2.2 → hyperstudy-0.2.3}/src/hyperstudy/_downloads.py

@@ -38,13 +38,39 @@ def build_filename(recording: dict[str, Any]) -> str:
 
 
 def download_file(url: str, dest: Path, timeout: int = 300) -> int:
-    """Stream-download *url* to *dest* and return bytes written."""
+    """Stream-download *url* to *dest* and return bytes written.
+
+    Verifies ``Content-Length`` (when the server provides it) against bytes
+    actually written. On any error — HTTP, mid-stream disconnect, or length
+    mismatch — the partial file on disk is removed so ``skip_existing``
+    logic won't mistake it for a complete download on retry.
+    """
     resp = requests.get(url, stream=True, timeout=timeout)
     resp.raise_for_status()
 
+    expected: int | None
+    if "Content-Length" in resp.headers:
+        try:
+            expected = int(resp.headers["Content-Length"])
+        except (TypeError, ValueError):
+            expected = None
+    else:
+        expected = None
+
     written = 0
-    with open(dest, "wb") as fh:
-        for chunk in resp.iter_content(chunk_size=_CHUNK_SIZE):
-            fh.write(chunk)
-            written += len(chunk)
+    # BaseException so Ctrl-C also cleans up, not just exceptions.
+    try:
+        with open(dest, "wb") as fh:
+            for chunk in resp.iter_content(chunk_size=_CHUNK_SIZE):
+                fh.write(chunk)
+                written += len(chunk)
+
+        if expected is not None and written != expected:
+            raise IOError(
+                f"Truncated download: wrote {written} of {expected} bytes for {dest.name}"
+            )
+    except BaseException:
+        dest.unlink(missing_ok=True)
+        raise
+
     return written

{hyperstudy-0.2.2 → hyperstudy-0.2.3}/src/hyperstudy/_http.py

@@ -63,8 +63,14 @@ class HttpTransport:
     # Public helpers
     # ------------------------------------------------------------------
 
-    def get(self, path: str, params: dict[str, Any] | None = None) -> dict:
-        return self._request("GET", path, params=params)
+    def get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        *,
+        timeout: int | float | None = None,
+    ) -> dict:
+        return self._request("GET", path, params=params, timeout=timeout)
 
     def post(self, path: str, json: dict[str, Any] | None = None) -> dict:
         return self._request("POST", path, json=json)
@@ -81,7 +87,8 @@ class HttpTransport:
 
     def _request(self, method: str, path: str, **kwargs) -> dict:
         url = f"{self.base_url}/{path.lstrip('/')}"
-        kwargs.setdefault("timeout", self.timeout)
+        if kwargs.get("timeout") is None:
+            kwargs["timeout"] = self.timeout
 
         resp = self._session.request(method, url, **kwargs)
         return self._handle_response(resp)

{hyperstudy-0.2.2 → hyperstudy-0.2.3}/src/hyperstudy/_pagination.py

@@ -16,6 +16,7 @@ def fetch_all_pages(
     *,
     page_size: int = 1000,
     progress: bool = True,
+    timeout: int | float | None = None,
 ) -> tuple[list[dict], dict]:
     """Fetch every page of a paginated endpoint.
 
@@ -28,7 +29,7 @@ def fetch_all_pages(
     params.setdefault("offset", 0)
 
     # First request to learn total
-    body = transport.get(path, params=params)
+    body = transport.get(path, params=params, timeout=timeout)
     metadata = body.get("metadata", {})
     pagination = metadata.get("pagination", {})
     total = pagination.get("total", 0)
@@ -43,7 +44,7 @@ def fetch_all_pages(
     while has_more:
         params["offset"] = pagination.get("nextOffset", params["offset"] + page_size)
 
-        body = transport.get(path, params=params)
+        body = transport.get(path, params=params, timeout=timeout)
         metadata = body.get("metadata", {})
         pagination = metadata.get("pagination", {})
 

{hyperstudy-0.2.2 → hyperstudy-0.2.3}/src/hyperstudy/client.py

@@ -13,6 +13,7 @@ from ._downloads import build_filename, download_file, get_download_url
 from ._http import HttpTransport
 from ._pagination import fetch_all_pages
 from ._types import Scope
+from .exceptions import HyperStudyError
 from .experiments import ExperimentMixin
 
 
@@ -533,13 +534,24 @@ class HyperStudy(ExperimentMixin):
             pandas DataFrame with recording metadata plus ``local_path``
             and ``download_status`` columns.
         """
-        recordings = self.get_recordings(
-            scope_id,
-            scope=scope,
-            deployment_id=deployment_id,
-            room_id=room_id,
-            output="dict",
-        )
+        try:
+            # Signing per-recording GCS URLs scales with count; 30s default is too short.
+            recordings = self._fetch_data(
+                "recordings",
+                scope_id,
+                scope=scope,
+                deployment_id=deployment_id,
+                room_id=room_id,
+                output="dict",
+                timeout=300,
+            )
+        except Exception as exc:
+            raise HyperStudyError(
+                f"Failed to list recordings for {scope}={scope_id!r}: {exc}",
+                code=getattr(exc, "code", "LIST_RECORDINGS_FAILED"),
+                status_code=getattr(exc, "status_code", None),
+                details=getattr(exc, "details", None),
+            ) from exc
 
         if recording_type:
             recordings = [
@@ -566,7 +578,9 @@ class HyperStudy(ExperimentMixin):
 
             if skip_existing and dest.exists():
                 expected_size = rec.get("fileSize")
-                if expected_size is None or dest.stat().st_size == expected_size:
+                # Require positive size match; missing size → re-download to
+                # avoid trusting a truncated file from a prior failed run.
+                if expected_size is not None and dest.stat().st_size == expected_size:
                     local_paths.append(str(dest.resolve()))
                     statuses.append("skipped")
                     continue
@@ -582,6 +596,13 @@ class HyperStudy(ExperimentMixin):
                     f"Failed to download recording {rec.get('recordingId')}: {exc}"
                 )
 
+        failed_count = sum(1 for s in statuses if s == "failed")
+        if failed_count:
+            warnings.warn(
+                f"{failed_count}/{len(recordings)} recordings failed to download; "
+                "see the 'download_status' column for per-file results."
+            )
+
         df = to_pandas(recordings)
         if not df.empty:
             df["local_path"] = local_paths
@@ -649,6 +670,7 @@ class HyperStudy(ExperimentMixin):
         offset: int = 0,
         output: str = "pandas",
         progress: bool = True,
+        timeout: int | float | None = None,
         **extra_params,
     ):
         """Generic data-fetching logic shared by all ``get_*`` methods."""
@@ -675,11 +697,15 @@ class HyperStudy(ExperimentMixin):
         # Single page or all pages
         if limit is not None:
             params["limit"] = limit
-            body = self._transport.get(path, params=params)
+            body = self._transport.get(path, params=params, timeout=timeout)
             data = body.get("data", [])
         else:
             data, _ = fetch_all_pages(
-                self._transport, path, params=params, progress=progress
+                self._transport,
+                path,
+                params=params,
+                progress=progress,
+                timeout=timeout,
             )
 
         return self._convert_output(data, output)

{hyperstudy-0.2.2 → hyperstudy-0.2.3}/tests/test_client.py

@@ -356,6 +356,141 @@ def test_download_recordings_skip_existing(api_key, recordings_response, tmp_pat
     assert df["download_status"].iloc[1] == "downloaded"
 
 
+@responses.activate
+def test_download_recordings_skip_requires_known_size(
+    api_key, recordings_response, tmp_path
+):
+    """When server-side fileSize is missing, skip_existing must NOT accept a
+    stale on-disk file — it must re-download so truncated prior attempts
+    don't linger forever."""
+    # Strip fileSize from the video record to simulate older recordings where
+    # the backend didn't store file size metadata.
+    recordings_response["data"][0]["fileSize"] = None
+
+    responses.get(
+        f"{BASE_URL}/data/recordings/experiment/exp_abc123",
+        json=recordings_response,
+        status=200,
+    )
+
+    # Pre-create a (probably partial) video file on disk.
+    video_path = tmp_path / "Alice_video_EG_video_001.mp4"
+    video_path.write_bytes(b"stale-partial-content")
+
+    fresh_video = b"freshly downloaded video bytes" * 20
+    responses.get(
+        recordings_response["data"][0]["downloadUrl"],
+        body=fresh_video,
+        status=200,
+    )
+    responses.get(
+        recordings_response["data"][1]["downloadUrl"],
+        body=b"audio",
+        status=200,
+    )
+
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    df = client.download_recordings(
+        "exp_abc123", output_dir=str(tmp_path), progress=False, skip_existing=True
+    )
+
+    assert df["download_status"].iloc[0] == "downloaded"
+    assert video_path.read_bytes() == fresh_video
+
+
+def test_download_recordings_list_call_uses_long_timeout(
+    api_key, recordings_response, monkeypatch, tmp_path
+):
+    """The recordings-list call must use a longer timeout than the default
+    30s API timeout, because signing many GCS URLs on the backend can easily
+    push the listing latency past that."""
+    captured_timeouts = []
+
+    class FakeResp:
+        status_code = 200
+        ok = True
+        reason = "OK"
+
+        def json(self):
+            return recordings_response
+
+    def fake_request(method, url, **kwargs):
+        captured_timeouts.append(kwargs.get("timeout"))
+        return FakeResp()
+
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL, timeout=30)
+    monkeypatch.setattr(client._transport._session, "request", fake_request)
+
+    # Stub downloads so we don't need HTTP mocks for the signed URLs.
+    import hyperstudy.client as client_mod
+
+    monkeypatch.setattr(
+        client_mod, "download_file", lambda url, dest, **kw: dest.write_bytes(b"") or 0
+    )
+
+    client.download_recordings(
+        "exp_abc123", output_dir=str(tmp_path), progress=False, skip_existing=False
+    )
+
+    assert captured_timeouts, "no list call was made"
+    # First captured timeout is the recordings-list call.
+    assert captured_timeouts[0] is not None and captured_timeouts[0] >= 300, (
+        f"expected list-call timeout >= 300s, got {captured_timeouts[0]}"
+    )
+
+
+@responses.activate
+def test_download_recordings_raises_clear_error_on_list_failure(api_key, tmp_path):
+    """A failure fetching recording metadata must surface a HyperStudyError
+    that names the failing phase. Previously a bare ReadTimeout/ServerError
+    leaked out, giving users no hint whether the list or a download failed."""
+    from hyperstudy.exceptions import HyperStudyError
+
+    responses.get(
+        f"{BASE_URL}/data/recordings/experiment/exp_abc123",
+        status=504,
+        json={
+            "status": "error",
+            "error": {"code": "GATEWAY_TIMEOUT", "message": "upstream timeout"},
+        },
+    )
+
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    with pytest.raises(HyperStudyError, match="[Ll]ist recordings"):
+        client.download_recordings("exp_abc123", output_dir=str(tmp_path), progress=False)
+
+
+@responses.activate
+def test_download_recordings_warns_summary_on_partial_failure(
+    api_key, recordings_response, tmp_path
+):
+    """When some files fail to download, a single summary warning must
+    surface so interactive users see the failure count at a glance."""
+    responses.get(
+        f"{BASE_URL}/data/recordings/experiment/exp_abc123",
+        json=recordings_response,
+        status=200,
+    )
+    # Video download fails with 404; audio succeeds.
+    responses.get(recordings_response["data"][0]["downloadUrl"], status=404)
+    responses.get(
+        recordings_response["data"][1]["downloadUrl"], body=b"audio", status=200
+    )
+
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        df = client.download_recordings(
+            "exp_abc123", output_dir=str(tmp_path), progress=False
+        )
+
+    messages = [str(w.message) for w in caught]
+    assert any("1" in m and "2" in m and "failed" in m.lower() for m in messages), (
+        f"expected a '1/2 failed' summary warning, got: {messages}"
+    )
+    assert list(df["download_status"]) == ["failed", "downloaded"]
+
+
 @responses.activate
 def test_download_recording_single(api_key, tmp_path):
     """download_recording downloads a single file."""

hyperstudy-0.2.3/tests/test_downloads.py

@@ -0,0 +1,188 @@
+"""Tests for recording download helpers."""
+
+from __future__ import annotations
+
+import pytest
+import responses
+
+from hyperstudy._downloads import build_filename, download_file
+
+# ------------------------------------------------------------------
+# build_filename
+# ------------------------------------------------------------------
+
+
+VIDEO_RECORDING = {
+    "recordingId": "EG_video_001",
+    "participantName": "Alice",
+    "format": "mp4",
+    "metadata": {"type": "video"},
+}
+
+AUDIO_RECORDING = {
+    "recordingId": "EG_audio_002",
+    "participantName": "Alice",
+    "format": "webm",
+    "metadata": {"type": "audio"},
+}
+
+
+def test_build_filename_video():
+    assert build_filename(VIDEO_RECORDING) == "Alice_video_EG_video_001.mp4"
+
+
+def test_build_filename_audio():
+    assert build_filename(AUDIO_RECORDING) == "Alice_audio_EG_audio_002.webm"
+
+
+def test_build_filename_missing_fields():
+    rec = {"egressId": "EG_123"}
+    name = build_filename(rec)
+    assert name == "unknown_recording_EG_123.mp4"
+
+
+def test_build_filename_sanitizes_name():
+    rec = {
+        "recordingId": "EG_001",
+        "participantName": "Alice O'Brien (test)",
+        "format": "mp4",
+        "metadata": {"type": "video"},
+    }
+    name = build_filename(rec)
+    assert name == "Alice_O_Brien__test__video_EG_001.mp4"
+    # No special characters remain
+    assert "'" not in name
+    assert "(" not in name
+
+
+def test_build_filename_uses_participant_id_fallback():
+    rec = {
+        "recordingId": "EG_001",
+        "participantId": "user_42",
+        "format": "mp4",
+        "metadata": {"type": "video"},
+    }
+    assert build_filename(rec) == "user_42_video_EG_001.mp4"
+
+
+def test_build_filename_audio_default_format():
+    """Audio recording with no format field defaults to webm."""
+    rec = {
+        "recordingId": "EG_001",
+        "participantName": "Bob",
+        "metadata": {"type": "audio"},
+    }
+    assert build_filename(rec).endswith(".webm")
+
+
+# ------------------------------------------------------------------
+# download_file
+# ------------------------------------------------------------------
+
+
+@responses.activate
+def test_download_file(tmp_path):
+    url = "https://storage.example.com/file.mp4"
+    content = b"fake video content " * 100
+    responses.get(url, body=content, status=200)
+
+    dest = tmp_path / "output.mp4"
+    written = download_file(url, dest)
+
+    assert dest.exists()
+    assert dest.read_bytes() == content
+    assert written == len(content)
+
+
+@responses.activate
+def test_download_file_raises_on_error(tmp_path):
+    url = "https://storage.example.com/missing.mp4"
+    responses.get(url, status=404)
+
+    dest = tmp_path / "output.mp4"
+    with pytest.raises(Exception):
+        download_file(url, dest)
+
+
+@responses.activate
+def test_download_file_detects_content_length_mismatch(tmp_path):
+    """If the response ends with fewer bytes than Content-Length advertised,
+    an error must propagate AND the partial file must be removed so it can't
+    be mistaken for a complete download on retry."""
+    url = "https://storage.example.com/truncated.mp4"
+    short_body = b"only-1kb" * 128  # 1024 bytes
+    # Lie about the length: claim 10x larger than what we send.
+    responses.get(
+        url,
+        body=short_body,
+        status=200,
+        headers={"Content-Length": str(len(short_body) * 10)},
+    )
+
+    dest = tmp_path / "truncated.mp4"
+    with pytest.raises(Exception):
+        download_file(url, dest)
+
+    assert not dest.exists(), "partial file must be deleted on truncation"
+
+
+def test_download_file_raises_on_short_body_without_protocol_error(tmp_path, monkeypatch):
+    """Guards the explicit Content-Length check: when the HTTP layer itself
+    does NOT detect a short body (e.g. server closes cleanly after fewer
+    bytes than advertised), download_file must still raise and clean up."""
+
+    class ShortResponse:
+        status_code = 200
+        headers = {"Content-Length": "1000"}
+
+        def raise_for_status(self):
+            return None
+
+        def iter_content(self, chunk_size):
+            # Deliberately yield fewer bytes than Content-Length claims,
+            # then stop cleanly — urllib3 won't notice.
+            yield b"x" * 10
+
+    import hyperstudy._downloads as downloads_mod
+
+    monkeypatch.setattr(
+        downloads_mod.requests, "get", lambda *a, **kw: ShortResponse()
+    )
+
+    dest = tmp_path / "short.mp4"
+    with pytest.raises(IOError, match="[Tt]runcated"):
+        download_file("https://example.com/short.mp4", dest)
+
+    assert not dest.exists()
+
+
+@responses.activate
+def test_download_file_cleans_up_on_stream_error(tmp_path):
+    """If iter_content raises mid-stream, the partial file must be removed."""
+    url = "https://storage.example.com/explode.mp4"
+
+    class ExplodingResponse:
+        status_code = 200
+        headers: dict = {}
+
+        def raise_for_status(self):
+            return None
+
+        def iter_content(self, chunk_size):
+            yield b"first-chunk"
+            raise ConnectionError("simulated network drop")
+
+    import hyperstudy._downloads as downloads_mod
+
+    def fake_get(url, stream, timeout):  # noqa: ARG001
+        return ExplodingResponse()
+
+    original = downloads_mod.requests.get
+    downloads_mod.requests.get = fake_get
+    try:
+        dest = tmp_path / "explode.mp4"
+        with pytest.raises(ConnectionError):
+            download_file(url, dest)
+        assert not dest.exists(), "partial file must be deleted on mid-stream error"
+    finally:
+        downloads_mod.requests.get = original

hyperstudy-0.2.3/tests/test_http.py

@@ -0,0 +1,54 @@
+"""Tests for the HttpTransport wrapper."""
+
+from __future__ import annotations
+
+from hyperstudy._http import HttpTransport
+
+
+class _FakeResponse:
+    status_code = 200
+    ok = True
+    reason = "OK"
+
+    def json(self):
+        return {"status": "success", "data": [], "metadata": {}}
+
+
+def _make_transport(timeout=30):
+    return HttpTransport(api_key="hst_test_key", timeout=timeout)
+
+
+def test_get_uses_instance_timeout_by_default(monkeypatch):
+    transport = _make_transport(timeout=30)
+    captured = {}
+
+    def fake_request(method, url, **kwargs):
+        captured.update(kwargs)
+        return _FakeResponse()
+
+    monkeypatch.setattr(transport._session, "request", fake_request)
+
+    transport.get("/data/ping")
+
+    assert captured["timeout"] == 30
+
+
+def test_get_accepts_per_call_timeout_override(monkeypatch):
+    """A per-call timeout must override the instance default without
+    mutating it — critical so download_recordings can give the list call
+    a longer window than other API calls."""
+    transport = _make_transport(timeout=30)
+    captured = []
+
+    def fake_request(method, url, **kwargs):
+        captured.append(kwargs)
+        return _FakeResponse()
+
+    monkeypatch.setattr(transport._session, "request", fake_request)
+
+    transport.get("/data/slow", timeout=300)
+    transport.get("/data/normal")
+
+    assert captured[0]["timeout"] == 300
+    assert captured[1]["timeout"] == 30
+    assert transport.timeout == 30  # unchanged

hyperstudy-0.2.2/tests/test_downloads.py

@@ -1,105 +0,0 @@
-"""Tests for recording download helpers."""
-
-from __future__ import annotations
-
-import responses
-import pytest
-
-from hyperstudy._downloads import build_filename, download_file
-
-
-# ------------------------------------------------------------------
-# build_filename
-# ------------------------------------------------------------------
-
-
-VIDEO_RECORDING = {
-    "recordingId": "EG_video_001",
-    "participantName": "Alice",
-    "format": "mp4",
-    "metadata": {"type": "video"},
-}
-
-AUDIO_RECORDING = {
-    "recordingId": "EG_audio_002",
-    "participantName": "Alice",
-    "format": "webm",
-    "metadata": {"type": "audio"},
-}
-
-
-def test_build_filename_video():
-    assert build_filename(VIDEO_RECORDING) == "Alice_video_EG_video_001.mp4"
-
-
-def test_build_filename_audio():
-    assert build_filename(AUDIO_RECORDING) == "Alice_audio_EG_audio_002.webm"
-
-
-def test_build_filename_missing_fields():
-    rec = {"egressId": "EG_123"}
-    name = build_filename(rec)
-    assert name == "unknown_recording_EG_123.mp4"
-
-
-def test_build_filename_sanitizes_name():
-    rec = {
-        "recordingId": "EG_001",
-        "participantName": "Alice O'Brien (test)",
-        "format": "mp4",
-        "metadata": {"type": "video"},
-    }
-    name = build_filename(rec)
-    assert name == "Alice_O_Brien__test__video_EG_001.mp4"
-    # No special characters remain
-    assert "'" not in name
-    assert "(" not in name
-
-
-def test_build_filename_uses_participant_id_fallback():
-    rec = {
-        "recordingId": "EG_001",
-        "participantId": "user_42",
-        "format": "mp4",
-        "metadata": {"type": "video"},
-    }
-    assert build_filename(rec) == "user_42_video_EG_001.mp4"
-
-
-def test_build_filename_audio_default_format():
-    """Audio recording with no format field defaults to webm."""
-    rec = {
-        "recordingId": "EG_001",
-        "participantName": "Bob",
-        "metadata": {"type": "audio"},
-    }
-    assert build_filename(rec).endswith(".webm")
-
-
-# ------------------------------------------------------------------
-# download_file
-# ------------------------------------------------------------------
-
-
-@responses.activate
-def test_download_file(tmp_path):
-    url = "https://storage.example.com/file.mp4"
-    content = b"fake video content " * 100
-    responses.get(url, body=content, status=200)
-
-    dest = tmp_path / "output.mp4"
-    written = download_file(url, dest)
-
-    assert dest.exists()
-    assert dest.read_bytes() == content
-    assert written == len(content)
-
-
-@responses.activate
-def test_download_file_raises_on_error(tmp_path):
-    url = "https://storage.example.com/missing.mp4"
-    responses.get(url, status=404)
-
-    dest = tmp_path / "output.mp4"
-    with pytest.raises(Exception):
-        download_file(url, dest)