Switch to using reference/secondary for insar_isce_burst_job

CHANGELOG.md

@@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [PEP 440](https://www.python.org/dev/peps/pep-0440/) 
 and uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.1.1]
+
+### Changed
+* The `insar_isce_burst_job` so that it takes a `reference` and `secondary` scene as input, not `granule1` and `granule2`. Backward compatibility in `submit_insar_isce_burst_job` is maintained for now.
+
 ## [7.0.1]
 
 ### Removed

src/hyp3_sdk/hyp3.py

@@ -4,7 +4,7 @@
 from datetime import datetime, timezone
 from functools import singledispatchmethod
 from getpass import getpass
-from typing import List, Literal, Optional, Union
+from typing import Iterable, List, Literal, Optional, Union
 from urllib.parse import urljoin
 from warnings import warn
 
@@ -424,55 +424,89 @@ def prepare_insar_job(cls,
         return job_dict
 
     def submit_insar_isce_burst_job(self,
-                                    granule1: str,
-                                    granule2: str,
+                                    reference: Optional[Union[str, Iterable[str]]] = None,
+                                    secondary: Optional[Union[str, Iterable[str]]] = None,
                                     name: Optional[str] = None,
                                     apply_water_mask: bool = False,
-                                    looks: Literal['20x4', '10x2', '5x1'] = '20x4') -> Batch:
+                                    looks: Literal['20x4', '10x2', '5x1'] = '20x4',
+                                    *,
+                                    granule1: Optional[str] = None,
+                                    granule2: Optional[str] = None,
+                                    ) -> Batch:
         """Submit an InSAR ISCE burst job.
 
         Args:
-            granule1: The first granule (scene) to use
-            granule2: The second granule (scene) to use
+            reference: The reference granules (older scenes) to use
+            secondary: The secondary granules (younger scenes) to use
             name: A name for the job
             apply_water_mask: Sets pixels over coastal waters and large inland waterbodies
                 as invalid for phase unwrapping
             looks: Number of looks to take in range and azimuth
+            granule1: Deprecated argument superseded by reference.The reference granule (older scene) to use
+            granule2: Deprecated argument superseded by secondary. The reference granule (older scene) to use
 
         Returns:
             A Batch object containing the InSAR ISCE burst job
         """
         arguments = locals().copy()
         arguments.pop('self')
+
         job_dict = self.prepare_insar_isce_burst_job(**arguments)
         return self.submit_prepared_jobs(prepared_jobs=job_dict)
 
     @classmethod
     def prepare_insar_isce_burst_job(cls,
-                                     granule1: str,
-                                     granule2: str,
+                                     reference: Optional[Union[str, Iterable[str]]] = None,
+                                     secondary: Optional[Union[str, Iterable[str]]] = None,
                                      name: Optional[str] = None,
                                      apply_water_mask: bool = False,
-                                     looks: Literal['20x4', '10x2', '5x1'] = '20x4') -> dict:
+                                     looks: Literal['20x4', '10x2', '5x1'] = '20x4',
+                                     *,
+                                     granule1: Optional[str] = None,
+                                     granule2: Optional[str] = None,
+                                     ) -> dict:
         """Prepare an InSAR ISCE burst job.
 
         Args:
-            granule1: The first granule (scene) to use
-            granule2: The second granule (scene) to use
+        Args:
+            reference: The reference granules (older scenes) to use
+            secondary: The secondary granules (younger scenes) to use
             name: A name for the job
             apply_water_mask: Sets pixels over coastal waters and large inland waterbodies
                 as invalid for phase unwrapping
             looks: Number of looks to take in range and azimuth
+            granule1: Deprecated argument superseded by reference.The reference granule (older scene) to use
+            granule2: Deprecated argument superseded by secondary. The reference granule (older scene) to use
 
         Returns:
             A dictionary containing the prepared InSAR ISCE burst job
         """
