add refresh to ibmqjob.result (#469)

* add refresh to ibmqjob.result

* Update changelog.

* add param to docstring.

* update changelog

* remove unused import

* Add default value to docstring.

Author: Luis Garcia

CHANGELOG.md

@@ -14,6 +14,14 @@ The format is based on [Keep a Changelog].
 > - **Security**: in case of vulnerabilities.
 
 
+## [UNRELEASED]
+
+### Added
+
+- `IBMQJob.result()` now accepts an optional `refresh` parameter. If 
+  `refresh=True` is specified, the function re-queries the api for the 
+  results, rather than returning those cached. (\#469)
+
 ## [0.4.3] - 2019-11-21
 
 ### Fixed

qiskit/providers/ibmq/job/ibmqjob.py

@@ -186,7 +186,8 @@ def result(
             self,
             timeout: Optional[float] = None,
             wait: float = 5,
-            partial: bool = False
+            partial: bool = False,
+            refresh: bool = False
     ) -> Result:
         """Return the result of the job.
 
@@ -222,6 +223,8 @@ def result(
            timeout: number of seconds to wait for job
            wait: time between queries to IBM Q server
            partial: if true attempts to return partial results for the job.
+           refresh: if true, query the API for the result again.
+               Otherwise return the cached value. Default: False.
 
         Returns:
             Result object.
@@ -243,7 +246,7 @@ def result(
                 raise IBMQJobFailureError('Unable to retrieve job result. Job has failed. '
                                           'Use job.error_message() to get more details.')
 
-        return self._retrieve_result()
+        return self._retrieve_result(refresh=refresh)
 
     def cancel(self) -> bool:
         """Attempt to cancel a job.
@@ -349,7 +352,7 @@ def queue_position(self, refresh: bool = False) -> Optional[int]:
         """Return the position in the server queue.
 
         Args:
-            refresh (bool): if True, query the API and return the latest value.
+            refresh: if True, query the API and return the latest value.
                 Otherwise return the cached value.
 
         Returns:
@@ -483,9 +486,13 @@ def _wait_for_completion(
 
         return self._status in required_status
 
-    def _retrieve_result(self) -> Result:
+    def _retrieve_result(self, refresh: bool = False) -> Result:
         """Retrieve the job result response.
 
+        Args:
+            refresh: if true, query the API for the result again.
+               Otherwise return the cached value. Default: False.
+
         Returns:
             The job result.
 
@@ -496,7 +503,7 @@ def _retrieve_result(self) -> Result:
         """
         # pylint: disable=access-member-before-definition,attribute-defined-outside-init
         result_response = None
-        if not self._result:  # type: ignore[has-type]
+        if not self._result or refresh:  # type: ignore[has-type]
             try:
                 result_response = self._api.job_result(self.job_id(), self._use_object_storage)
                 self._result = Result.from_dict(result_response)

test/ibmq/test_ibmq_job.py

@@ -15,6 +15,7 @@
 """IBMQJob Test."""
 
 import time
+import copy
 from concurrent import futures
 from datetime import datetime, timedelta
 from unittest import SkipTest
@@ -484,6 +485,28 @@ def test_retrieve_from_retired_backend(self, provider):
         self.assertTrue(isinstance(new_job2.backend(), IBMQRetiredBackend))
         self.assertNotEqual(new_job2.backend().name(), 'unknown')
 
+    @requires_provider
+    def test_refresh_job_result(self, provider):
+        """Test re-retrieving job result via refresh."""
+        backend = provider.get_backend('ibmq_qasm_simulator')
+        qobj = assemble(transpile(self._qc, backend=backend), backend=backend)
+        job = backend.run(qobj)
+        result = job.result()
+
+        # Save original cached results.
+        cached_result = copy.deepcopy(result)
+        self.assertTrue(cached_result)
+
+        # Modify cached results.
+        result.results[0].header.name = 'modified_result'
+        self.assertNotEqual(cached_result, result)
+        self.assertEqual(result.results[0].header.name, 'modified_result')
+
+        # Re-retrieve result via refresh.
+        result = job.result(refresh=True)
+        self.assertEqual(cached_result, result)
+        self.assertNotEqual(result.results[0].header.name, 'modified_result')
+
 
 def _bell_circuit():
     qr = QuantumRegister(2, 'q')