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

{wherobots_python_sdk-0.2.0/wherobots_python_sdk.egg-info → wherobots_python_sdk-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wherobots-python-sdk
-Version: 0.2.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
@@ -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.2.0 → wherobots_python_sdk-0.2.1}/README.md

@@ -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.2.0 → wherobots_python_sdk-0.2.1}/tests/test_client.py

@@ -447,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.2.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,
 )
 
 # ---------------------------------------------------------------------------
@@ -786,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.2.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.2.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.2.0 → wherobots_python_sdk-0.2.1}/wherobots/__version__.py

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

{wherobots_python_sdk-0.2.0 → wherobots_python_sdk-0.2.1}/wherobots/client.py

@@ -29,6 +29,8 @@ from wherobots.models import (
     RunMetricsResponse,
     RunPythonPayload,
     RunView,
+    UtilizationStats,
+    extract_instant_value,
 )
 from wherobots.utils.logger import get_logger
 from wherobots.utils.validation import validate_name
@@ -52,8 +54,55 @@ class WherobotsJob:
 
     Manages the lifecycle of Wherobots job runs including submission,
     monitoring, log streaming, and cancellation.
+
+    Use :meth:`from_run_id` to attach to an existing run for read-only
+    log/metrics access without binding a script.
     """
 
+    # Candidate metric key names. The metrics endpoint is server-defined
+    # and untyped (see ``RunMetricsResponse``); the UPPERCASE names are
+    # the current production keys, with lowercase fallbacks kept for
+    # forward-compat. Confirmed against run gt3oirei5widjk (2026-06-11).
+    _CPU_METRIC_KEYS: tuple[str, ...] = ("CPU_UTILIZATION_PERCENT", "cpu_usage", "cpu")
+    _MEM_METRIC_KEYS: tuple[str, ...] = (
+        "MEMORY_UTILIZATION_PERCENT",
+        "memory_usage",
+        "mem_usage",
+    )
+    _COST_METRIC_KEYS: tuple[str, ...] = ("COST_USD", "cost_usd")
+    _SU_METRIC_KEYS: tuple[str, ...] = ("CONSUMED_SPATIAL_UNITS", "consumed_spatial_units")
+
+    # Instance attribute type declarations. ``_init_defaults`` (called
+    # by both ``__init__`` and ``from_run_id``) assigns initial values
+    # for every name listed here. Adding a new instance attribute means
+    # one declaration here + one assignment in ``_init_defaults`` —
+    # both constructor paths then pick it up automatically.
+    script: str | None
+    name: str | None
+    runtime: str | None
+    region: str | None
+    version: str | None
+    timeout_seconds: int
+    args: list[str]
+    spark_configs: dict[str, str]
+    dependencies: list[dict[str, Any]]
+    spark_driver_disk_gb: int | None
+    spark_executor_disk_gb: int | None
+    s3_bucket: str | None
+    s3_prefix: str | None
+    jar_main_class: str | None
+    auto_upload: bool
+    is_jar: bool
+    run_id: str | None
+    # Status may be a string when the server returns a value the
+    # SDK's JobStatus enum doesn't recognize yet (forward-compat).
+    status: JobStatus | str | None
+    _last_log_cursor: int | str
+    _script_uri: str | None
+    _attached: bool
+    _config: WherobotsConfig
+    _api: RunsAPI
+
     def __init__(
         self,
         script: str,
@@ -130,9 +179,8 @@ class WherobotsJob:
                 f"spark_executor_disk_gb must be non-negative, got {spark_executor_disk_gb}"
             )
 
-        self.script = script
-        self.name = validate_name(name)
-        self.runtime = runtime.value if isinstance(runtime, Runtime) else runtime
+        self._init_defaults()
+
         region_value = region.value if isinstance(region, Region) else region
 
         # Deprecation warnings for s3_bucket / s3_prefix are emitted by
@@ -149,6 +197,9 @@ class WherobotsJob:
             request_timeout_seconds=request_timeout_seconds,
         )
 
+        self.script = script
+        self.name = validate_name(name)
+        self.runtime = runtime.value if isinstance(runtime, Runtime) else runtime
         # No hardcoded fallback: when neither the argument nor the config
         # supplies a region, leave it unset so the API applies the org default.
         self.region = region_value or self._config.region
@@ -164,20 +215,44 @@ class WherobotsJob:
         self.jar_main_class = jar_main_class
         self.auto_upload = auto_upload
 
-        self.run_id: str | None = None
-        # Status may be a string when the server returns a value the
-        # SDK's JobStatus enum doesn't recognize yet (forward-compat).
-        self.status: JobStatus | str | None = None
-        self._last_log_cursor: int | str = 0
-        self._script_uri: str | None = None
-
         self.is_jar = script.lower().endswith(".jar")
         if self.is_jar and not jar_main_class:
             raise WherobotsValidationError("jar_main_class is required for JAR files")
 
-        # Build the API layer
         self._api = RunsAPI.from_config(self._config)
 
+    def _init_defaults(self) -> None:
+        """Initialize instance attributes shared by every construction path.
+
+        Both ``__init__`` and :meth:`from_run_id` MUST call this first,
+        then override the subset of fields they own. Any new instance
+        attribute that lives on every ``WherobotsJob`` belongs here
+        (and in the class-level type declarations above) — adding it
+        in only one constructor would leave the other in a
+        partially-constructed state.
+        """
+        self.script = None
+        self.name = None
+        self.runtime = None
+        self.region = None
+        self.version = None
+        self.timeout_seconds = 0
+        self.args = []
+        self.spark_configs = {}
+        self.dependencies = []
+        self.spark_driver_disk_gb = None
+        self.spark_executor_disk_gb = None
+        self.s3_bucket = None
+        self.s3_prefix = None
+        self.jar_main_class = None
+        self.auto_upload = False
+        self.is_jar = False
+        self.run_id = None
+        self.status = None
+        self._last_log_cursor = 0
+        self._script_uri = None
+        self._attached = False
+
     # ------------------------------------------------------------------ #
     # Upload helpers
     # ------------------------------------------------------------------ #
@@ -200,6 +275,10 @@ class WherobotsJob:
         if self._script_uri:
             return self._script_uri
 
+        # Only reachable from submit(), which raises in attached mode
+        # before getting here. The asserts narrow ``str | None`` -> ``str``.
+        assert self.script is not None, "script must be set in submit-mode"
+
         if self._is_s3_uri(self.script):
             self._script_uri = self.script
         elif self.auto_upload:
@@ -240,6 +319,10 @@ class WherobotsJob:
     # ------------------------------------------------------------------ #
 
     def _build_payload(self) -> CreateRunPayload:
+        # Only reachable from submit(); attached instances raise earlier.
+        # Runtime is optional — the API applies the org default when unset.
+        assert self.name is not None, "name must be set in submit-mode"
+
         script_uri = self._prepare_script_uri()
 
         run_python: RunPythonPayload | None = None
@@ -278,6 +361,99 @@ class WherobotsJob:
             environment=environment,
         )
 
+    # ------------------------------------------------------------------ #
+    # Attach
+    # ------------------------------------------------------------------ #
+
+    @classmethod
+    def from_run_id(
+        cls,
+        run_id: str,
+        *,
+        api_key: str | None = None,
+        config: WherobotsConfig | None = None,
+        base_url: str | None = None,
+        region: str | None = None,
+        request_timeout_seconds: int | None = None,
+    ) -> WherobotsJob:
+        """Attach to an existing run for read-only log/metric access.
+
+        Unlike the regular constructor this does not require a script
+        or name — only a ``run_id``. The returned instance is read-only:
+        :meth:`submit` will raise. All other read methods (``get_logs``,
+        ``iter_logs``, ``poll_for_logs``, ``get_metrics``,
+        ``get_cpu_utilization``, ``get_mem_utilization``, ``get_status``,
+        ``cancel``, ``wait_for_completion``) work normally.
+
+        Args:
+            run_id: Run identifier from a prior submission, the CLI, or
+                the Wherobots UI.
+            api_key: Wherobots API key (or set ``WHEROBOTS_API_KEY``).
+            config: Pre-built ``WherobotsConfig`` to use instead of the
+                environment.
+            base_url: Override the API base URL.
+            region: AWS region override.
+            request_timeout_seconds: HTTP request timeout in seconds.
+
+        Returns:
+            A ``WherobotsJob`` bound to *run_id* with descriptive
+            fields (name, runtime, status, ...) hydrated from the API.
+
+        Raises:
+            WherobotsValidationError: If *run_id* is empty.
+            WherobotsAPIError: If the initial refresh fails.
+        """
+        if not run_id:
+            raise WherobotsValidationError("run_id must not be None or empty")
+
+        self = cls.__new__(cls)
+        self._init_defaults()
+
+        self._config = config or WherobotsConfig.from_env(
+            api_key=api_key,
+            region=region,
+            base_url=base_url,
+            request_timeout_seconds=request_timeout_seconds,
+        )
+        self._api = RunsAPI.from_config(self._config)
+
+        # Attached-mode overrides on top of _init_defaults().
+        self.run_id = run_id
+        self._attached = True
+        self.region = region or self._config.region
+        self.version = self._config.version
+        self.s3_bucket = self._config.s3_bucket
+        self.s3_prefix = self._config.s3_prefix
+
+        self.refresh()
+        return self
+
+    def refresh(self) -> RunView:
+        """Re-fetch the run from the API and update local fields.
+
+        Updates ``status``, ``name``, ``runtime``, ``region``, and
+        ``version`` in place. Works in both attached and submitted modes.
+
+        Returns:
+            The freshly fetched ``RunView``.
+
+        Raises:
+            WherobotsJobError: If ``run_id`` is not set.
+        """
+        if not self.run_id:
+            raise WherobotsJobError("No run_id bound. Call submit() or use from_run_id().")
+        run_view = self._api.get(self.run_id)
+        self.status = run_view.status
+        if run_view.name:
+            self.name = run_view.name
+        if run_view.runtime:
+            self.runtime = run_view.runtime
+        if run_view.region:
+            self.region = run_view.region
+        if run_view.version:
+            self.version = run_view.version
+        return run_view
+
     # ------------------------------------------------------------------ #
     # Lifecycle
     # ------------------------------------------------------------------ #
@@ -306,6 +482,10 @@ class WherobotsJob:
         Returns:
             Run ID
         """