-        job_parameters = locals().copy()
+        if reference is None:
+            if granule1:
+                warnings.warn("Keyword argument 'granule1' is deprecated. Use 'reference' instead.", DeprecationWarning)
+                reference = granule1
+            else:
+                raise ValueError('Either reference and secondary or granule1 and granule2 must be provided.')
+
+        if secondary is None:
+            if granule2:
+                warnings.warn("Keyword argument 'granule1' is deprecated. Use 'reference' instead.", DeprecationWarning)
+                secondary = granule2
+            else:
+                raise ValueError('Either reference and secondary or granule1 and granule2 must be provided.')
+
+        if isinstance(reference, str):
+            reference = [reference]
+
+        if isinstance(secondary, str):
+            secondary = [secondary]
+
+        arguments = locals().copy()
         for key in ['cls', 'granule1', 'granule2', 'name']:
-            job_parameters.pop(key)
+            arguments.pop(key)
 
         job_dict = {
-            'job_parameters': {'granules': [granule1, granule2], **job_parameters},
+            'job_parameters': {**arguments},
             'job_type': 'INSAR_ISCE_BURST',
         }
         if name is not None:

tests/test_hyp3.py

@@ -3,6 +3,7 @@
 from datetime import datetime, timedelta, timezone
 from urllib.parse import urljoin
 
+import pytest
 import responses
 
 import hyp3_sdk
@@ -281,25 +282,72 @@ def test_prepare_insar_job():
 
 
 def test_prepare_insar_isce_burst_job():
-    assert HyP3.prepare_insar_isce_burst_job(granule1='my_granule1', granule2='my_granule2') == {
+    assert HyP3.prepare_insar_isce_burst_job(reference='ref_granule1', secondary='sec_granule2') == {
         'job_type': 'INSAR_ISCE_BURST',
         'job_parameters': {
-            'granules': ['my_granule1', 'my_granule2'],
+            'reference': ['ref_granule1'],
+            'secondary': ['sec_granule2'],
             'apply_water_mask': False,
             'looks': '20x4',
-        }
+        },
+    }
+
+    assert HyP3.prepare_insar_isce_burst_job('ref_granule1', 'sec_granule2', 'job_name') == {
+        'job_type': 'INSAR_ISCE_BURST',
+        'name': 'job_name',
+        'job_parameters': {
+            'reference': ['ref_granule1'],
+            'secondary': ['sec_granule2'],
+            'apply_water_mask': False,
+            'looks': '20x4',
+        },
     }
-    assert HyP3.prepare_insar_isce_burst_job(granule1='my_granule1', granule2='my_granule2', name='my_name',
-                                             apply_water_mask=True, looks='10x2') == {
+
+    assert HyP3.prepare_insar_isce_burst_job(
+        reference=['ref_granule1', 'ref_granule2'],
+        secondary=['sec_granule1', 'sec_granule2'],
+        name='my_name',
+        apply_water_mask=True,
+        looks='10x2',
+    ) == {
         'job_type': 'INSAR_ISCE_BURST',
         'name': 'my_name',
         'job_parameters': {
-            'granules': ['my_granule1', 'my_granule2'],
+            'reference': ['ref_granule1', 'ref_granule2'],
+            'secondary': ['sec_granule1', 'sec_granule2'],
             'apply_water_mask': True,
             'looks': '10x2',
-        }
+        },
     }
 
+    assert HyP3.prepare_insar_isce_burst_job(
+        ['ref_granule1', 'ref_granule2'],
+        ['sec_granule1', 'sec_granule2'],
+        name='my_name',
+        apply_water_mask=True,
+        looks='10x2',
+    ) == {
+               'job_type': 'INSAR_ISCE_BURST',
+               'name': 'my_name',
+               'job_parameters': {
+                   'reference': ['ref_granule1', 'ref_granule2'],
+                   'secondary': ['sec_granule1', 'sec_granule2'],
+                   'apply_water_mask': True,
+                   'looks': '10x2',
+               },
+           }
+
+    with pytest.warns(DeprecationWarning):
+        assert HyP3.prepare_insar_isce_burst_job(granule1='ref_granule1', granule2='sec_granule2') == {
+            'job_type': 'INSAR_ISCE_BURST',
+            'job_parameters': {
+                'reference': ['ref_granule1'],
+                'secondary': ['sec_granule2'],
+                'apply_water_mask': False,
+                'looks': '20x4',
+            },
+        }
+
 
 def test_deprecated_warning():
     with warnings.catch_warnings(record=True) as w: