docs: explain retry behavior for DONE jobs

plamut · plamut · commit e6e3c465f2f9 · 2021-02-22T15:53:08.000+01:00
diff --git a/google/cloud/bigquery/job/base.py b/google/cloud/bigquery/job/base.py
@@ -635,7 +635,9 @@ def result(self, retry=DEFAULT_RETRY, timeout=None):
         """Start the job and wait for it to complete and get the result.
 
         Args:
-            retry (Optional[google.api_core.retry.Retry]): How to retry the RPC.
+            retry (Optional[google.api_core.retry.Retry]):
+                How to retry the RPC. If the job state is ``DONE``, retrying is aborted
+                early, as the job will not change anymore.
             timeout (Optional[float]):
                 The number of seconds to wait for the underlying HTTP transport
                 before using ``retry``.
diff --git a/google/cloud/bigquery/job/query.py b/google/cloud/bigquery/job/query.py
@@ -979,7 +979,8 @@ def done(self, retry=DEFAULT_RETRY, timeout=None, reload=True):
 
         Args:
             retry (Optional[google.api_core.retry.Retry]):
-                How to retry the call that retrieves query results.
+                How to retry the call that retrieves query results. If the job state is
+                ``DONE``, retrying is aborted early, as the job will not change anymore.
             timeout (Optional[float]):
                 The number of seconds to wait for the underlying HTTP transport
                 before using ``retry``.
@@ -1128,7 +1129,9 @@ def result(
             max_results (Optional[int]):
                 The maximum total number of rows from this request.
             retry (Optional[google.api_core.retry.Retry]):
-                How to retry the call that retrieves rows.
+                How to retry the call that retrieves rows. If the job state is
+                ``DONE``, retrying is aborted early even if the results are not
+                availalbe, as this will not change anymore.
             timeout (Optional[float]):
                 The number of seconds to wait for the underlying HTTP transport
                 before using ``retry``.
