improved error message handling to use notification pattern instead of fast fail with exception

Author: james-rl

src/runloop_api_client/_utils/__init__.py

@@ -1,3 +1,4 @@
+# isort: skip_file
 from ._sync import asyncify as asyncify
 from ._proxy import LazyProxy as LazyProxy
 from ._utils import (
@@ -57,6 +58,7 @@
     maybe_transform as maybe_transform,
     async_maybe_transform as async_maybe_transform,
 )
+from ._validation import ValidationNotification as ValidationNotification
 from ._reflection import (
     function_has_argument as function_has_argument,
     assert_signatures_in_sync as assert_signatures_in_sync,

src/runloop_api_client/resources/blueprints.py

@@ -1,4 +1,5 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+# isort: skip_file
 
 from __future__ import annotations
 
@@ -14,7 +15,7 @@
     blueprint_create_from_inspection_params,
 )
 from .._types import NOT_GIVEN, Body, Omit, Query, Headers, NotGiven, SequenceNotStr, omit, not_given
-from .._utils import maybe_transform, async_maybe_transform
+from .._utils import maybe_transform, async_maybe_transform, ValidationNotification
 from .._compat import cached_property
 from .._resource import SyncAPIResource, AsyncAPIResource
 from .._response import (
@@ -51,32 +52,56 @@ class BlueprintRequestArgs(TypedDict, total=False):
 __all__ = ["BlueprintsResource", "AsyncBlueprintsResource", "BlueprintRequestArgs"]
 
 
-def _validate_file_mounts(file_mounts: Optional[Dict[str, str]] | Omit) -> None:
-    """Validate file_mounts are within size constraints.
+def _format_bytes(num_bytes: int) -> str:
+    """Format a byte count in a human-friendly way (KB/MB/GB).
+
+    Uses binary units (1024). Avoids decimals when exact.
+    """
+    if num_bytes < 1024:
+        return f"{num_bytes} bytes"
+    for factor, unit in ((1 << 30, "GB"), (1 << 20, "MB"), (1 << 10, "KB")):
+        if num_bytes >= factor:
+            value = num_bytes / factor
+            if float(value).is_integer():
+                return f"{int(value)} {unit}"
+            return f"{value:.1f} {unit}"
+    return f"{num_bytes} bytes"
+
+
+def _validate_file_mounts(file_mounts: Optional[Dict[str, str]] | Omit) -> ValidationNotification:
+    """Validate file_mounts are within size constraints: returns validation failures.
 
     Currently enforces a maximum per-file size to avoid server-side issues with
     large inline file contents. Also enforces a maximum total size across all
     file_mounts.
     """
 
+    note = ValidationNotification()
+
     if file_mounts is omit or file_mounts is None:
-        return
+        return note
 
     total_size_bytes = 0
     for mount_path, content in file_mounts.items():
         # Measure size in bytes using UTF-8 encoding since payloads are JSON strings
         size_bytes = len(content.encode("utf-8"))
         if size_bytes > FILE_MOUNT_MAX_SIZE_BYTES:
-            raise ValueError(
-                f"file_mount '{mount_path}' exceeds maximum size of {FILE_MOUNT_MAX_SIZE_BYTES} bytes. Use object_mounts instead."
+            over = size_bytes - FILE_MOUNT_MAX_SIZE_BYTES
+            note.add_error(
+                f"file_mount '{mount_path}' is {_format_bytes(over)} over the limit "
+                f"({_format_bytes(size_bytes)} / {_format_bytes(FILE_MOUNT_MAX_SIZE_BYTES)}). Use object_mounts instead."
             )
         total_size_bytes += size_bytes
 
     if total_size_bytes > FILE_MOUNT_TOTAL_MAX_SIZE_BYTES:
-        raise ValueError(
-            f"total file_mounts size exceeds maximum of {FILE_MOUNT_TOTAL_MAX_SIZE_BYTES} bytes. Use object_mounts instead."
+        total_over = total_size_bytes - FILE_MOUNT_TOTAL_MAX_SIZE_BYTES
+        note.add_error(
+            f"total file_mounts size is {_format_bytes(total_over)} over the limit "
+            f"({_format_bytes(total_size_bytes)} / {_format_bytes(FILE_MOUNT_TOTAL_MAX_SIZE_BYTES)}). Use object_mounts instead."
         )
 
+    return note
+
 
 class BlueprintsResource(SyncAPIResource):
     @cached_property
@@ -172,7 +197,9 @@ def create(
 
           idempotency_key: Specify a custom idempotency key for this request
         """
-        _validate_file_mounts(file_mounts)
+        note = _validate_file_mounts(file_mounts)
+        if note.has_errors():
+            raise ValueError(note.error_message())
 
         return self._post(
             "/v1/blueprints",
@@ -788,7 +815,9 @@ async def create(
 
           idempotency_key: Specify a custom idempotency key for this request
         """
-        _validate_file_mounts(file_mounts)
+        note = _validate_file_mounts(file_mounts)
+        if note.has_errors():
+            raise ValueError(note.error_message())
 
         return await self._post(
             "/v1/blueprints",

tests/api_resources/test_blueprints.py

@@ -112,7 +112,7 @@ def test_streaming_response_create(self, client: Runloop) -> None:
     def test_create_rejects_large_file_mount(self, client: Runloop) -> None:
         # 512KB + 1 byte
         too_large_content = "a" * (512 * 1024 + 1)
-        with pytest.raises(ValueError, match=r"exceeds maximum size"):
+        with pytest.raises(ValueError, match=r"over the limit"):
             client.blueprints.create(
                 name="name",
                 file_mounts={"/tmp/large.txt": too_large_content},
@@ -125,7 +125,7 @@ def test_create_rejects_total_file_mount_size(self, client: Runloop) -> None:
         content_a = "a" * per_file_max
         content_b = "b" * per_file_max
         content_c = "c" * 1
-        with pytest.raises(ValueError, match=r"total file_mounts size exceeds maximum"):
+        with pytest.raises(ValueError, match=r"total file_mounts size .* over the limit"):
             client.blueprints.create(
                 name="name",
                 file_mounts={
@@ -567,7 +567,7 @@ async def test_streaming_response_create(self, async_client: AsyncRunloop) -> No
     async def test_create_rejects_large_file_mount(self, async_client: AsyncRunloop) -> None:
         # 512KB + 1 byte
         too_large_content = "a" * (512 * 1024 + 1)
-        with pytest.raises(ValueError, match=r"exceeds maximum size"):
+        with pytest.raises(ValueError, match=r"over the limit"):
             await async_client.blueprints.create(
                 name="name",
                 file_mounts={"/tmp/large.txt": too_large_content},
@@ -580,7 +580,7 @@ async def test_create_rejects_total_file_mount_size(self, async_client: AsyncRun
         content_a = "a" * per_file_max
         content_b = "b" * per_file_max
         content_c = "c" * 1
-        with pytest.raises(ValueError, match=r"total file_mounts size exceeds maximum"):
+        with pytest.raises(ValueError, match=r"total file_mounts size .* over the limit"):
             await async_client.blueprints.create(
                 name="name",
                 file_mounts={