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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wherobots-python-sdk
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python SDK for Wherobots (currently covers the Jobs REST API)
 Author-email: Wherobots <support@wherobots.com>
 License-Expression: Apache-2.0
@@ -22,6 +22,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.33.0
+Requires-Dist: boto3>=1.34.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.4.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
@@ -187,7 +188,7 @@ WherobotsJob(
     spark_driver_disk_gb: int | None = None, # Driver disk size (GB)
     spark_executor_disk_gb: int | None = None, # Executor disk size (GB)
     jar_main_class: str | None = None,       # Main class (required for JARs)
-    auto_upload: bool = True,                # Upload local files to S3
+    auto_upload: bool = True,                # Upload local files to S3 (managed storage)
     base_url: str | None = None,             # Override API URL
     request_timeout_seconds: int | None = None,  # HTTP timeout
     config: WherobotsConfig | None = None,   # Full config object
@@ -202,6 +203,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,9 +233,39 @@ 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`). |
+| `add_file_dependency(file_path)` | `dict` | Create a file dependency dict (`.jar`, `.whl`, `.zip`, `.json`). Accepts an `s3://` URI or a local path — local paths are auto-uploaded to **managed storage** at `submit()` time. For non-managed destinations, upload via `FilesAPI` first and pass the resulting `s3://` URI. |
+
+#### 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
 
@@ -272,6 +308,80 @@ job = WherobotsJob(
 )
 ```
 
+##### Local Dependency Files
+
+`add_file_dependency` also accepts a **local path** to a `.whl`, `.jar`, `.zip`,
+or `.json`. The SDK uploads the file just before the job is submitted, fetching
+short-lived AWS STS credentials from the Wherobots API (`POST /storage/credentials`)
+and using boto3 multipart under the hood — no AWS credentials need to leave your
+environment.
+
+```python
+job = WherobotsJob(
+    script="my_job.py",                  # local script auto-upload still works
+    name="job-with-local-wheel",
+    dependencies=[
+        # Local wheel — uploaded to managed storage at submit() time
+        WherobotsJob.add_file_dependency("dist/mypkg-0.1.0-py3-none-any.whl"),
+        # Already-uploaded artifact — used as-is
+        WherobotsJob.add_file_dependency("s3://bucket/shared-libs/lib-2.0.jar"),
+        WherobotsJob.add_pypi_dependency("pandas", "2.0.3"),
+    ],
+)
+job.submit()
+```
+
+Auto-upload always targets the org's **managed storage**:
+
+| Artifact | Destination |
+|---|---|
+| Script (when `script` is a local path) | `s3://<managed.path>/scripts/<filename>` |
+| Dependency (when path is a local file) | `s3://<managed.path>/dependencies/<filename>` |
+
+Local dependency uploads honor the same `auto_upload` flag as the script —
+if `auto_upload=False`, attempting to submit a job with a local dependency
+path raises `WherobotsValidationError`. The 5 GiB cap on a single upload
+applies; for larger artifacts, pre-upload and pass an `s3://` URI.
+
+### Uploading to a Storage Integration
+
+`WherobotsJob` stays focused on job orchestration — it doesn't take any
+"where files go" kwargs. To upload to a [Storage Integration](https://docs.wherobots.com/latest/develop/storage-management/storage/)
+or a custom subdirectory, use `FilesAPI` directly and pass the resulting
+`s3://` URI to `WherobotsJob`:
+
+```python
+from wherobots import FilesAPI, WherobotsJob
+from wherobots.config import WherobotsConfig
+
+with FilesAPI.from_config(WherobotsConfig.from_env()) as files:
+    si = files.resolve_integration("customer-bucket")
+    # Build explicit destinations; upload_file is the "upload this file
+    # to this exact s3 path" primitive.
+    script_uri = files.upload_file(
+        "my_job.py",
+        files.dest_uri_for(si, "my_job.py", "job-scripts/sdk-e2e"),
+    )
+    wheel_uri = files.upload_file(
+        "dist/internal-lib-1.0.whl",
+        files.dest_uri_for(si, "internal-lib-1.0.whl", "job-scripts/sdk-e2e"),
+    )
+
+job = WherobotsJob(
+    script=script_uri,                              # already-uploaded URI
+    name="job-in-integration",
+    dependencies=[WherobotsJob.add_file_dependency(wheel_uri)],
+)
+job.submit()
+```
+
+Both artifacts land under `s3://<integration.path>/job-scripts/sdk-e2e/`.
+
+`FilesAPI` is also where to look for low-level controls (custom managed
+subdirs, raw `s3://` destinations, STS credential fetch for BYO upload
+tooling). See `FilesAPI.upload_file`, `upload_managed_file`,
+`upload_dependency`, `dest_uri_for`, and `get_storage_credentials`.
+
 #### JAR Jobs
 
 ```python

{wherobots_python_sdk-0.2.0 → wherobots_python_sdk-0.3.0}/README.md

@@ -154,7 +154,7 @@ WherobotsJob(
     spark_driver_disk_gb: int | None = None, # Driver disk size (GB)
     spark_executor_disk_gb: int | None = None, # Executor disk size (GB)
     jar_main_class: str | None = None,       # Main class (required for JARs)
-    auto_upload: bool = True,                # Upload local files to S3
+    auto_upload: bool = True,                # Upload local files to S3 (managed storage)
     base_url: str | None = None,             # Override API URL
     request_timeout_seconds: int | None = None,  # HTTP timeout
     config: WherobotsConfig | None = None,   # Full config object
@@ -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,9 +199,39 @@ 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`). |
+| `add_file_dependency(file_path)` | `dict` | Create a file dependency dict (`.jar`, `.whl`, `.zip`, `.json`). Accepts an `s3://` URI or a local path — local paths are auto-uploaded to **managed storage** at `submit()` time. For non-managed destinations, upload via `FilesAPI` first and pass the resulting `s3://` URI. |
+
+#### 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
 
@@ -239,6 +274,80 @@ job = WherobotsJob(
 )
 ```
 
+##### Local Dependency Files
+
+`add_file_dependency` also accepts a **local path** to a `.whl`, `.jar`, `.zip`,
+or `.json`. The SDK uploads the file just before the job is submitted, fetching
+short-lived AWS STS credentials from the Wherobots API (`POST /storage/credentials`)
+and using boto3 multipart under the hood — no AWS credentials need to leave your
+environment.
+
+```python
+job = WherobotsJob(
+    script="my_job.py",                  # local script auto-upload still works
+    name="job-with-local-wheel",
+    dependencies=[
+        # Local wheel — uploaded to managed storage at submit() time
+        WherobotsJob.add_file_dependency("dist/mypkg-0.1.0-py3-none-any.whl"),
+        # Already-uploaded artifact — used as-is
+        WherobotsJob.add_file_dependency("s3://bucket/shared-libs/lib-2.0.jar"),
+        WherobotsJob.add_pypi_dependency("pandas", "2.0.3"),
+    ],
+)
+job.submit()
+```
+
+Auto-upload always targets the org's **managed storage**:
+
+| Artifact | Destination |
+|---|---|
+| Script (when `script` is a local path) | `s3://<managed.path>/scripts/<filename>` |
+| Dependency (when path is a local file) | `s3://<managed.path>/dependencies/<filename>` |
+
+Local dependency uploads honor the same `auto_upload` flag as the script —
+if `auto_upload=False`, attempting to submit a job with a local dependency
+path raises `WherobotsValidationError`. The 5 GiB cap on a single upload
+applies; for larger artifacts, pre-upload and pass an `s3://` URI.
+
+### Uploading to a Storage Integration
+
+`WherobotsJob` stays focused on job orchestration — it doesn't take any
+"where files go" kwargs. To upload to a [Storage Integration](https://docs.wherobots.com/latest/develop/storage-management/storage/)
+or a custom subdirectory, use `FilesAPI` directly and pass the resulting
+`s3://` URI to `WherobotsJob`:
+
+```python
+from wherobots import FilesAPI, WherobotsJob
+from wherobots.config import WherobotsConfig
+
+with FilesAPI.from_config(WherobotsConfig.from_env()) as files:
+    si = files.resolve_integration("customer-bucket")
+    # Build explicit destinations; upload_file is the "upload this file
+    # to this exact s3 path" primitive.
+    script_uri = files.upload_file(
+        "my_job.py",
+        files.dest_uri_for(si, "my_job.py", "job-scripts/sdk-e2e"),
+    )
+    wheel_uri = files.upload_file(
+        "dist/internal-lib-1.0.whl",
+        files.dest_uri_for(si, "internal-lib-1.0.whl", "job-scripts/sdk-e2e"),
+    )
+
+job = WherobotsJob(
+    script=script_uri,                              # already-uploaded URI
+    name="job-in-integration",
+    dependencies=[WherobotsJob.add_file_dependency(wheel_uri)],
+)
+job.submit()
+```
+
+Both artifacts land under `s3://<integration.path>/job-scripts/sdk-e2e/`.
+
+`FilesAPI` is also where to look for low-level controls (custom managed
+subdirs, raw `s3://` destinations, STS credential fetch for BYO upload
+tooling). See `FilesAPI.upload_file`, `upload_managed_file`,
+`upload_dependency`, `dest_uri_for`, and `get_storage_credentials`.
+
 #### JAR Jobs
 
 ```python

{wherobots_python_sdk-0.2.0 → wherobots_python_sdk-0.3.0}/pyproject.toml

@@ -26,6 +26,7 @@ classifiers = [
 keywords = ["wherobots", "spark", "sedona", "geospatial", "jobs", "sdk", "rest-api"]
 dependencies = [
     "requests>=2.33.0",
+    "boto3>=1.34.0",
 ]
 
 [project.urls]
@@ -85,6 +86,13 @@ show_error_codes = true
 module = "tests.*"
 ignore_errors = true
 
+[[tool.mypy.overrides]]
+# boto3 / botocore ship runtime types in some versions but the
+# pre-commit mypy env doesn't install them. Declare the policy once
+# here rather than scattering per-import ``# type: ignore`` comments.
+module = ["boto3", "boto3.*", "botocore", "botocore.*"]
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 python_files = ["test_*.py"]