Enhance timeout error messages with actionable guidance

src/citrine/jobs/job.py

@@ -165,7 +165,12 @@ def _poll_for_job_completion(session: Session,
             logger.error(f'Job exceeded user timeout of {timeout} seconds. '
                          f'Note job on server is unaffected by this timeout.')
             logger.debug('Last status: {}'.format(status.dump()))
-            raise PollingTimeoutError('Job {} timed out.'.format(job_id))
+            raise PollingTimeoutError(
+                'Polling for job {} exceeded timeout of {} seconds. '
+                'The job may still be running on the server. '
+                'Increase the timeout parameter or check job '
+                'status manually.'.format(job_id, timeout)
+            )
     if status.status == JobStatus.FAILURE:
         logger.debug(f'Job terminated with Failure status: {status.dump()}')
         if raise_errors:

src/citrine/jobs/waiting.py

@@ -75,9 +75,12 @@ def is_finished():
         time.sleep(interval)
     if not is_finished():
         raise ConditionTimeoutError(
-            "Timeout of {timeout_length} seconds "
-            "reached, but task {uid} is still in progress".format(
-                timeout_length=timeout, uid=resource.uid)
+            "Timeout of {} seconds reached, but task {} "
+            "is still in progress. The server-side task "
+            "continues running independently of this client "
+            "timeout. Increase the 'timeout' parameter to "
+            "wait longer, or poll status manually.".format(
+                timeout, resource.uid)
         )
 
     current_resource = collection.get(resource.uid)

tests/jobs/test_waiting.py

@@ -89,5 +89,7 @@ def test_wait_for_asynchronous_object(sleep_mock, time_mock):
     with pytest.raises(ConditionTimeoutError) as exception:
         wait_for_asynchronous_object(collection=collection, resource=resource, timeout=1.0)
 
-    assert str(exception.value) == ("Timeout of 1.0 seconds reached, "
-        "but task 123456 is still in progress")
+    msg = str(exception.value)
+    assert "1.0 seconds" in msg
+    assert "123456" in msg
+    assert "still in progress" in msg