+        if self._attached:
+            raise WherobotsValidationError(
+                "Cannot submit a job attached via from_run_id(); this instance is read-only."
+            )
         if self.run_id:
             logger.warning("Job already submitted with run_id: %s", self.run_id)
             return self.run_id
@@ -368,6 +548,52 @@ class WherobotsJob:
 
         return self._api.get_metrics(self.run_id)
 
+    def get_cpu_utilization(self) -> UtilizationStats:
+        """Get aggregated CPU utilization for the run.
+
+        Returns:
+            ``UtilizationStats`` with ``latest``/``max``/``avg``/``series``.
+            All fields are ``None``/empty when the CPU metric is absent
+            from the server response.
+        """
+        metrics = self.get_metrics()
+        return UtilizationStats.from_metric(
+            metrics.instant_metrics, metrics.series_metrics, self._CPU_METRIC_KEYS
+        )
+
+    def get_mem_utilization(self) -> UtilizationStats:
+        """Get aggregated memory utilization for the run.
+
+        Returns:
+            ``UtilizationStats`` with ``latest``/``max``/``avg``/``series``.
+            All fields are ``None``/empty when the memory metric is
+            absent from the server response.
+        """
+        metrics = self.get_metrics()
+        return UtilizationStats.from_metric(
+            metrics.instant_metrics, metrics.series_metrics, self._MEM_METRIC_KEYS
+        )
+
+    def get_cost(self) -> float | None:
+        """Get the run's total cost in USD.
+
+        Returns:
+            Cost in USD (e.g. ``16.90``), or ``None`` if the server did
+            not surface a cost for this run (typical for runs that are
+            still running or have not yet been billed).
+        """
+        metrics = self.get_metrics()
+        return extract_instant_value(metrics.instant_metrics, self._COST_METRIC_KEYS)
+
+    def get_consumed_spatial_units(self) -> float | None:
+        """Get the spatial units (SUs) consumed by the run.
+
+        Returns:
+            SUs consumed (e.g. ``11.27``), or ``None`` if not reported.
+        """
+        metrics = self.get_metrics()
+        return extract_instant_value(metrics.instant_metrics, self._SU_METRIC_KEYS)
+
     def iter_logs(
         self,
         cursor: int | str = 0,
@@ -442,6 +668,7 @@ class WherobotsJob:
                 )
 
             try:
