Client

class dazpy.DazClient(host='127.0.0.1', port=18811, token=None, timeout=30.0)[source]

Bases: object

HTTP client for the DAZ Studio Script Server.

Handles authentication, request serialisation, and response mapping for all server endpoints. The token is loaded automatically from ~/.daz3d/dazscriptserver_token.txt when token is None.

Parameters:

  • host (str) – Hostname or IP address of the Script Server.

  • port (int) – Listening port of the Script Server.

  • token (str | None) – API token. Pass an empty string to disable authentication or None to auto-load from the default token file.

  • timeout (float) – Per-request HTTP timeout in seconds.

Requests are issued through a pooled requests.Session for connection reuse. Call close() when done, or use as a context manager:

client = DazClient()                          # default 127.0.0.1:18811
client = DazClient(token="my-secret-token")   # explicit token

with DazClient() as client:
    result = client.execute("1 + 1;")
close()[source]

Close the underlying requests.Session’s pooled connections.

execute(script, args=None, *, retry_on_busy=False, max_wait=30.0)[source]

Execute a DazScript string synchronously.

Parameters:

  • script (str) – DazScript source code to execute.

  • args (object) – Optional value passed into the script as getArguments()[0]. Must be JSON-serialisable.

  • retry_on_busy (bool) – If True, transparently retry with backoff when the server reports StudioBusyError/ConcurrencyLimitError, instead of raising immediately.

  • max_wait (float) – 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 console output.

Raises:
Return type:

ExecutionResult

execute_file(script_file, args=None, *, retry_on_busy=False, max_wait=30.0)[source]

Execute a .dsa script file that resides on the DAZ Studio host.

Parameters:

  • script_file (str) – Absolute path to the .dsa file on the server host.

  • args (object) – Optional argument passed to the script.

  • retry_on_busy (bool) – If True, transparently retry with backoff when the server reports StudioBusyError/ConcurrencyLimitError, instead of raising immediately.

  • max_wait (float) – Maximum total seconds to retry when retry_on_busy is True, before re-raising the busy error.

Returns:

The execution result.

Raises:
Return type:

ExecutionResult

execute_async_submit(script, args=None, *, report_file=None, retry_on_busy=False, max_wait=30.0)[source]

Submit a script for asynchronous execution and return immediately.

Parameters:

  • script (str) – DazScript source code.

  • args (object) – Optional argument for the script.

  • report_file (str | None) – Optional host-side JSONL file used by the script to report structured progress, logs, and output artefacts.

  • retry_on_busy (bool) – If True, transparently retry with backoff when the server reports StudioBusyError/ConcurrencyLimitError, instead of raising immediately.

  • max_wait (float) – 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 get_request_status() or get_request_result() to poll for the outcome.

Raises:
Return type:

str

execute_file_async_submit(script_file, args=None, *, report_file=None, retry_on_busy=False, max_wait=30.0)[source]

Submit a host-side .dsa file for asynchronous execution.

The file is loaded by DAZ Studio when the queued job starts, preserving its filename for getScriptFileName() and relative include() calls. Returns the server-assigned request id immediately; use the request status/result/cancel methods to manage its lifecycle.

execute_batch_async(operations, args=None, *, report_file=None)[source]

Submit multiple operations as one async request (one queue slot, one script).

Parameters:

  • operations (list[dict]) – List of {"body_lines": [...], "result_expression": "..."} dicts — same shape as add_operation()’s arguments.

  • args (object) – Optional argument passed to the combined script.

  • report_file (str | None) – Optional host-side JSONL file used for structured job observation, as in execute_async_submit().

Returns:

The server-assigned request_id. Poll it like any other async request; the result’s result field is a dict keyed "_r0", "_r1", … in submission order.

Return type:

str

get_request_status(request_id)[source]

Return the current status of an async request.

Parameters:

request_id (str) – The ID returned by execute_async_submit().

Returns:

A dict with at least "status" and "observation" keys. Observation contains structured progress, the bounded log tail, and the output manifest. Possible status values: "queued", "running", "completed", "failed", "cancelled", or "not_found".

Return type:

dict

get_request_result(request_id, wait=False, wait_timeout=30)[source]

Fetch the result of a completed async request.

Parameters:

  • request_id (str) – The ID returned by execute_async_submit().

  • wait (bool) – If True, the server will long-poll until the request completes or wait_timeout is reached.

  • wait_timeout (int) – Maximum number of seconds the server should wait before returning (only relevant when wait is True).

Returns:

A dict containing success, result, output, error, duration_ms, status, and observation keys.

Return type:

dict

list_requests(status=None)[source]

List all tracked async requests (script and render) with their status.

Parameters:

status (str | None) – Optional filter, one of "queued", "running", "completed", "failed", "cancelled". Omit to list requests in every status.

Returns:

A dict with a "requests" list (each item has request_id, status, progress, submitted_at) plus total and a per-status count for every status value.

Return type:

dict

cancel_request(request_id)[source]

Cancel a queued or running async request.

Parameters:

request_id (str) – The ID returned by execute_async_submit().

Returns:

True if the server confirmed cancellation, False otherwise.

Return type:

bool

render_submit(output_path, *, figure=None, morphs=None, figures=None, width=0, height=0, camera='', engine='', iray_samples=0, reset_morphs=False, retry_on_busy=False, max_wait=30.0)[source]

