From b58dc3fe70b6ab6e44827a0b6b3c5300f29faf1f Mon Sep 17 00:00:00 2001 From: Gregory Mulholland Date: Wed, 25 Mar 2026 13:30:58 -0700 Subject: [PATCH] Improve docstrings for jobs and waiting utilities - JobSubmissionResponse: explain what it is and how to use job_id for status polling - waiting.py: add module docstring explaining polling utilities - ConditionTimeoutError: explain that the server continues running independently and suggest increasing timeout Co-Authored-By: Claude Opus 4.6 (1M context) --- src/citrine/jobs/job.py | 12 ++++++++++-- src/citrine/jobs/waiting.py | 19 ++++++++++++++++++- 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/src/citrine/jobs/job.py b/src/citrine/jobs/job.py index 397a99971..bb6f71012 100644 --- a/src/citrine/jobs/job.py +++ b/src/citrine/jobs/job.py @@ -16,9 +16,17 @@ class JobSubmissionResponse(Resource['JobSubmissionResponse']): - """A response to a submit-job request for the job submission framework. + """Response from submitting an asynchronous job to the platform. + + Returned by operations that trigger server-side work (e.g., + ingestion, table building). Use the ``job_id`` to poll for + completion status. + + Attributes + ---------- + job_id : UUID + Unique identifier for tracking the submitted job. - This is returned as a successful response from the remote service. """ job_id = properties.UUID("job_id") diff --git a/src/citrine/jobs/waiting.py b/src/citrine/jobs/waiting.py index 62207947a..328d11f8d 100644 --- a/src/citrine/jobs/waiting.py +++ b/src/citrine/jobs/waiting.py @@ -1,3 +1,10 @@ +"""Utilities for waiting on asynchronous platform operations. + +These functions poll the platform at a configurable interval +until an asynchronous operation (predictor training, workflow +validation, design execution) completes or a timeout is reached. + +""" import time from pprint import pprint from typing import Union @@ -11,7 +18,17 @@ class ConditionTimeoutError(RuntimeError): - """Error that is raised when timeout is reached but the checked condition is still False.""" + """The client-side polling timeout was exceeded. + + Raised when an asynchronous operation (e.g. predictor + training, design execution) has not completed within the + specified ``timeout`` seconds. The server-side operation + continues running independently of this client timeout. + + Increase the ``timeout`` parameter to wait longer, or + poll the resource status manually. + + """ pass