drukbox-python-sdk 0.3.0__tar.gz → 0.4.0__tar.gz

{drukbox_python_sdk-0.3.0 → drukbox_python_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: drukbox-python-sdk
-Version: 0.3.0
+Version: 0.4.0
 Summary: Async Python client for Drukbox.
 Project-URL: Homepage, https://github.com/clawhaven/drukbox-python-sdk
 Project-URL: Repository, https://github.com/clawhaven/drukbox-python-sdk
@@ -59,6 +59,8 @@ finally:
 few minutes worst case. The SDK's default `timeout` (300s) covers this. Pass
 an `idempotency_key` for retry safety: a retry with the same key after a
 successful provision returns the original host instead of creating a duplicate.
+A provider at its host limit raises `SandboxCapacityError`, a
+`SandboxUnavailableError` whose `retry_after` gives the seconds to wait.
 
 `SandboxAPI.from_env(prefix="SANDBOX_")` reads
 `SANDBOX_SERVICE_URL`, `SANDBOX_SERVICE_TOKEN`, and optional

{drukbox_python_sdk-0.3.0 → drukbox_python_sdk-0.4.0}/README.md

@@ -46,6 +46,8 @@ finally:
 few minutes worst case. The SDK's default `timeout` (300s) covers this. Pass
 an `idempotency_key` for retry safety: a retry with the same key after a
 successful provision returns the original host instead of creating a duplicate.
+A provider at its host limit raises `SandboxCapacityError`, a
+`SandboxUnavailableError` whose `retry_after` gives the seconds to wait.
 
 `SandboxAPI.from_env(prefix="SANDBOX_")` reads
 `SANDBOX_SERVICE_URL`, `SANDBOX_SERVICE_TOKEN`, and optional

{drukbox_python_sdk-0.3.0 → drukbox_python_sdk-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "drukbox-python-sdk"
-version = "0.3.0"
+version = "0.4.0"
 description = "Async Python client for Drukbox."
 readme = "README.md"
 license = "MIT"

{drukbox_python_sdk-0.3.0 → drukbox_python_sdk-0.4.0}/src/drukbox_sdk/__init__.py

@@ -19,6 +19,7 @@ from .api import (
 from .exceptions import (
     SandboxAPIError,
     SandboxAuthError,
+    SandboxCapacityError,
     SandboxConflictError,
     SandboxNotFoundError,
     SandboxProvisioningError,
@@ -36,6 +37,7 @@ __all__ = [
     "SandboxAPI",
     "SandboxAPIError",
     "SandboxAuthError",
+    "SandboxCapacityError",
     "SandboxConflictError",
     "SandboxHost",
     "SandboxNotFoundError",

{drukbox_python_sdk-0.3.0 → drukbox_python_sdk-0.4.0}/src/drukbox_sdk/api.py

@@ -47,6 +47,7 @@ import httpx
 
 from .exceptions import (
     SandboxAuthError,
+    SandboxCapacityError,
     SandboxConflictError,
     SandboxNotFoundError,
     SandboxProvisioningError,
@@ -435,14 +436,15 @@ class SandboxAPI:
         base_image: str | None = None,
         label: str | None = None,
     ) -> SandboxTemplate:
-        """Start a template build and return immediately.
-
-        The service responds 202 with ``status="building"``. Poll
-        :meth:`get_template` until the status becomes ``"available"`` or
-        ``"failed"``. A failed record carries the reason in
-        ``last_error``. A repeated post with the same provider, base
-        image, and setup script returns the existing record without a
-        rebuild.
+        """Start a template build.
+
+        The service pulls the base image, then responds 202 with
+        ``status="building"``. Poll :meth:`get_template` until the status
+        becomes ``"available"`` or ``"failed"``. A failed record carries the
+        reason in ``last_error``. A repeated post with the same provider,
+        base image digest, and setup script returns the existing record. A
+        ``"failed"`` record builds again and keeps its ``last_error`` until
+        that build ends.
         """
 
         payload: dict[str, Any] = {"setup_script": setup_script}
@@ -614,6 +616,11 @@ class SandboxAPI:
             raise SandboxProvisioningError(json_response.get("detail", "provisioning failed"))
 
         if response.status_code == 503:
+            if json_response.get("error_code") == "CAPACITY":
+                raise SandboxCapacityError(
+                    json_response.get("detail", "provider at host limit"),
+                    retry_after=int(response.headers["Retry-After"]),
+                )
             raise SandboxUnavailableError(json_response.get("detail", "service unavailable"))
 
         if response.status_code == 422:

{drukbox_python_sdk-0.3.0 → drukbox_python_sdk-0.4.0}/src/drukbox_sdk/exceptions.py

@@ -18,6 +18,18 @@ class SandboxUnavailableError(RuntimeError):
     """
 
 
+class SandboxCapacityError(SandboxUnavailableError):
+    """503 — the provider is at its host limit.
+
+    ``retry_after`` is the service's ``Retry-After`` value in seconds:
+    wait at least that long before the next create.
+    """
+
+    def __init__(self, message: str, retry_after: int) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
 class SandboxAPIError(RuntimeError):
     """Base for any error the sandbox service returned via HTTP."""
 

{drukbox_python_sdk-0.3.0 → drukbox_python_sdk-0.4.0}/tests/test_api.py

@@ -28,6 +28,7 @@ from drukbox_sdk import (
     Issuer,
     SandboxAPI,
     SandboxAuthError,
+    SandboxCapacityError,
     SandboxConflictError,
     SandboxNotFoundError,
     SandboxProvisioningError,
@@ -796,6 +797,27 @@ async def test_503_raises_sandbox_unavailable_error(api: SandboxAPI):
         await api.list_hosts()
 
 
+@respx.mock
+async def test_capacity_503_raises_sandbox_capacity_error(api: SandboxAPI):
+    """A 503 with error_code CAPACITY is a host-limit refusal, not an
+    outage. It stays a SandboxUnavailableError so existing retries keep
+    working, and carries the service's Retry-After in seconds."""
+
+    respx.post(f"{BASE_URL}/hosts").mock(
+        return_value=httpx.Response(
+            503,
+            json={"detail": "provider 'exe' is at its host limit", "error_code": "CAPACITY"},
+            headers={"Retry-After": "30"},
+        ),
+    )
+
+    with pytest.raises(SandboxCapacityError, match="host limit") as exc_info:
+        await api.create_host()
+
+    assert isinstance(exc_info.value, SandboxUnavailableError)
+    assert exc_info.value.retry_after == 30
+
+
 @respx.mock
 async def test_non_json_body_raises_sandbox_response_error(api: SandboxAPI):
     respx.get(f"{BASE_URL}/hosts").mock(