Submit a render job and return immediately.

Parameters:

  • output_path (str) – Absolute path on the DAZ Studio host to write the image.

  • figure (str | None) – Label of the figure to configure morphs on.

  • morphs (dict | None) – Morph values to apply {label: value}.

  • figures (list | None) – List of {"name": ..., "morphs": {...}} dicts for multi-figure scenes.

  • width (int) – Image width in pixels (must be paired with height).

  • height (int) – Image height in pixels (must be paired with width).

  • camera (str) – Camera label to render from.

  • engine (str) – Render engine ("iray", "viewport", "filament").

  • iray_samples (int) – iRay sample count (0 = use scene default).

  • reset_morphs (bool) – If True, reset all morphs to defaults before applying.

  • retry_on_busy (bool) – If True, transparently retry with backoff when the server reports StudioBusyError/ConcurrencyLimitError, instead of raising immediately.

  • max_wait (float) – 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 submitted_at keys.

Raises:
Return type:

dict

render_batch_submit(variants, base=None, *, retry_on_busy=False, max_wait=30.0)[source]

Submit a batch render job and return immediately.

Parameters:

  • variants (list) – List of variant dicts, each with at least output_path. Supported keys mirror render_submit() optional fields.

  • base (dict | None) – Optional shared defaults applied to all variants.

  • retry_on_busy (bool) – If True, transparently retry with backoff when the server reports StudioBusyError/ConcurrencyLimitError, instead of raising immediately.

  • max_wait (float) – 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.

Raises:
Return type:

dict

render_animation_submit(output_path, start_frame, end_frame, *, frame_padding=4, width=0, height=0, camera='', engine='', retry_on_busy=False, max_wait=30.0)[source]

Submit an animation render job spanning a frame range and return immediately.

Renders each frame in [start_frame, end_frame] to a separate file, as a single trackable async request (mirrors render_submit()’s request-tracking shape, not render_batch_submit()’s fan-out).

Parameters:

  • output_path (str) – Output path pattern containing the literal token "{frame}", e.g. r"C:\tmp\anim\frame_{frame}.png". The token is replaced with the frame number, zero-padded to frame_padding digits.

  • start_frame (int) – First frame to render (inclusive).

  • end_frame (int) – Last frame to render (inclusive).

  • frame_padding (int) – Zero-padding width for the frame number (default 4).

  • width (int) – Image width in pixels (must be paired with height).

  • height (int) – Image height in pixels (must be paired with width).

  • camera (str) – Camera label to render from.

  • engine (str) – Render engine ("iray", "viewport", "filament").

  • retry_on_busy (bool) – If True, transparently retry with backoff when the server reports StudioBusyError/ConcurrencyLimitError, instead of raising immediately.

  • max_wait (float) – 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 submitted_at keys.

Raises:
Return type:

dict

cancel_render(request_id)[source]

Cancel a queued or running render job.

Parameters:

request_id (str) – The request_id from render_submit() or a RenderResult with wait=False.

Returns:

True if the server confirmed cancellation, False otherwise (already finished, not found, or connection error).

Return type:

bool

stream_render_progress(request_id, stream_timeout=305.0)[source]

Open the SSE progress stream for a render request.

Returns a streaming requests.Response on success, or None if the endpoint is unavailable. Callers must close the response when done.

stream_scene_events(categories=None, stream_timeout=None)[source]

Open the SSE stream for general scene-change events (GET /scene/events).

Parameters:

  • categories (list[str] | None) – Optional subset of event categories to subscribe to ("node", "skeleton", "light", "camera", "selection", "scene", "time", "render"). None (default) subscribes to all categories.

  • stream_timeout (float | None) – Socket timeout in seconds. None (default) waits indefinitely — the server sends a keepalive comment every 15 seconds, so the connection never idles out.

Returns:

A streaming requests.Response on success, or None if the endpoint is unavailable. Callers must close the response when done (e.g. via a with statement).

Return type:

object | None

export_usd_submit(output_path, *, include_geometry=True, include_materials=True, include_skeleton=False, include_morphs=False, include_lights=False, include_camera=False)[source]

Submit a USD export job and return immediately.

Parameters:

  • output_path (str) – Absolute path on the DAZ Studio host where the .usda file should be written.

  • include_geometry (bool) – Export mesh geometry (default True).

  • include_materials (bool) – Export PBR material prims (default True).

  • include_skeleton (bool) – Export UsdSkel armature and skin weights.

  • include_morphs (bool) – Export active morphs as UsdSkelBlendShape prims.

  • include_lights (bool) – Export scene lights using UsdLux prims.

  • include_camera (bool) – Export the active render camera as UsdGeomCamera.

Returns:

A dict with job_id, status ("queued"), and submittedAt keys.

Raises:
Return type:

dict

get_usd_export_status(job_id)[source]

Poll the status of a USD export job.

Parameters:

job_id (str) – The ID returned by export_usd_submit().

Returns:

A dict with job_id, status, and (on completion) outputPath or error keys.

Raises:
Return type:

dict

status()[source]

Return the server status dict from GET /status.

Raises:

AuthenticationError – On HTTP 401/403.

health()[source]

Return the health check dict from GET /health.

Raises:

AuthenticationError – On HTTP 401/403.

metrics()[source]

Return the metrics dict from GET /metrics.

Raises:

AuthenticationError – On HTTP 401/403.