wherobots-python-sdk 0.1.0__tar.gz → 0.2.1__tar.gz

{wherobots_python_sdk-0.1.0 → wherobots_python_sdk-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wherobots-python-sdk
-Version: 0.1.0
+Version: 0.2.1
 Summary: Python SDK for Wherobots (currently covers the Jobs REST API)
 Author-email: Wherobots <support@wherobots.com>
 License-Expression: Apache-2.0
@@ -130,7 +130,7 @@ The API key can also be set via the `WHEROBOTS_API_KEY` environment variable.
 | Variable                           | Description                     | Default                              |
 |------------------------------------|---------------------------------|--------------------------------------|
 | `WHEROBOTS_API_KEY`                | API key                         | *(required)*                         |
-| `WHEROBOTS_REGION`                 | Default AWS region              | `aws-us-west-2`                      |
+| `WHEROBOTS_REGION`                 | Region override (else org default) | *(none — org default)*            |
 | `WHEROBOTS_API_BASE_URL`          | API base URL                    | `https://api.cloud.wherobots.com`    |
 | `WHEROBOTS_VERSION`               | Wherobots version               | `latest`                             |
 | `WHEROBOTS_REQUEST_TIMEOUT_SECONDS`| HTTP request timeout (seconds) | `30`                                 |
@@ -176,8 +176,8 @@ The primary class for managing job runs.
 WherobotsJob(
     script: str,                             # Path or S3 URI to .py or .jar
     name: str,                               # Job name (8-255 chars, [a-zA-Z0-9_\-.]+)
-    runtime: str | Runtime = "tiny",         # Compute size
-    region: str | Region | None = None,      # AWS region
+    runtime: str | Runtime | None = None,    # Compute size (None -> org default)
+    region: str | Region | None = None,      # Region; str passed as-is (None -> org default)
     api_key: str | None = None,              # API key (or env var)
     version: str | None = None,              # "latest" | "preview"
     timeout_seconds: int = 3600,             # Job timeout
@@ -202,6 +202,11 @@ WherobotsJob(
 | `get_status()` | `RunView` | Get current job status and full details. |
 | `get_logs(cursor=0, size=100)` | `LogsResponse` | Fetch a page of log entries. |
 | `get_metrics()` | `RunMetricsResponse` | Fetch CPU/memory metrics for the run. |
+| `get_cpu_utilization()` | `UtilizationStats` | Aggregated CPU utilization (`latest`, `max`, `avg`, `series`). |
+| `get_mem_utilization()` | `UtilizationStats` | Aggregated memory utilization (`latest`, `max`, `avg`, `series`). |
+| `get_cost()` | `float \| None` | Total run cost in USD, or `None` if not yet billed. |
+| `get_consumed_spatial_units()` | `float \| None` | Spatial Units (SUs) consumed by the run. |
+| `refresh()` | `RunView` | Re-fetch from the API and update `status`/`name`/`runtime`/`region`/`version` in place. |
 | `iter_logs(cursor=0, size=100)` | `Iterator[dict]` | Iterate over all log entries, handling pagination automatically. |
 | `poll_for_logs(follow=True, interval=2.0, log_handler=None, max_errors=10)` | `None` | Poll and print logs. If `follow=True`, continues until job completes. `max_errors` sets the max consecutive transient errors before giving up. |
 | `cancel()` | `bool` | Request cancellation. Returns `True` on success. |
@@ -227,10 +232,40 @@ with WherobotsJob(script="s3://bucket/script.py", name="my-job") as job:
 
 | Method | Returns | Description |
 |--------|---------|-------------|
+| `from_run_id(run_id, api_key=None, ...)` | `WherobotsJob` | Attach to an existing run for read-only log/metric access. No script required. `submit()` is disabled on the returned instance. |
 | `list_runs(...)` | `RunListPage` | List runs with optional filters. No instance required. |
 | `add_pypi_dependency(name, version)` | `dict` | Create a PyPI dependency dict for the `dependencies` parameter. |
 | `add_file_dependency(file_path)` | `dict` | Create a file dependency dict (`.jar`, `.whl`, `.zip`, `.json`). |
 
+#### Attaching to an Existing Run
+
+If you already have a `run_id` (from the CLI, the Wherobots UI, or a prior SDK
+session) you can attach without a script:
+
+```python
+from wherobots import WherobotsJob
+
+job = WherobotsJob.from_run_id("run-abc-123")
+print(job.status, job.name)
+
+# Stream remaining logs
+job.poll_for_logs(follow=False)
+
+# Or paginate
+for entry in job.iter_logs(size=200):
+    print(entry["raw"])
+
+# Aggregated utilization for a completed run
+cpu = job.get_cpu_utilization()
+print(f"CPU peak {cpu.max}, avg {cpu.avg}, samples {len(cpu.series)}")
+
+# Billing
+print(f"cost ${job.get_cost():.2f}, SUs {job.get_consumed_spatial_units()}")
+```
+
+Calling `job.submit()` on an attached instance raises
+`WherobotsValidationError` — these instances are read-only.
+
 #### Listing Runs
 
 ```python

{wherobots_python_sdk-0.1.0 → wherobots_python_sdk-0.2.1}/README.md

@@ -97,7 +97,7 @@ The API key can also be set via the `WHEROBOTS_API_KEY` environment variable.
 | Variable                           | Description                     | Default                              |
 |------------------------------------|---------------------------------|--------------------------------------|
 | `WHEROBOTS_API_KEY`                | API key                         | *(required)*                         |
-| `WHEROBOTS_REGION`                 | Default AWS region              | `aws-us-west-2`                      |
+| `WHEROBOTS_REGION`                 | Region override (else org default) | *(none — org default)*            |
 | `WHEROBOTS_API_BASE_URL`          | API base URL                    | `https://api.cloud.wherobots.com`    |
 | `WHEROBOTS_VERSION`               | Wherobots version               | `latest`                             |
 | `WHEROBOTS_REQUEST_TIMEOUT_SECONDS`| HTTP request timeout (seconds) | `30`                                 |
@@ -143,8 +143,8 @@ The primary class for managing job runs.
 WherobotsJob(
     script: str,                             # Path or S3 URI to .py or .jar
     name: str,                               # Job name (8-255 chars, [a-zA-Z0-9_\-.]+)
-    runtime: str | Runtime = "tiny",         # Compute size
-    region: str | Region | None = None,      # AWS region
+    runtime: str | Runtime | None = None,    # Compute size (None -> org default)
+    region: str | Region | None = None,      # Region; str passed as-is (None -> org default)
     api_key: str | None = None,              # API key (or env var)
     version: str | None = None,              # "latest" | "preview"
     timeout_seconds: int = 3600,             # Job timeout
@@ -169,6 +169,11 @@ WherobotsJob(
 | `get_status()` | `RunView` | Get current job status and full details. |
 | `get_logs(cursor=0, size=100)` | `LogsResponse` | Fetch a page of log entries. |
 | `get_metrics()` | `RunMetricsResponse` | Fetch CPU/memory metrics for the run. |
+| `get_cpu_utilization()` | `UtilizationStats` | Aggregated CPU utilization (`latest`, `max`, `avg`, `series`). |
+| `get_mem_utilization()` | `UtilizationStats` | Aggregated memory utilization (`latest`, `max`, `avg`, `series`). |
+| `get_cost()` | `float \| None` | Total run cost in USD, or `None` if not yet billed. |
+| `get_consumed_spatial_units()` | `float \| None` | Spatial Units (SUs) consumed by the run. |
+| `refresh()` | `RunView` | Re-fetch from the API and update `status`/`name`/`runtime`/`region`/`version` in place. |
 | `iter_logs(cursor=0, size=100)` | `Iterator[dict]` | Iterate over all log entries, handling pagination automatically. |
 | `poll_for_logs(follow=True, interval=2.0, log_handler=None, max_errors=10)` | `None` | Poll and print logs. If `follow=True`, continues until job completes. `max_errors` sets the max consecutive transient errors before giving up. |
 | `cancel()` | `bool` | Request cancellation. Returns `True` on success. |
@@ -194,10 +199,40 @@ with WherobotsJob(script="s3://bucket/script.py", name="my-job") as job:
 
 | Method | Returns | Description |
 |--------|---------|-------------|
+| `from_run_id(run_id, api_key=None, ...)` | `WherobotsJob` | Attach to an existing run for read-only log/metric access. No script required. `submit()` is disabled on the returned instance. |
 | `list_runs(...)` | `RunListPage` | List runs with optional filters. No instance required. |
 | `add_pypi_dependency(name, version)` | `dict` | Create a PyPI dependency dict for the `dependencies` parameter. |
 | `add_file_dependency(file_path)` | `dict` | Create a file dependency dict (`.jar`, `.whl`, `.zip`, `.json`). |
 
+#### Attaching to an Existing Run
+
+If you already have a `run_id` (from the CLI, the Wherobots UI, or a prior SDK
+session) you can attach without a script:
+
+```python
+from wherobots import WherobotsJob
+
+job = WherobotsJob.from_run_id("run-abc-123")
+print(job.status, job.name)
+
+# Stream remaining logs
+job.poll_for_logs(follow=False)
+
+# Or paginate
+for entry in job.iter_logs(size=200):
+    print(entry["raw"])
+
+# Aggregated utilization for a completed run
+cpu = job.get_cpu_utilization()
+print(f"CPU peak {cpu.max}, avg {cpu.avg}, samples {len(cpu.series)}")
+
+# Billing
+print(f"cost ${job.get_cost():.2f}, SUs {job.get_consumed_spatial_units()}")
+```
+
+Calling `job.submit()` on an attached instance raises
+`WherobotsValidationError` — these instances are read-only.
+
 #### Listing Runs
 
 ```python

{wherobots_python_sdk-0.1.0 → wherobots_python_sdk-0.2.1}/tests/test_api.py

@@ -145,6 +145,21 @@ class TestCreate:
         assert "/runs" in call_args[0][1]
         assert call_args[1]["params"]["region"] == "aws-us-east-1"
 
+    def test_omits_region_when_not_provided(self, api, mock_session):
+        mock_session.request.return_value = _make_response(
+            {"id": "r2", "name": "t", "status": "PENDING"}
+        )
+        payload = CreateRunPayload(
+            name="default-region-job",
+            run_python=RunPythonPayload(uri="s3://b/s.py"),
+        )
+        api.create(payload)  # no region -> API applies org default
+
+        call_kwargs = mock_session.request.call_args[1]
+        assert "region" not in call_kwargs["params"]
+        # runtime omitted from the body too -> org default applies
+        assert "runtime" not in call_kwargs["json"]
+
     def test_sends_payload_as_json(self, api, mock_session):
         mock_session.request.return_value = _make_response(
             {"id": "r1", "name": "test", "status": "PENDING"}

{wherobots_python_sdk-0.1.0 → wherobots_python_sdk-0.2.1}/tests/test_client.py

@@ -69,6 +69,37 @@ def test_build_payload_jar_job(mock_env):
     assert payload.run_python is None
 
 
+def test_no_region_or_runtime_uses_no_default(monkeypatch, mock_api_key):
+    """When neither arg, config, nor env supplies region/runtime, they stay
+    unset so the API applies the organization's configured defaults."""
+    monkeypatch.setenv("WHEROBOTS_API_KEY", mock_api_key)
+    monkeypatch.delenv("WHEROBOTS_REGION", raising=False)
+
+    job = WherobotsJob(script="s3://test-bucket/test-script.py", name="defaults-job")
+
+    assert job.region is None
+    assert job.runtime is None
+    payload = job._build_payload()
+    assert payload.runtime is None
+    assert "runtime" not in payload.to_dict()
+
+
+def test_string_region_runtime_passthrough(monkeypatch, mock_api_key):
+    """Raw region/runtime strings (e.g. BYOC regions) are kept as-is."""
+    monkeypatch.setenv("WHEROBOTS_API_KEY", mock_api_key)
+    monkeypatch.delenv("WHEROBOTS_REGION", raising=False)
+
+    job = WherobotsJob(
+        script="s3://test-bucket/test-script.py",
+        name="byoc-job",
+        runtime="x-large",
+        region="byoc-acme-us-east-1",
+    )
+
+    assert job.region == "byoc-acme-us-east-1"
+    assert job.runtime == "x-large"
+
+
 def test_submit_sets_run_id(mock_env, sample_job_config):
     job = WherobotsJob(**sample_job_config)
 
@@ -416,3 +447,221 @@ class TestS3DeprecationWarnings:
             )
         deprecations = [w for w in caught if issubclass(w.category, DeprecationWarning)]
         assert any("s3_prefix" in str(w.message) for w in deprecations)
+
+
+# ── from_run_id (attach to existing run) ────────────────────────────────
+
+
+class TestFromRunId:
+    """Read-only attach constructor — no script required."""
+
+    def test_from_run_id_hydrates_from_api(self, mock_env, mock_run_view):
+        with patch("wherobots.client.RunsAPI") as runs_cls:
+            api = _make_mock_api(run_view=mock_run_view)
+            runs_cls.from_config.return_value = api
+
+            job = WherobotsJob.from_run_id("run-123")
+
+            assert job.run_id == "run-123"
+            assert job._attached is True
+            assert job.name == "test-job-name"
+            assert job.runtime == "tiny"
+            assert job.status == JobStatus.PENDING
+            api.get.assert_called_once_with("run-123")
+
+    def test_from_run_id_empty_raises(self, mock_env):
+        with pytest.raises(WherobotsValidationError):
+            WherobotsJob.from_run_id("")
+
+    def test_attached_submit_raises(self, mock_env, mock_run_view):
+        with patch("wherobots.client.RunsAPI") as runs_cls:
+            runs_cls.from_config.return_value = _make_mock_api(run_view=mock_run_view)
+            job = WherobotsJob.from_run_id("run-123")
+
+        with pytest.raises(WherobotsValidationError, match="read-only"):
+            job.submit()
+
+    def test_attached_get_logs(self, mock_env, mock_run_view, mock_logs_response):
+        with patch("wherobots.client.RunsAPI") as runs_cls:
+            api = _make_mock_api(run_view=mock_run_view, logs_response=mock_logs_response)
+            runs_cls.from_config.return_value = api
+
+            job = WherobotsJob.from_run_id("run-123")
+            logs = job.get_logs(size=10)
+
+            assert len(logs.items) == 2
+            api.get_logs.assert_called_once_with("run-123", cursor=0, size=10)
+
+    def test_refresh_updates_fields(self, mock_env):
+        with patch("wherobots.client.RunsAPI") as runs_cls:
+            first = RunView.from_dict({"id": "r", "name": "n1", "status": "PENDING"})
+            second = RunView.from_dict(
+                {"id": "r", "name": "n2", "status": "COMPLETED", "runtime": "small"}
+            )
+            api = MagicMock()
+            api.get.side_effect = [first, second]
+            runs_cls.from_config.return_value = api
+
+            job = WherobotsJob.from_run_id("r")
+            assert job.status == JobStatus.PENDING
+
+            run_view = job.refresh()
+            assert run_view.status == JobStatus.COMPLETED
+            assert job.status == JobStatus.COMPLETED
+            assert job.name == "n2"
+            assert job.runtime == "small"
+
+
+# ── Utilization accessors ──────────────────────────────────────────────
+
+
+class TestUtilizationAccessors:
+    def test_cpu_utilization_from_series(self, mock_env, sample_job_config):
+        job = WherobotsJob(**sample_job_config)
+        job.run_id = "run-1"
+        metrics = RunMetricsResponse.from_dict(
+            {"series_metrics": {"cpu_usage": [[1.0, 10.0], [2.0, 30.0], [3.0, 20.0]]}}
+        )
+        job._api = _make_mock_api(metrics_response=metrics)
+
+        stats = job.get_cpu_utilization()
+        assert stats.latest == 20.0
+        assert stats.max == 30.0
+        assert stats.avg == pytest.approx(20.0)
+        assert stats.series == [(1.0, 10.0), (2.0, 30.0), (3.0, 20.0)]
+
+    def test_mem_utilization_falls_back_to_instant(self, mock_env, sample_job_config):
+        job = WherobotsJob(**sample_job_config)
+        job.run_id = "run-1"
+        metrics = RunMetricsResponse.from_dict(
+            {"series_metrics": {}, "instant_metrics": {"memory_usage": 0.42}}
+        )
+        job._api = _make_mock_api(metrics_response=metrics)
+
+        stats = job.get_mem_utilization()
+        assert stats.latest == 0.42
+        assert stats.max == 0.42
+        assert stats.avg == 0.42
+        assert stats.series == []
+
+    def test_utilization_absent_returns_empty(self, mock_env, sample_job_config):
+        job = WherobotsJob(**sample_job_config)
+        job.run_id = "run-1"
+        metrics = RunMetricsResponse.from_dict({"series_metrics": {}, "instant_metrics": {}})
+        job._api = _make_mock_api(metrics_response=metrics)
+
+        stats = job.get_cpu_utilization()
+        assert stats.latest is None
+        assert stats.max is None
+        assert stats.avg is None
+        assert stats.series == []
+
+    def test_real_api_shape_cpu_and_cost(self, mock_env, sample_job_config):
+        """End-to-end shape match against the actual API envelope."""
+        job = WherobotsJob(**sample_job_config)
+        job.run_id = "run-1"
+        metrics = RunMetricsResponse.from_dict(
+            {
+                "series_metrics": {
+                    "CPU_UTILIZATION_PERCENT": {
+                        "display_name": "CPU Utilization",
+                        "metric": {
+                            "data": [
+                                {"value": 5.0, "timestamp": 1000},
+                                {"value": 50.0, "timestamp": 1015},
+                            ],
+                            "format": "PERCENT",
+                        },
+                    },
+                    "MEMORY_UTILIZATION_PERCENT": {
+                        "display_name": "Memory Utilization",
+                        "metric": {
+                            "data": [{"value": 25.0, "timestamp": 1000}],
+                            "format": "PERCENT",
+                        },
+                    },
+                },
+                "instant_metrics": {
+                    "COST_USD": {
+                        "display_name": "Cost",
+                        "metric": {
+                            "data": {"value": 16.904, "timestamp": 1000},
+                            "format": "CURRENCY",
+                        },
+                    },
+                    "CONSUMED_SPATIAL_UNITS": {
+                        "display_name": "Spatial Units Consumed",
+                        "metric": {
+                            "data": {"value": 11.27, "timestamp": 1000},
+                            "format": "NUMBER",
+                        },
+                    },
+                },
+            }
+        )
+        job._api = _make_mock_api(metrics_response=metrics)
+
+        cpu = job.get_cpu_utilization()
+        assert cpu.latest == 50.0
+        assert cpu.max == 50.0
+        assert len(cpu.series) == 2
+
+        mem = job.get_mem_utilization()
+        assert mem.latest == 25.0
+
+        assert job.get_cost() == 16.904
+        assert job.get_consumed_spatial_units() == 11.27
+
+    def test_cost_missing_returns_none(self, mock_env, sample_job_config):
+        job = WherobotsJob(**sample_job_config)
+        job.run_id = "run-1"
+        metrics = RunMetricsResponse.from_dict({"series_metrics": {}, "instant_metrics": {}})
+        job._api = _make_mock_api(metrics_response=metrics)
+
+        assert job.get_cost() is None
+        assert job.get_consumed_spatial_units() is None
+
+
+class TestPollForLogsDrain:
+    """``poll_for_logs(follow=False)`` must drain ALL pages, not just one."""
+
+    def test_follow_false_drains_all_pages(self, mock_env, sample_job_config):
+        job = WherobotsJob(**sample_job_config)
+        job.run_id = "run-drain"
+
+        pages = [
+            LogsResponse(
+                items=[LogItem(raw=f"line-{i}") for i in range(3)],
+                next_page="cursor-1",
+            ),
+            LogsResponse(
+                items=[LogItem(raw=f"line-{i}") for i in range(3, 6)],
+                next_page="cursor-2",
+            ),
+            LogsResponse(
+                items=[LogItem(raw=f"line-{i}") for i in range(6, 8)],
+                next_page=None,
+            ),
+        ]
+        job._api = MagicMock()
+        job._api.get_logs.side_effect = pages
+
+        captured: list[dict] = []
+        job.poll_for_logs(follow=False, log_handler=captured.append)
+
+        assert [c["raw"] for c in captured] == [f"line-{i}" for i in range(8)]
+        assert job._api.get_logs.call_count == 3
+
+    def test_follow_false_stuck_cursor_breaks(self, mock_env, sample_job_config):
+        """Server returning the same cursor stops the drain (no infinite loop)."""
+        job = WherobotsJob(**sample_job_config)
+        job.run_id = "run-stuck"
+
+        stuck = LogsResponse(items=[LogItem(raw="x")], next_page=0)
+        job._api = MagicMock()
+        job._api.get_logs.return_value = stuck
+
+        captured: list[dict] = []
+        job.poll_for_logs(follow=False, log_handler=captured.append)
+
+        assert job._api.get_logs.call_count == 1

{wherobots_python_sdk-0.1.0 → wherobots_python_sdk-0.2.1}/tests/test_models.py

@@ -18,6 +18,8 @@ from wherobots.models import (
     RunMetricsResponse,
     RunPythonPayload,
     RunView,
+    UtilizationStats,
+    extract_instant_value,
 )
 
 # ---------------------------------------------------------------------------
@@ -196,6 +198,16 @@ class TestCreateRunPayload:
         out = payload.to_dict()
         assert "environment" not in out
 
+    def test_runtime_omitted_when_none(self):
+        payload = CreateRunPayload(name="no-runtime")
+        out = payload.to_dict()
+        assert "runtime" not in out
+
+    def test_runtime_included_when_set(self):
+        payload = CreateRunPayload(name="with-runtime", runtime="large")
+        out = payload.to_dict()
+        assert out["runtime"] == "large"
+
 
 # ---------------------------------------------------------------------------
 # RunView
@@ -776,3 +788,128 @@ class TestRunListPage:
         assert run.run_python.uri == "s3://b/s.py"
         assert run.triggered_by is not None
         assert run.triggered_by.email == "user@example.com"
+
+
+# ---------------------------------------------------------------------------
+# UtilizationStats.from_metric
+# ---------------------------------------------------------------------------
+
+
+class TestUtilizationStats:
+    def test_empty(self):
+        stats = UtilizationStats.from_metric({}, {}, ("cpu_usage",))
+        assert stats.latest is None
+        assert stats.max is None
+        assert stats.avg is None
+        assert stats.series == []
+
+    def test_series_list_of_pairs(self):
+        stats = UtilizationStats.from_metric(
+            {}, {"cpu_usage": [[0, 1.0], [1, 5.0], [2, 3.0]]}, ("cpu_usage",)
+        )
+        assert stats.series == [(0.0, 1.0), (1.0, 5.0), (2.0, 3.0)]
+        assert stats.latest == 3.0
+        assert stats.max == 5.0
+        assert stats.avg == 3.0
+
+    def test_series_list_of_dicts(self):
+        stats = UtilizationStats.from_metric(
+            {},
+            {"cpu_usage": [{"timestamp": 0, "value": 2.0}, {"t": 1, "v": 4.0}]},
+            ("cpu_usage",),
+        )
+        assert stats.series == [(0.0, 2.0), (1.0, 4.0)]
+        assert stats.max == 4.0
+
+    def test_instant_fallback_when_series_empty(self):
+        stats = UtilizationStats.from_metric({"memory_usage": 0.75}, {}, ("memory_usage",))
+        assert stats.latest == 0.75
+        assert stats.max == 0.75
+        assert stats.avg == 0.75
+        assert stats.series == []
+
+    def test_first_matching_key_wins(self):
+        stats = UtilizationStats.from_metric(
+            {},
+            {"cpu_utilization": [[0, 100.0]], "cpu": [[0, 50.0]]},
+            ("cpu_usage", "cpu_utilization", "cpu"),
+        )
+        assert stats.latest == 100.0
+
+    def test_unrecognized_shape_skipped(self):
+        stats = UtilizationStats.from_metric(
+            {},
+            {"cpu_usage": [[0, 1.0], "garbage", {"no": "fields"}, [1, 2.0]]},
+            ("cpu_usage",),
+        )
+        assert stats.series == [(0.0, 1.0), (1.0, 2.0)]
+
+    def test_non_numeric_instant_ignored(self):
+        stats = UtilizationStats.from_metric(
+            {"memory_usage": "not-a-number"}, {}, ("memory_usage",)
+        )
+        assert stats.latest is None
+        assert stats.series == []
+
+    def test_missing_keys(self):
+        stats = UtilizationStats.from_metric(
+            {"other": 1.0}, {"different": [[0, 1.0]]}, ("cpu_usage",)
+        )
+        assert stats.latest is None
+        assert stats.series == []
+
+    def test_real_api_envelope_series(self):
+        """Real API wraps values as {display_name, metric: {data, format}}."""
+        series = {
+            "CPU_UTILIZATION_PERCENT": {
+                "display_name": "CPU Utilization",
+                "metric": {
+                    "data": [
+                        {"value": 10.0, "timestamp": 1000},
+                        {"value": 30.0, "timestamp": 1015},
+                        {"value": 20.0, "timestamp": 1030},
+                    ],
+                    "format": "PERCENT",
+                },
+            }
+        }
+        stats = UtilizationStats.from_metric({}, series, ("CPU_UTILIZATION_PERCENT",))
+        assert stats.series == [(1000.0, 10.0), (1015.0, 30.0), (1030.0, 20.0)]
+        assert stats.latest == 20.0
+        assert stats.max == 30.0
+
+    def test_real_api_envelope_instant(self):
+        """Real API instant_metrics wrap a single point under metric.data."""
+        instant = {
+            "COST_USD": {
+                "display_name": "Cost",
+                "metric": {"data": {"value": 16.904, "timestamp": 1000}, "format": "CURRENCY"},
+            }
+        }
+        stats = UtilizationStats.from_metric(instant, {}, ("COST_USD",))
+        assert stats.latest == 16.904
+        assert stats.max == 16.904
+
+
+class TestExtractInstantValue:
+    def test_real_envelope(self):
+        instant = {
+            "COST_USD": {
+                "display_name": "Cost",
+                "metric": {"data": {"value": 16.904, "timestamp": 1000}, "format": "CURRENCY"},
+            }
+        }
+        assert extract_instant_value(instant, ("COST_USD",)) == 16.904
+
+    def test_bare_number(self):
+        assert extract_instant_value({"x": 42}, ("x",)) == 42.0
+
+    def test_missing_key(self):
+        assert extract_instant_value({"other": 1.0}, ("x",)) is None
+
+    def test_non_numeric_skipped(self):
+        assert extract_instant_value({"x": "nope"}, ("x", "y")) is None
+
+    def test_first_match_wins(self):
+        instant = {"a": 1.0, "b": 2.0}
+        assert extract_instant_value(instant, ("a", "b")) == 1.0

{wherobots_python_sdk-0.1.0 → wherobots_python_sdk-0.2.1}/tests/test_security.py

@@ -232,17 +232,62 @@ class TestPollForLogsErrorHandling:
         # Should not raise — error count resets after successful request
         job.poll_for_logs(follow=True, interval=0.01, max_errors=2)
 
-    def test_no_follow_does_not_retry(self, mock_env, sample_job_config):
-        """In oneshot mode (follow=False), errors should be raised immediately."""
+    def test_no_follow_retries_transient_then_raises(self, mock_env, sample_job_config):
+        """``follow=False`` drains multiple pages and must respect ``max_errors``
+        — transient 5xx are retried, only exhausting the budget propagates."""
         job = WherobotsJob(**sample_job_config)
         job.run_id = "run-nofollow"
         job._api = MagicMock()
         job._api.get_logs.side_effect = WherobotsAPIError("Server error", status_code=500)
 
-        with pytest.raises(WherobotsAPIError):
+        with pytest.raises(WherobotsAPIError, match="Server error"):
+            job.poll_for_logs(follow=False, interval=0.01, max_errors=3)
+        assert job._api.get_logs.call_count == 3
+
+    def test_no_follow_non_transient_raises_immediately(self, mock_env, sample_job_config):
+        """Non-transient 4xx (except 429) must propagate on the first hit even
+        in drain mode — we don't retry permission/validation errors."""
+        job = WherobotsJob(**sample_job_config)
+        job.run_id = "run-nofollow-4xx"
+        job._api = MagicMock()
+        job._api.get_logs.side_effect = WherobotsAPIError("Forbidden", status_code=403)
+
+        with pytest.raises(WherobotsAPIError, match="Forbidden"):
             job.poll_for_logs(follow=False, interval=0.01, max_errors=5)
         assert job._api.get_logs.call_count == 1
 
+    def test_no_follow_recovers_mid_drain(self, mock_env, sample_job_config):
+        """A transient error mid-drain should not abort the whole drain, and
+        the retry must reuse the un-advanced cursor (not skip the failed page)."""
+        job = WherobotsJob(**sample_job_config)
+        job.run_id = "run-nofollow-recover"
+
+        from wherobots.models import LogItem
+
+        pages = [
+            LogsResponse(items=[LogItem(raw="a")], next_page="c1"),
+            WherobotsAPIError("Transient", status_code=500),  # mid-drain blip
+            LogsResponse(items=[LogItem(raw="b")], next_page=None),
+        ]
+        job._api = MagicMock()
+        job._api.get_logs.side_effect = pages
+
+        captured: list[dict] = []
+        job.poll_for_logs(follow=False, interval=0.01, max_errors=3, log_handler=captured.append)
+        assert [c["raw"] for c in captured] == ["a", "b"]
+
+        # Pin retry semantics: the mock's side_effect list returns by call
+        # index, so without these assertions a buggy implementation that
+        # advanced the cursor past the failed page would still pass.
+        calls = job._api.get_logs.call_args_list
+        assert len(calls) == 3
+        assert calls[0].kwargs["cursor"] == 0
+        # The failed page (call 2) and its retry (call 3) MUST use the same
+        # cursor — the implementation must not advance past a page that errored.
+        assert calls[1].kwargs["cursor"] == "c1"
+        assert calls[2].kwargs["cursor"] == "c1"
+        assert calls[1] == calls[2]
+
 
 # =========================================================================== #
 # RunsAPI._parse_json()

{wherobots_python_sdk-0.1.0 → wherobots_python_sdk-0.2.1}/wherobots/__init__.py

@@ -39,6 +39,7 @@ from wherobots.models import (
     RunPythonPayload,
     RunView,
     StorageIntegration,
+    UtilizationStats,
 )
 
 # Convenience alias
@@ -84,4 +85,5 @@ __all__ = [
     "PyPiDependency",
     "FileDependency",
     "StorageIntegration",
+    "UtilizationStats",
 ]

{wherobots_python_sdk-0.1.0 → wherobots_python_sdk-0.2.1}/wherobots/__version__.py

@@ -1,5 +1,5 @@
 """Version information."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"
 __author__ = "Wherobots"
 __email__ = "support@wherobots.com"