dazpy 2.7.2__tar.gz → 2.8.0__tar.gz

{dazpy-2.7.2/dazpy.egg-info → dazpy-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dazpy
-Version: 2.7.2
+Version: 2.8.0
 Summary: Python SDK for the DAZ Studio Script Server
 License: MIT
 Project-URL: Homepage, https://github.com/bluemoonfoundry/daz-script-server
@@ -15,7 +15,7 @@ Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
 
 # DazScript Server
 
-**Version 2.7.2** | DAZ Studio 4.5+ | DAZ Studio 6.25+ | Windows & macOS
+**Version 2.8.0** | DAZ Studio 4.5+ | DAZ Studio 6.25+ | Windows & macOS
 
 [![Docs](https://img.shields.io/badge/docs-dazpy%20SDK-blue)](https://bluemoonfoundry.github.io/daz-script-server/)
 [![HTTP API](https://img.shields.io/badge/docs-HTTP%20API%20reference-blue)](https://bluemoonfoundry.github.io/daz-script-server/api-reference/)
@@ -83,6 +83,7 @@ print(response.json())
 ### Getting Started
 - [Quick Start](#-quick-start)
 - [Why This Exists](#why-this-exists)
+- [What's New in v2.8.0](#whats-new-in-v280)
 - [What's New in v2.7.2](#whats-new-in-v272)
 - [What's New in v2.7.1](#whats-new-in-v271)
 - [What's New in v2.7.0](#whats-new-in-v270)
@@ -169,6 +170,50 @@ DAZ Studio is powerful for 3D content creation, but automation is limited to man
 
 ---
 
+## What's New in v2.8.0
+
+### 🚦 Fail Fast When DAZ Studio Is Busy — `503 STUDIO_BUSY`
+
+DAZ Studio's Qt main thread is single-threaded: if a user loads a scene,
+saves, clears the scene, or renders through the DAZ Studio UI while the
+server is also being driven remotely, requests that need the main thread
+used to block indefinitely with no signal to the caller. `/execute`,
+`/scripts/:id/execute`, the async-enqueue endpoints, and the render-submit
+endpoints now check DAZ Studio's busy state first and return `503` with
+`error_code: "STUDIO_BUSY"` (plus a `Retry-After` header) immediately
+instead of hanging.
+
+`dazpy` surfaces this as a new exception hierarchy — `DazBusyError`, with
+`StudioBusyError` (503) and `ConcurrencyLimitError` (429) subclasses, each
+carrying `reason` and `retry_after`. This also fixes a pre-existing bug
+where `429 CONCURRENT_LIMIT_EXCEEDED` responses were misreported as
+`ScriptRuntimeError`, as if the script itself had failed.
+
+```python
+from dazpy import DazClient
+from dazpy.exceptions import DazBusyError
+
+client = DazClient()
+try:
+    result = client.execute("1+1;")
+except DazBusyError as e:
+    print(f"DAZ Studio is busy: {e.reason} — retry after {e.retry_after}s")
+```
+
+Opt in to automatic retry with backoff instead of handling the exception
+yourself:
+
+```python
+result = client.execute("1+1;", retry_on_busy=True, max_wait=30.0)
+```
+
+`retry_on_busy`/`max_wait` are available on `execute`, `execute_file`,
+`execute_async_submit`, `render_submit`, `render_batch_submit`, and
+`render_animation_submit`. Retry is opt-in and off by default — callers
+(and any LLM driving them) stay informed rather than silently blocked.
+
+---
+
 ## What's New in v2.7.2
 
 No functional changes to `dazpy`'s behavior. `2.7.1`'s version bump missed
@@ -667,7 +712,7 @@ automation code without authoring DazScript by hand.
 Download the `.whl` file from the [latest release](https://github.com/bluemoonfoundry/daz-script-server/releases/latest) and install it:
 
 ```bash
-pip install dazpy-2.7.2-py3-none-any.whl
+pip install dazpy-2.8.0-py3-none-any.whl
 ```
 
 Or install directly from the repo for development:

dazpy-2.7.2/PKG-INFO → dazpy-2.8.0/README.md

@@ -1,21 +1,6 @@
-Metadata-Version: 2.4
-Name: dazpy
-Version: 2.7.2
-Summary: Python SDK for the DAZ Studio Script Server
-License: MIT
-Project-URL: Homepage, https://github.com/bluemoonfoundry/daz-script-server
-Project-URL: Repository, https://github.com/bluemoonfoundry/daz-script-server
-Project-URL: Bug Tracker, https://github.com/bluemoonfoundry/daz-script-server/issues
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.28
-Provides-Extra: docs
-Requires-Dist: sphinx>=7.0; extra == "docs"
-Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
-
 # DazScript Server
 
-**Version 2.7.2** | DAZ Studio 4.5+ | DAZ Studio 6.25+ | Windows & macOS
+**Version 2.8.0** | DAZ Studio 4.5+ | DAZ Studio 6.25+ | Windows & macOS
 
 [![Docs](https://img.shields.io/badge/docs-dazpy%20SDK-blue)](https://bluemoonfoundry.github.io/daz-script-server/)
 [![HTTP API](https://img.shields.io/badge/docs-HTTP%20API%20reference-blue)](https://bluemoonfoundry.github.io/daz-script-server/api-reference/)
@@ -83,6 +68,7 @@ print(response.json())
 ### Getting Started
 - [Quick Start](#-quick-start)
 - [Why This Exists](#why-this-exists)
+- [What's New in v2.8.0](#whats-new-in-v280)
 - [What's New in v2.7.2](#whats-new-in-v272)
 - [What's New in v2.7.1](#whats-new-in-v271)
 - [What's New in v2.7.0](#whats-new-in-v270)
@@ -169,6 +155,50 @@ DAZ Studio is powerful for 3D content creation, but automation is limited to man
 
 ---
 
+## What's New in v2.8.0
+
+### 🚦 Fail Fast When DAZ Studio Is Busy — `503 STUDIO_BUSY`
+
+DAZ Studio's Qt main thread is single-threaded: if a user loads a scene,
+saves, clears the scene, or renders through the DAZ Studio UI while the
+server is also being driven remotely, requests that need the main thread
+used to block indefinitely with no signal to the caller. `/execute`,
+`/scripts/:id/execute`, the async-enqueue endpoints, and the render-submit
+endpoints now check DAZ Studio's busy state first and return `503` with
+`error_code: "STUDIO_BUSY"` (plus a `Retry-After` header) immediately
+instead of hanging.
+
+`dazpy` surfaces this as a new exception hierarchy — `DazBusyError`, with
+`StudioBusyError` (503) and `ConcurrencyLimitError` (429) subclasses, each
+carrying `reason` and `retry_after`. This also fixes a pre-existing bug
+where `429 CONCURRENT_LIMIT_EXCEEDED` responses were misreported as
+`ScriptRuntimeError`, as if the script itself had failed.
+
+```python
+from dazpy import DazClient
+from dazpy.exceptions import DazBusyError
+
+client = DazClient()
+try:
+    result = client.execute("1+1;")
+except DazBusyError as e:
+    print(f"DAZ Studio is busy: {e.reason} — retry after {e.retry_after}s")
+```
+
+Opt in to automatic retry with backoff instead of handling the exception
+yourself:
+
+```python
+result = client.execute("1+1;", retry_on_busy=True, max_wait=30.0)
+```
+
+`retry_on_busy`/`max_wait` are available on `execute`, `execute_file`,
+`execute_async_submit`, `render_submit`, `render_batch_submit`, and
+`render_animation_submit`. Retry is opt-in and off by default — callers
+(and any LLM driving them) stay informed rather than silently blocked.
+
+---
+
 ## What's New in v2.7.2
 
 No functional changes to `dazpy`'s behavior. `2.7.1`'s version bump missed
@@ -667,7 +697,7 @@ automation code without authoring DazScript by hand.
 Download the `.whl` file from the [latest release](https://github.com/bluemoonfoundry/daz-script-server/releases/latest) and install it:
 
 ```bash
-pip install dazpy-2.7.2-py3-none-any.whl
+pip install dazpy-2.8.0-py3-none-any.whl
 ```
 
 Or install directly from the repo for development:

{dazpy-2.7.2 → dazpy-2.8.0}/dazpy/__init__.py

@@ -13,7 +13,7 @@ Typical usage::
     figure.find_bone("r_forearm").set_local_rotation(0, 0, 45)
 """
 
-__version__ = "2.7.2"
+__version__ = "2.8.0"
 
 from ._client import DazClient
 from ._scene import DazScene

{dazpy-2.7.2 → dazpy-2.8.0}/dazpy/_client.py

@@ -2,14 +2,18 @@ from __future__ import annotations
 
 import os
 import re
+import time
 
 import requests as _requests
 
 from .exceptions import (
     AuthenticationError,
+    ConcurrencyLimitError,
     ConnectionError,
+    DazBusyError,
     ScriptRuntimeError,
     ScriptSyntaxError,
+    StudioBusyError,
     TimeoutError,
 )
 from ._result import ExecutionResult
@@ -27,10 +31,37 @@ def _load_token() -> str:
     return ""
 
 
-def _map_response(resp: _requests.Response, script: str = "") -> ExecutionResult:
+def _parse_retry_after(resp: _requests.Response) -> float:
+    raw = resp.headers.get("Retry-After", "")
+    try:
+        return float(raw)
+    except (TypeError, ValueError):
+        return 2.0
+
+
+def _raise_for_error(resp: _requests.Response) -> None:
+    """Raise a typed exception for authentication or server-busy responses.
+
+    Leaves 2xx responses (and DazScript's own success:false runtime/syntax
+    errors, which use HTTP 200) for the caller to handle.
+    """
     status = resp.status_code
     if status == 401 or status == 403:
         raise AuthenticationError(f"HTTP {status}: {resp.text[:200]}")
+    if status < 400:
+        return
+    data = resp.json()
+    error_code = data.get("error_code", "")
+    error_msg = data.get("error") or f"HTTP {status}"
+    retry_after = _parse_retry_after(resp)
+    if error_code == "STUDIO_BUSY":
+        raise StudioBusyError(error_msg, reason=data.get("detail", error_msg), retry_after=retry_after)
+    if error_code == "CONCURRENT_LIMIT_EXCEEDED":
+        raise ConcurrencyLimitError(error_msg, reason=error_msg, retry_after=retry_after)
+
+
+def _map_response(resp: _requests.Response, script: str = "") -> ExecutionResult:
+    _raise_for_error(resp)
 
     data = resp.json()
     request_id = data.get("request_id", "")
@@ -118,13 +149,37 @@ class DazClient:
         except _requests.exceptions.Timeout as e:
             raise TimeoutError(f"Request timed out after {self._timeout}s") from e
 
-    def execute(self, script: str, args: object = None) -> ExecutionResult:
+    def _with_busy_retry(self, fn, retry_on_busy: bool, max_wait: float):
+        """Run *fn* (a zero-arg callable), retrying on DazBusyError while
+        *retry_on_busy* is true, up to *max_wait* seconds total."""
+        if not retry_on_busy:
+            return fn()
+        deadline = time.monotonic() + max_wait
+        backoff = 1.0
+        while True:
+            try:
+                return fn()
+            except DazBusyError:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise
+                time.sleep(min(backoff, remaining))
+                backoff = min(backoff + 1.0, 5.0)
+
+    def execute(
+        self, script: str, args: object = None, *, retry_on_busy: bool = False, max_wait: float = 30.0
+    ) -> ExecutionResult:
         """Execute a DazScript string synchronously.
 
         Args:
             script: DazScript source code to execute.
             args: Optional value passed into the script as ``getArguments()[0]``.
                 Must be JSON-serialisable.
+            retry_on_busy: If ``True``, transparently retry with backoff when
+                the server reports ``StudioBusyError``/``ConcurrencyLimitError``,
+                instead of raising immediately.
+            max_wait: Maximum total seconds to retry when *retry_on_busy* is
+                ``True``, before re-raising the busy error.
 
         Returns:
             The execution result containing the script return value and any
@@ -135,20 +190,36 @@ class DazClient:
             AuthenticationError: If the token is invalid or the IP is blocked.
             ScriptSyntaxError: If the script contains a parse error.
             ScriptRuntimeError: If the script raises a runtime exception.
+            StudioBusyError: If DAZ Studio's main thread is busy and
+                *retry_on_busy* is ``False`` or *max_wait* is exceeded.
+            ConcurrencyLimitError: If too many concurrent requests are in
+                flight and *retry_on_busy* is ``False`` or *max_wait* is
+                exceeded.
             TimeoutError: If the request exceeds *timeout* seconds.
         """
         payload: dict = {"script": script}
         if args is not None:
             payload["args"] = args
-        resp = self._post("/execute", payload)
-        return _map_response(resp, script=script)
 
-    def execute_file(self, script_file: str, args: object = None) -> ExecutionResult:
+        def _do():
+            resp = self._post("/execute", payload)
+            return _map_response(resp, script=script)
+
+        return self._with_busy_retry(_do, retry_on_busy, max_wait)
+
+    def execute_file(
+        self, script_file: str, args: object = None, *, retry_on_busy: bool = False, max_wait: float = 30.0
+    ) -> ExecutionResult:
         """Execute a ``.dsa`` script file that resides on the DAZ Studio host.
 
         Args:
             script_file: Absolute path to the ``.dsa`` file on the server host.
             args: Optional argument passed to the script.
+            retry_on_busy: If ``True``, transparently retry with backoff when
+                the server reports ``StudioBusyError``/``ConcurrencyLimitError``,
+                instead of raising immediately.
+            max_wait: Maximum total seconds to retry when *retry_on_busy* is
+                ``True``, before re-raising the busy error.
 
         Returns:
             The execution result.
@@ -158,20 +229,36 @@ class DazClient:
             AuthenticationError: On auth failure.
             ScriptSyntaxError: On parse error.
             ScriptRuntimeError: On runtime error.
+            StudioBusyError: If DAZ Studio's main thread is busy and
+                *retry_on_busy* is ``False`` or *max_wait* is exceeded.
+            ConcurrencyLimitError: If too many concurrent requests are in
+                flight and *retry_on_busy* is ``False`` or *max_wait* is
+                exceeded.
             TimeoutError: On HTTP timeout.
         """
         payload: dict = {"scriptFile": script_file}
         if args is not None:
             payload["args"] = args
-        resp = self._post("/execute", payload)
-        return _map_response(resp)
 
-    def execute_async_submit(self, script: str, args: object = None) -> str:
+        def _do():
+            resp = self._post("/execute", payload)
+            return _map_response(resp)
+
+        return self._with_busy_retry(_do, retry_on_busy, max_wait)
+
+    def execute_async_submit(
+        self, script: str, args: object = None, *, retry_on_busy: bool = False, max_wait: float = 30.0
+    ) -> str:
         """Submit a script for asynchronous execution and return immediately.
 
         Args:
             script: DazScript source code.
             args: Optional argument for the script.
+            retry_on_busy: If ``True``, transparently retry with backoff when
+                the server reports ``StudioBusyError``/``ConcurrencyLimitError``,
+                instead of raising immediately.
+            max_wait: Maximum total seconds to retry when *retry_on_busy* is
+                ``True``, before re-raising the busy error.
 
         Returns:
             The server-assigned ``request_id`` string.  Use it with
@@ -181,14 +268,22 @@ class DazClient:
         Raises:
             ConnectionError: If the server cannot be reached.
             AuthenticationError: On auth failure.
+            StudioBusyError: If DAZ Studio's main thread is busy and
+                *retry_on_busy* is ``False`` or *max_wait* is exceeded.
+            ConcurrencyLimitError: If too many concurrent requests are in
+                flight and *retry_on_busy* is ``False`` or *max_wait* is
+                exceeded.
         """
         payload: dict = {"script": script}
         if args is not None:
             payload["args"] = args
-        resp = self._post("/execute/async", payload)
-        if resp.status_code in (401, 403):
-            raise AuthenticationError(f"HTTP {resp.status_code}")
-        return resp.json().get("request_id", "")
+
+        def _do():
+            resp = self._post("/execute/async", payload)
+            _raise_for_error(resp)
+            return resp.json().get("request_id", "")
+
+        return self._with_busy_retry(_do, retry_on_busy, max_wait)
 
     def get_request_status(self, request_id: str) -> dict:
         """Return the current status of an async request.
@@ -282,6 +377,8 @@ class DazClient:
         engine: str = "",
         iray_samples: int = 0,
         reset_morphs: bool = False,
+        retry_on_busy: bool = False,
+        max_wait: float = 30.0,
     ) -> dict:
         """Submit a render job and return immediately.
 
@@ -296,6 +393,11 @@ class DazClient:
             engine: Render engine (``"iray"``, ``"filament"``).
             iray_samples: iRay sample count (0 = use scene default).
             reset_morphs: If ``True``, reset all morphs to defaults before applying.
+            retry_on_busy: If ``True``, transparently retry with backoff when
+                the server reports ``StudioBusyError``/``ConcurrencyLimitError``,
+                instead of raising immediately.
+            max_wait: Maximum total seconds to retry when *retry_on_busy* is
+                ``True``, before re-raising the busy error.
 
         Returns:
             A dict with ``request_id``, ``status`` (``"queued"``), and
@@ -304,6 +406,11 @@ class DazClient:
         Raises:
             ConnectionError: If the server cannot be reached.
             AuthenticationError: On HTTP 401/403.
+            StudioBusyError: If DAZ Studio's main thread is busy and
+                *retry_on_busy* is ``False`` or *max_wait* is exceeded.
+            ConcurrencyLimitError: If too many concurrent requests are in
+                flight and *retry_on_busy* is ``False`` or *max_wait* is
+                exceeded.
         """
         payload: dict = {"output_path": output_path}
         if width and height:
@@ -323,18 +430,28 @@ class DazClient:
             payload["figure"] = figure
             if morphs:
                 payload["morphs"] = morphs
-        resp = self._post("/render", payload)
-        if resp.status_code in (401, 403):
-            raise AuthenticationError(f"HTTP {resp.status_code}: {resp.text[:200]}")
-        return resp.json()
 
-    def render_batch_submit(self, variants: list, base: dict | None = None) -> dict:
+        def _do():
+            resp = self._post("/render", payload)
+            _raise_for_error(resp)
+            return resp.json()
+
+        return self._with_busy_retry(_do, retry_on_busy, max_wait)
+
+    def render_batch_submit(
+        self, variants: list, base: dict | None = None, *, retry_on_busy: bool = False, max_wait: float = 30.0
+    ) -> dict:
         """Submit a batch render job and return immediately.
 
         Args:
             variants: List of variant dicts, each with at least ``output_path``.
                 Supported keys mirror :meth:`render_submit` optional fields.
             base: Optional shared defaults applied to all variants.
+            retry_on_busy: If ``True``, transparently retry with backoff when
+                the server reports ``StudioBusyError``/``ConcurrencyLimitError``,
+                instead of raising immediately.
+            max_wait: Maximum total seconds to retry when *retry_on_busy* is
+                ``True``, before re-raising the busy error.
 
         Returns:
             A dict with ``batch_id``, ``request_ids`` (list), and ``total`` keys.
@@ -342,14 +459,22 @@ class DazClient:
         Raises:
             ConnectionError: If the server cannot be reached.
             AuthenticationError: On HTTP 401/403.
+            StudioBusyError: If DAZ Studio's main thread is busy and
+                *retry_on_busy* is ``False`` or *max_wait* is exceeded.
+            ConcurrencyLimitError: If too many concurrent requests are in
+                flight and *retry_on_busy* is ``False`` or *max_wait* is
+                exceeded.
         """
         payload: dict = {"variants": variants}
         if base:
             payload["base"] = base
-        resp = self._post("/render/batch", payload)
-        if resp.status_code in (401, 403):
-            raise AuthenticationError(f"HTTP {resp.status_code}: {resp.text[:200]}")
-        return resp.json()
+
+        def _do():
+            resp = self._post("/render/batch", payload)
+            _raise_for_error(resp)
+            return resp.json()
+
+        return self._with_busy_retry(_do, retry_on_busy, max_wait)
 
     def render_animation_submit(
         self,
@@ -362,6 +487,8 @@ class DazClient:
         height: int = 0,
         camera: str = "",
         engine: str = "",
+        retry_on_busy: bool = False,
+        max_wait: float = 30.0,
     ) -> dict:
         """Submit an animation render job spanning a frame range and return immediately.
 
@@ -381,6 +508,11 @@ class DazClient:
             height: Image height in pixels (must be paired with *width*).
             camera: Camera label to render from.
             engine: Render engine (``"iray"``, ``"filament"``).
+            retry_on_busy: If ``True``, transparently retry with backoff when
+                the server reports ``StudioBusyError``/``ConcurrencyLimitError``,
+                instead of raising immediately.
+            max_wait: Maximum total seconds to retry when *retry_on_busy* is
+                ``True``, before re-raising the busy error.
 
         Returns:
             A dict with ``request_id``, ``status`` (``"queued"``), and
@@ -389,6 +521,11 @@ class DazClient:
         Raises:
             ConnectionError: If the server cannot be reached.
             AuthenticationError: On HTTP 401/403.
+            StudioBusyError: If DAZ Studio's main thread is busy and
+                *retry_on_busy* is ``False`` or *max_wait* is exceeded.
+            ConcurrencyLimitError: If too many concurrent requests are in
+                flight and *retry_on_busy* is ``False`` or *max_wait* is
+                exceeded.
         """
         payload: dict = {
             "output_path": output_path,
@@ -403,10 +540,13 @@ class DazClient:
             payload["camera"] = camera
         if engine:
             payload["engine"] = engine
-        resp = self._post("/render/animation", payload)
-        if resp.status_code in (401, 403):
-            raise AuthenticationError(f"HTTP {resp.status_code}: {resp.text[:200]}")
-        return resp.json()
+
+        def _do():
+            resp = self._post("/render/animation", payload)
+            _raise_for_error(resp)
+            return resp.json()
+
+        return self._with_busy_retry(_do, retry_on_busy, max_wait)
 
     def cancel_render(self, request_id: str) -> bool:
         """Cancel a queued or running render job.

{dazpy-2.7.2 → dazpy-2.8.0}/dazpy/exceptions.py

@@ -10,6 +10,30 @@ class AuthenticationError(DazError):
     """Raised on HTTP 401 or 403 (bad or missing API token, or IP blocked)."""
 
 
+class DazBusyError(DazError):
+    """Base class for transient "DAZ Studio is busy, please retry" conditions.
+
+    Attributes:
+        reason: Human-readable explanation of why the server is busy.
+        retry_after: Server-suggested seconds to wait before retrying.
+    """
+
+    def __init__(self, message: str, reason: str = "", retry_after: float = 2.0):
+        super().__init__(message)
+        self.reason = reason
+        self.retry_after = retry_after
+
+
+class StudioBusyError(DazBusyError):
+    """Raised on HTTP 503 STUDIO_BUSY: DAZ Studio's main thread is occupied
+    with a scene load, save, clear, or render and cannot service the request."""
+
+
+class ConcurrencyLimitError(DazBusyError):
+    """Raised on HTTP 429 CONCURRENT_LIMIT_EXCEEDED: too many requests are
+    already in flight against the server."""
+
+
 class ScriptError(DazError):
     """Base class for errors that originate inside a DazScript execution.
 

dazpy-2.7.2/README.md → dazpy-2.8.0/dazpy.egg-info/PKG-INFO

@@ -1,6 +1,21 @@
+Metadata-Version: 2.4
+Name: dazpy
+Version: 2.8.0
+Summary: Python SDK for the DAZ Studio Script Server
+License: MIT
+Project-URL: Homepage, https://github.com/bluemoonfoundry/daz-script-server
+Project-URL: Repository, https://github.com/bluemoonfoundry/daz-script-server
+Project-URL: Bug Tracker, https://github.com/bluemoonfoundry/daz-script-server/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
+
 # DazScript Server
 
-**Version 2.7.2** | DAZ Studio 4.5+ | DAZ Studio 6.25+ | Windows & macOS
+**Version 2.8.0** | DAZ Studio 4.5+ | DAZ Studio 6.25+ | Windows & macOS
 
 [![Docs](https://img.shields.io/badge/docs-dazpy%20SDK-blue)](https://bluemoonfoundry.github.io/daz-script-server/)
 [![HTTP API](https://img.shields.io/badge/docs-HTTP%20API%20reference-blue)](https://bluemoonfoundry.github.io/daz-script-server/api-reference/)
@@ -68,6 +83,7 @@ print(response.json())
 ### Getting Started
 - [Quick Start](#-quick-start)
 - [Why This Exists](#why-this-exists)
+- [What's New in v2.8.0](#whats-new-in-v280)
 - [What's New in v2.7.2](#whats-new-in-v272)
 - [What's New in v2.7.1](#whats-new-in-v271)
 - [What's New in v2.7.0](#whats-new-in-v270)
@@ -154,6 +170,50 @@ DAZ Studio is powerful for 3D content creation, but automation is limited to man
 
 ---
 
+## What's New in v2.8.0
+
+### 🚦 Fail Fast When DAZ Studio Is Busy — `503 STUDIO_BUSY`
+
+DAZ Studio's Qt main thread is single-threaded: if a user loads a scene,
+saves, clears the scene, or renders through the DAZ Studio UI while the
+server is also being driven remotely, requests that need the main thread
+used to block indefinitely with no signal to the caller. `/execute`,
+`/scripts/:id/execute`, the async-enqueue endpoints, and the render-submit
+endpoints now check DAZ Studio's busy state first and return `503` with
+`error_code: "STUDIO_BUSY"` (plus a `Retry-After` header) immediately
+instead of hanging.
+
+`dazpy` surfaces this as a new exception hierarchy — `DazBusyError`, with
+`StudioBusyError` (503) and `ConcurrencyLimitError` (429) subclasses, each
+carrying `reason` and `retry_after`. This also fixes a pre-existing bug
+where `429 CONCURRENT_LIMIT_EXCEEDED` responses were misreported as
+`ScriptRuntimeError`, as if the script itself had failed.
+
+```python
+from dazpy import DazClient
+from dazpy.exceptions import DazBusyError
+
+client = DazClient()
+try:
+    result = client.execute("1+1;")
+except DazBusyError as e:
+    print(f"DAZ Studio is busy: {e.reason} — retry after {e.retry_after}s")
+```
+
+Opt in to automatic retry with backoff instead of handling the exception
+yourself:
+
+```python
+result = client.execute("1+1;", retry_on_busy=True, max_wait=30.0)
+```
+
+`retry_on_busy`/`max_wait` are available on `execute`, `execute_file`,
+`execute_async_submit`, `render_submit`, `render_batch_submit`, and
+`render_animation_submit`. Retry is opt-in and off by default — callers
+(and any LLM driving them) stay informed rather than silently blocked.
+
+---
+
 ## What's New in v2.7.2
 
 No functional changes to `dazpy`'s behavior. `2.7.1`'s version bump missed
@@ -652,7 +712,7 @@ automation code without authoring DazScript by hand.
 Download the `.whl` file from the [latest release](https://github.com/bluemoonfoundry/daz-script-server/releases/latest) and install it:
 
 ```bash
-pip install dazpy-2.7.2-py3-none-any.whl
+pip install dazpy-2.8.0-py3-none-any.whl
 ```
 
 Or install directly from the repo for development:

{dazpy-2.7.2 → dazpy-2.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dazpy"
-version = "2.7.2"
+version = "2.8.0"
 description = "Python SDK for the DAZ Studio Script Server"
 readme = "README.md"
 requires-python = ">=3.10"

{dazpy-2.7.2 → dazpy-2.8.0}/tests/test_dazpy.py

@@ -935,6 +935,109 @@ class TestErrorMapping(unittest.TestCase):
             with self.assertRaises(exceptions.ScriptSyntaxError):
                 client.execute("{bad syntax")
 
+    def test_studio_busy_error_503(self):
+        import requests as req
+        resp = MagicMock(spec=req.Response)
+        resp.status_code = 503
+        resp.json.return_value = {
+            "success": False,
+            "error_code": "STUDIO_BUSY",
+            "error": "DAZ Studio's main thread is busy; please retry shortly",
+            "detail": "DAZ Studio is currently loading a scene",
+        }
+        resp.headers = {"Retry-After": "2"}
+        resp.text = ""
+        client = DazClient.__new__(DazClient)
+        object.__setattr__(client, "_base", "http://127.0.0.1:18811")
+        object.__setattr__(client, "_token", "")
+        object.__setattr__(client, "_timeout", 30.0)
+        with patch("dazpy._client._requests.post", return_value=resp):
+            with self.assertRaises(exceptions.StudioBusyError) as ctx:
+                client.execute("1+1;")
+            self.assertIsInstance(ctx.exception, exceptions.DazBusyError)
+            self.assertEqual(ctx.exception.retry_after, 2.0)
+            self.assertIn("loading a scene", ctx.exception.reason)
+
+    def test_concurrency_limit_error_429(self):
+        import requests as req
+        resp = MagicMock(spec=req.Response)
+        resp.status_code = 429
+        resp.json.return_value = {
+            "success": False,
+            "error_code": "CONCURRENT_LIMIT_EXCEEDED",
+            "error": "Server busy: maximum concurrent requests reached, please retry",
+        }
+        resp.headers = {}
+        resp.text = ""
+        client = DazClient.__new__(DazClient)
+        object.__setattr__(client, "_base", "http://127.0.0.1:18811")
+        object.__setattr__(client, "_token", "")
+        object.__setattr__(client, "_timeout", 30.0)
+        with patch("dazpy._client._requests.post", return_value=resp):
+            with self.assertRaises(exceptions.ConcurrencyLimitError) as ctx:
+                client.execute("1+1;")
+            self.assertIsInstance(ctx.exception, exceptions.DazBusyError)
+            self.assertNotIsInstance(ctx.exception, exceptions.ScriptRuntimeError)
+            self.assertEqual(ctx.exception.retry_after, 2.0)
+
+    def _busy_resp(self):
+        import requests as req
+        resp = MagicMock(spec=req.Response)
+        resp.status_code = 503
+        resp.json.return_value = {
+            "success": False,
+            "error_code": "STUDIO_BUSY",
+            "error": "DAZ Studio's main thread is busy; please retry shortly",
+            "detail": "DAZ Studio is currently rendering",
+        }
+        resp.headers = {"Retry-After": "1"}
+        resp.text = ""
+        return resp
+
+    def _success_resp(self):
+        import requests as req
+        resp = MagicMock(spec=req.Response)
+        resp.status_code = 200
+        resp.json.return_value = {"success": True, "result": 2, "output": [], "request_id": "ok1"}
+        resp.headers = {}
+        resp.text = ""
+        return resp
+
+    def _busy_client(self):
+        client = DazClient.__new__(DazClient)
+        object.__setattr__(client, "_base", "http://127.0.0.1:18811")
+        object.__setattr__(client, "_token", "")
+        object.__setattr__(client, "_timeout", 30.0)
+        return client
+
+    def test_execute_without_retry_on_busy_raises_immediately(self):
+        client = self._busy_client()
+        with patch("dazpy._client._requests.post", return_value=self._busy_resp()) as post:
+            with self.assertRaises(exceptions.StudioBusyError):
+                client.execute("1+1;")
+            self.assertEqual(post.call_count, 1)
+
+    def test_execute_retry_on_busy_succeeds_after_retries(self):
+        client = self._busy_client()
+        responses = [self._busy_resp(), self._busy_resp(), self._success_resp()]
+        with patch("dazpy._client._requests.post", side_effect=responses) as post:
+            with patch("dazpy._client.time.sleep") as sleep:
+                result = client.execute("1+1;", retry_on_busy=True, max_wait=10.0)
+        self.assertEqual(result.value, 2)
+        self.assertEqual(post.call_count, 3)
+        self.assertEqual(sleep.call_count, 2)
+
+    def test_execute_retry_on_busy_gives_up_after_max_wait(self):
+        client = self._busy_client()
+        with patch("dazpy._client._requests.post", return_value=self._busy_resp()):
+            with patch("dazpy._client.time.sleep"):
+                with patch(
+                    "dazpy._client.time.monotonic",
+                    side_effect=[0.0, 0.0, 5.0, 11.0, 20.0, 20.0],
+                ):
+                    with self.assertRaises(exceptions.StudioBusyError):
+                        client.execute("1+1;", retry_on_busy=True, max_wait=10.0)
+
     def test_connection_error(self):
         import requests as req
         client = DazClient.__new__(DazClient)