ENH Add job_id and run_id property attributes to CivisFuture (#290)

* ENH job_id and run_id as property attrs at CivisFuture

* TST CivisFuture job_id and run_id

* DOC explain why CivisFuture run_id can be None

* DOC demo job_id and run_id in CivisFuture docstring

* MAINT update change log

* TST ensure no change to ContainerFuture's job_id and run_id

* DOC job_id and run_id under Attributes of CivisFuture's docstring

* DOC clearer example for run_id in CivisFuture's docstring

* DOC add back example reminder in CivisFuture's docstring

Author: jacksonllee

CHANGELOG.md

@@ -3,6 +3,9 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
+### Added
+- `CivisFuture` has the `job_id` and `run_id` property attributes. (#290)
+
 ### Fixed
 - Polling will treat `None` responses generated by spotty internet connections
   like responses with a non-DONE state. (#289)

civis/futures.py

@@ -87,6 +87,14 @@ class CivisFuture(PollableResult):
         first time. If ``False``, it will wait the number of seconds specified
         in `polling_interval` from object creation before polling.
 
+    Attributes
+    ----------
+    job_id : int
+        First element of the tuple given to `poller_args`
+    run_id : int or None
+        Second element of the tuple given to `poller_args`
+        (`None` if the poller function does not require a run ID)
+
     Examples
     --------
     This example is provided as a function at :func:`~civis.io.query_civis`.
@@ -98,12 +106,15 @@ class CivisFuture(PollableResult):
     >>> preview_rows = 10
     >>> response = client.queries.post(database_id, sql, preview_rows,
     >>>                                credential=cred_id)
-    >>> job_id = response.id
     >>>
-    >>> poller = client.queries.get
-    >>> poller_args = (job_id, ) # (job_id, run_id) if poller requires run_id
+    >>> poller = client.queries.get_runs
+    >>> poller_args = response.id, response.last_run_id
     >>> polling_interval = 10
     >>> future = CivisFuture(poller, poller_args, polling_interval)
+    >>> future.job_id == response.id
+    True
+    >>> future.run_id == response.last_run_id
+    True
     """
     def __init__(self, poller, poller_args,
                  polling_interval=None, api_key=None, client=None,
@@ -136,6 +147,18 @@ def subscribed(self):
         return (hasattr(self, '_pubnub') and
                 len(self._pubnub.get_subscribed_channels()) > 0)
 
+    @property
+    def job_id(self):
+        return self.poller_args[0]
+
+    @property
+    def run_id(self):
+        try:
+            return self.poller_args[1]
+        except IndexError:
+            # when poller function has job_id only but not run_id
+            return None
+
     def cleanup(self):
         with self._condition:
             super().cleanup()
@@ -249,14 +272,6 @@ def __init__(self, job_id, run_id,
                          poll_on_creation=poll_on_creation)
         self._max_n_retries = max_n_retries
 
-    @property
-    def job_id(self):
-        return self.poller_args[0]
-
-    @property
-    def run_id(self):
-        return self.poller_args[1]
-
     def _set_api_exception(self, exc, result=None):
         # Catch attempts to set an exception. If there's retries
         # remaining, retry the run instead of erroring.

civis/tests/test_futures.py

@@ -16,7 +16,7 @@
 from civis.futures import (CivisFuture,
                            JobCompleteListener,
                            _LONG_POLLING_INTERVAL)
-from civis.tests import TEST_SPEC
+from civis.tests import TEST_SPEC, create_client_mock
 from pubnub.enums import PNStatusCategory
 
 from civis.tests.testcase import CivisVCRTestCase
@@ -280,6 +280,32 @@ def _check_executor(from_template_id=None):
     return c
 
 
+@pytest.mark.parametrize(
+    'poller_args,expected_job_id,expected_run_id',
+    [((123, 456), 123, 456),
+     ((123,), 123, None)]
+)
+def test_future_job_id_run_id(poller_args, expected_job_id, expected_run_id):
+    result = CivisFuture(
+        poller=lambda x: x,
+        poller_args=poller_args,
+        client=create_client_mock(),
+    )
+    assert result.job_id == expected_job_id
+    assert result.run_id == expected_run_id
+
+
+def test_container_future_job_id_run_id():
+    job_id, run_id = 123, 456
+    result = ContainerFuture(
+        job_id=job_id,
+        run_id=run_id,
+        client=create_client_mock(),
+    )
+    assert result.job_id == job_id
+    assert result.run_id == run_id
+
+
 def test_container_scripts():
     c = _check_executor()
     assert c.scripts.post_custom.call_count == 0