+                prev_cursor = self._last_log_cursor
                 logs = self.get_logs(cursor=self._last_log_cursor)
 
                 for item in logs.items:
@@ -453,7 +680,12 @@ class WherobotsJob:
                 consecutive_errors = 0  # Reset on success
 
                 if not follow:
-                    break
+                    # Drain remaining pages, then exit. Mirror iter_logs:
+                    # stop when next_page is missing or the cursor doesn't
+                    # advance (server-side loop guard).
+                    if logs.next_page is None or logs.next_page == prev_cursor:
+                        break
+                    continue  # fetch the next page immediately, no sleep
 
                 run_view = self.get_status()
                 if is_terminal_status(run_view.status):
@@ -474,13 +706,13 @@ class WherobotsJob:
                     raise
                 consecutive_errors += 1
                 logger.error("Error polling logs (%d/%d): %s", consecutive_errors, max_errors, exc)
-                if consecutive_errors >= max_errors or not follow:
+                if consecutive_errors >= max_errors:
                     raise
                 time.sleep(interval)
             except Exception as exc:
                 consecutive_errors += 1
                 logger.error("Error polling logs (%d/%d): %s", consecutive_errors, max_errors, exc)
-                if consecutive_errors >= max_errors or not follow:
+                if consecutive_errors >= max_errors:
                     raise
                 time.sleep(interval)
 

