Repository: spacetelescope/jwst

Issue:
Print deprecation warning when neither .call nor .run is specified
_Issue [JP-3728](https://jira.stsci.edu/browse/JP-3728) was created on JIRA by [David Law](https://jira.stsci.edu/secure/ViewProfile.jspa?name=dlaw):_

Per discussion at <https://jira.stsci.edu/browse/JP-3490> and the Sep 4 JP meeting, we would like to add a warning notice to the pipeline log when users are directly using pipeline functions without specifying either .call() or .run().  This message would be to warn users that in a future build (TBD) usage without specifying which method to use will be deprecated.

Presumably this will apply only to usage within python environments, as command-line use via strun is understood to use the .call approach that incorporates parameter reference files.

Discussion:
codecov[bot]: ## [Codecov](https://app.codecov.io/gh/spacetelescope/jwst/pull/8761?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=spacetelescope) Report
Attention: Patch coverage is `83.33333%` with `1 line` in your changes missing coverage. Please review.
> Project coverage is 60.83%. Comparing base [(`8381a26`)](https://app.codecov.io/gh/spacetelescope/jwst/commit/8381a261d0b9a51d0ce2e7ac693032c76efac697?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=spacetelescope) to head [(`0c2a3bf`)](https://app.codecov.io/gh/spacetelescope/jwst/commit/0c2a3bf380e5ba362805f76b23d55800302b1471?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=spacetelescope).
> Report is 4 commits behind head on master.

| [Files with missing lines](https://app.codecov.io/gh/spacetelescope/jwst/pull/8761?dropdown=coverage&src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=spacetelescope) | Patch % | Lines |
|---|---|---|
| [jwst/stpipe/core.py](https://app.codecov.io/gh/spacetelescope/jwst/pull/8761?src=pr&el=tree&filepath=jwst%2Fstpipe%2Fcore.py&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=spacetelescope#diff-andzdC9zdHBpcGUvY29yZS5weQ==) | 83.33% | [1 Missing :warning: ](https://app.codecov.io/gh/spacetelescope/jwst/pull/8761?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=spacetelescope) |

<details><summary>Additional details and impacted files</summary>


```diff
@@            Coverage Diff             @@
##           master    #8761      +/-   ##
==========================================
+ Coverage   60.63%   60.83%   +0.20%     
==========================================
  Files         372      373       +1     
  Lines       38372    38642     +270     
==========================================
+ Hits        23267    23508     +241     
- Misses      15105    15134      +29     
```

</details>

[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/spacetelescope/jwst/pull/8761?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=spacetelescope).   
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=spacetelescope).

braingram: Thanks @melanieclarke and @tapastro for taking a look. I updated the changelog to use towncrier.

Patch:
diff --git a/changes/8761.stpipe.rst b/changes/8761.stpipe.rst
new file mode 100644
index 000000000..3d2985c04
--- /dev/null
+++ b/changes/8761.stpipe.rst
@@ -0,0 +1,1 @@
+Add warning that ``Step.__call__`` is deprecated.
diff --git a/jwst/stpipe/core.py b/jwst/stpipe/core.py
index 02ae5eb92..21efa00ef 100644
--- a/jwst/stpipe/core.py
+++ b/jwst/stpipe/core.py
@@ -3,6 +3,7 @@ JWST-specific Step and Pipeline base classes.
 """
 from functools import wraps
 import logging
+import warnings
 
 from stdatamodels.jwst.datamodels import JwstDataModel
 from stdatamodels.jwst import datamodels
@@ -102,6 +103,19 @@ class JwstStep(Step):
             log.info(f"Results used jwst version: {__version__}")
         return result
 
+    @wraps(Step.__call__)
+    def __call__(self, *args, **kwargs):
+        if not self.parent:
+            warnings.warn(
+                "Step.__call__ is deprecated. It is equivalent to Step.run "
+                "and is not recommended. See "
+                "https://jwst-pipeline.readthedocs.io/en/latest/jwst/"
+                "user_documentation/running_pipeline_python.html"
+                "#advanced-use-pipeline-run-vs-pipeline-call for more details.",
+                UserWarning
+            )
+        return super().__call__(*args, **kwargs)
+
 
 # JwstPipeline needs to inherit from Pipeline, but also
 # be a subclass of JwstStep so that it will pass checks


Test patch:
diff --git a/jwst/extract_2d/tests/test_grisms.py b/jwst/extract_2d/tests/test_grisms.py
index 0da23a2ca..1e50ace08 100644
--- a/jwst/extract_2d/tests/test_grisms.py
+++ b/jwst/extract_2d/tests/test_grisms.py
@@ -209,7 +209,7 @@ def test_create_box_fits():
     # Add fake data to pass a shape to wfss_imaging_wcs
     im.data = np.zeros((512, 512))
     aswcs = AssignWcsStep()
-    imwcs = aswcs(im)
+    imwcs = aswcs.run(im)
     imwcs.meta.source_catalog = source_catalog
     refs = get_reference_files(im)
     test_boxes = create_grism_bbox(imwcs, refs,
@@ -242,7 +242,7 @@ def test_create_box_gwcs():
     # The data array is not relevant
     im.data = np.zeros((512, 512))
     aswcs = AssignWcsStep()
-    imwcs = aswcs(im)
+    imwcs = aswcs.run(im)
     imwcs.meta.source_catalog = source_catalog
     refs = get_reference_files(im)
     test_boxes = create_grism_bbox(imwcs, refs,
@@ -268,7 +268,7 @@ def setup_image_cat():
     im.data = np.zeros((512, 512))
     im.meta.source_catalog = source_catalog
     aswcs = AssignWcsStep()
-    imwcs = aswcs(im)
+    imwcs = aswcs.run(im)
     refs = get_reference_files(im)
 
     return imwcs, refs
diff --git a/jwst/stpipe/tests/test_step.py b/jwst/stpipe/tests/test_step.py
index 735b474a9..8ca804ff2 100644
--- a/jwst/stpipe/tests/test_step.py
+++ b/jwst/stpipe/tests/test_step.py
@@ -623,3 +623,9 @@ def test_finalize_logging(monkeypatch):
     monkeypatch.setattr(logging.getLogger("jwst.stpipe.core"), "info", watcher)
     pipeline.run(model)
     assert watcher.seen
+
+
+def test_dunder_call_warning():
+    pipeline = EmptyPipeline()
+    with pytest.warns(UserWarning, match="Step.__call__ is deprecated"):
+        pipeline(None)
diff --git a/jwst/tweakreg/tests/test_tweakreg.py b/jwst/tweakreg/tests/test_tweakreg.py
index a038410e6..9dc21267c 100644
--- a/jwst/tweakreg/tests/test_tweakreg.py
+++ b/jwst/tweakreg/tests/test_tweakreg.py
@@ -193,7 +193,7 @@ def test_tweakreg_step(example_input, with_shift):
     step = tweakreg_step.TweakRegStep()
 
     # run the step on the example input modified above
-    result = step(example_input)
+    result = step.run(example_input)
 
     # check that step completed
     with result:
@@ -227,7 +227,7 @@ def test_src_confusion_pars(example_input, alignment_type):
         "abs_refcat": REFCAT,
     }
     step = tweakreg_step.TweakRegStep(**pars)
-    result = step(example_input)
+    result = step.run(example_input)
 
     # check that step was skipped
     with result:
@@ -356,7 +356,7 @@ def test_custom_catalog(custom_catalog_path, example_input, catfile, asn, meta,
     monkeypatch.setattr(twk, "construct_wcs_corrector", patched_construct_wcs_corrector)
 
     with pytest.raises(ValueError, match="done testing"):
-        step(str(asn_path))
+        step.run(str(asn_path))
 
 
 @pytest.mark.parametrize("with_shift", [True, False])
@@ -384,7 +384,7 @@ def test_sip_approx(example_input, with_shift):
     step.sip_npoints = 12
 
     # run the step on the example input modified above
-    result = step(example_input)
+    result = step.run(example_input)
 
     with result:
         r0 = result.borrow(0)