tpf.interact(): no longer return the useless bokeh show() result (alw…

…ays None) to make the API more intuitive.

src/lightkurve/interact.py

@@ -1000,7 +1000,7 @@ def show_interact_widget(
     vmax=None,
     scale="log",
     cmap="Viridis256",
-    return_selected_mask=False,
+    return_selection_mask=False,
 ):
     """Display an interactive Jupyter Notebook widget to inspect the pixel data.
 
@@ -1065,9 +1065,16 @@ def show_interact_widget(
         Maximum color scale for tpf figure
     cmap: str
         Colormap to use for tpf plot. Default is 'Viridis256'
-    return_selected_mask: bool
-        Optional, if set to `True`, also return the pixel selection as an aperture mask.
-    TODO: 1) document return result, 2) update for the docstring in tpf.interact(), 3) remind users to copy the result once satisfied.
+    return_selection_mask: bool
+        Optional, if set to `True`, return the pixel selection as an aperture mask.
+
+    Returns
+    -------
+    If ``return_selection_mask`` is set to ``True``, this method will return:
+    selection_mask: array-like
+    The mask representing the pixels the user has currently selected.
+    The user should copy the result after pixel selection is finalized, because the values
+    of the return array change dynamically as user changes the pixel selection.
     """
     try:
         import bokeh
@@ -1319,12 +1326,9 @@ def jump_to_lightcurve_position(attr, old, new):
         doc.add_root(widgets_and_figures)
 
     output_notebook(verbose=False, hide_banner=True)
-    show_result = show(create_interact_ui, notebook_url=notebook_url)
-    if return_selected_mask:
-        return show_result, selected_mask_to_return
-    else:
-        return show_result
-
+    show(create_interact_ui, notebook_url=notebook_url)
+    if return_selection_mask:
+        return selected_mask_to_return
 
 
 def show_skyview_widget(tpf, notebook_url=None, aperture_mask="empty",  magnitude_limit=18):

tests/test_interact.py

@@ -62,14 +62,13 @@ def test_graceful_exit_outside_notebook():
 
 
 @pytest.mark.skipif(bad_optional_imports, reason="requires bokeh")
-def test_return_selected_mask():
-    """Test to `return_selected_mask=True` can run without any syntax error."""
+def test_return_selection_mask():
+    """Test to `return_selection_mask=True` can run without any syntax error."""
     import bokeh
 
     tpf = TessTargetPixelFile(example_tpf)
     mask_to_use = tpf.create_threshold_mask()
-    result, selection_mask = tpf.interact(aperture_mask=mask_to_use, return_selected_mask=True)
-    assert result is None
+    selection_mask = tpf.interact(aperture_mask=mask_to_use, return_selection_mask=True)
     # the returned mask should be the same as the supplied one initially
     assert_array_equal(selection_mask, mask_to_use)