{wherobots_python_sdk-0.2.0 → wherobots_python_sdk-0.2.1}/wherobots/models.py

@@ -944,6 +944,146 @@ class RunMetricsResponse:
         return d
 
 
+@dataclass
+class UtilizationStats:
+    """Aggregated utilization for a single metric (e.g. CPU or memory).
+
+    ``series`` is the raw time-series of ``(timestamp, value)`` points
+    as returned by the server, normalized to floats. ``latest`` /
+    ``max`` / ``avg`` are derived from that series for convenience.
+    All fields are ``None`` / empty when the metric was not present in
+    the response.
+    """
+
+    latest: float | None = None
+    max: float | None = None
+    avg: float | None = None
+    series: list[tuple[float, float]] = field(default_factory=list)
+
+    @classmethod
+    def from_metric(
+        cls,
+        instant: dict[str, Any],
+        series: dict[str, Any],
+        keys: tuple[str, ...],
+    ) -> UtilizationStats:
+        """Build stats from the server's untyped metric dicts.
+
+        Args:
+            instant: ``RunMetricsResponse.instant_metrics``.
+            series: ``RunMetricsResponse.series_metrics``.
+            keys: Candidate metric names to look up, in priority order.
+                The first key found in *series* (or *instant* as a
+                fallback) is used. Multiple candidates are supported
+                because metric names are server-defined and untyped.
+
+        Returns:
+            A populated ``UtilizationStats``, or an empty instance if
+            none of the candidate keys are present.
+
+        Note:
+            Tie-break is "first key with ≥1 parseable point wins" — once
+            we begin parsing a given key we do not fall through to
+            subsequent candidates, even if some points within that key
+            are malformed. In practice the primary (UPPERCASE) production
+            key matches and the lowercase aliases only get tried when the
+            primary key is entirely absent from the response.
+        """
+        points = cls._extract_series(series, keys)
+        if points:
+            values = [v for _, v in points]
+            return cls(
+                latest=values[-1],
+                max=max(values),
+                avg=sum(values) / len(values),
+                series=points,
+            )
+
+        instant_value = extract_instant_value(instant, keys)
+        if instant_value is not None:
+            return cls(latest=instant_value, max=instant_value, avg=instant_value)
+
+        return cls()
+
+    @staticmethod
+    def _extract_series(
+        series: dict[str, Any],
+        keys: tuple[str, ...],
+    ) -> list[tuple[float, float]]:
+        for key in keys:
+            raw = series.get(key)
+            if raw is None:
+                continue
+            data = _unwrap_metric_envelope(raw)
+            points: list[tuple[float, float]] = []
+            for item in data if isinstance(data, list) else []:
+                point = UtilizationStats._coerce_point(item)
+                if point is not None:
+                    points.append(point)
+            if points:
+                return points
+        return []
+
+    @staticmethod
+    def _coerce_point(item: Any) -> tuple[float, float] | None:
+        """Coerce a single series entry to ``(timestamp, value)``.
+
+        Accepts ``[ts, value]`` / ``(ts, value)`` tuples and dicts
+        with ``timestamp``/``value`` (or ``t``/``v``) keys. Returns
+        ``None`` for shapes that can't be coerced — silently skipped.
+        """
+        if isinstance(item, (list, tuple)) and len(item) == 2:
+            ts, value = item
+        elif isinstance(item, dict):
+            ts = item.get("timestamp", item.get("t"))
+            value = item.get("value", item.get("v"))
+        else:
+            return None
+        try:
+            return float(ts), float(value)
+        except (TypeError, ValueError):
+            return None
+
+
+def _unwrap_metric_envelope(value: Any) -> Any:
+    """Strip the server's ``{display_name, metric: {data, format}}`` wrapper.
+
+    The Wherobots metrics endpoint wraps each metric as
+    ``{"display_name": ..., "metric": {"data": ..., "format": ...}}``.
+    Returns ``data`` if present, otherwise the value untouched (so
+    callers tolerate raw lists/scalars too).
+    """
+    if isinstance(value, dict) and "metric" in value:
+        metric = value.get("metric")
+        if isinstance(metric, dict) and "data" in metric:
+            return metric["data"]
+    return value
+
+
+def extract_instant_value(
+    instant: dict[str, Any],
+    keys: tuple[str, ...],
+) -> float | None:
+    """Pull a scalar from ``instant_metrics`` by candidate key name.
+
+    Handles both the server's wrapped shape
+    (``{metric: {data: {value, timestamp}}}``) and a bare numeric
+    value. Returns ``None`` if no key matched or coercion failed.
+    """
+    for key in keys:
+        raw = instant.get(key)
+        if raw is None:
+            continue
+        data = _unwrap_metric_envelope(raw)
+        if isinstance(data, dict) and "value" in data:
+            data = data["value"]
+        try:
+            return float(data)
+        except (TypeError, ValueError):
+            continue
+    return None
+
+
 # ---------------------------------------------------------------------------
 # Pagination
 # ---------------------------------------------------------------------------

{wherobots_python_sdk-0.2.0 → wherobots_python_sdk-0.2.1/wherobots_python_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wherobots-python-sdk
-Version: 0.2.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
@@ -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