MAINT: standardize spatial query parameter name to 'coordinates'

CHANGES.rst

@@ -64,6 +64,10 @@ esa.euclid
    product_type parameters dynamically. [#3601]
 - In the method, ``get_scientific_product_list``, the ``dsr_part3`` parameter now supports the additional value
    ``latest``. [#3601]
+- The ``coordinate`` keyword of ``query_object``, ``cone_search``, and ``get_cutout`` is deprecated in
+  favor of ``coordinates`` for consistency with the rest of astroquery. [#3609]
+- ``query_object`` and ``cone_search`` now also accept multiple coordinates (a list, or a non-scalar
+  ``SkyCoord``); one query is run per position and the results are combined. [#3609]
 
 
 vizier
@@ -87,6 +91,85 @@ vo_conesearch
   PyVO Simple Cone Search interface instead. There is no direct replacement
   for server validation. [#3548]
 
+alma
+^^^^
+
+- The ``coordinate`` keyword of ``query_region`` and ``query_region_async`` is deprecated in favor of
+  ``coordinates`` for consistency with the rest of astroquery. [#3609]
+- ``query_region`` now also accepts multiple coordinates (a list, or a non-scalar ``SkyCoord``);
+  one query is run per position and the results are stacked into a single table with a
+  ``query_index`` column. [#3609]
+
+esa.hsa
+^^^^^^^
+
+- The ``coordinate`` keyword of ``query_observations`` and ``query_region`` is deprecated in favor of
+  ``coordinates`` for consistency with the rest of astroquery. [#3609]
+- ``query_observations`` and ``query_region`` now also accept multiple coordinates (a list, or a
+  non-scalar ``SkyCoord``); one query is run per position and the results are combined. [#3609]
+
+esa.jwst
+^^^^^^^^
+
+- The ``coordinate`` keyword of ``query_region`` and ``cone_search`` is deprecated in favor of
+  ``coordinates`` for consistency with the rest of astroquery. [#3609]
+- ``query_region`` and ``cone_search`` now also accept multiple coordinates (a list, or a non-scalar
+  ``SkyCoord``); one query is run per position and the results are combined. [#3609]
+
+esasky
+^^^^^^
+
+- The ``position`` keyword of ``query_region_maps``, ``query_region_catalogs``, and
+  ``query_region_spectra`` is deprecated in favor of ``coordinates`` for consistency with the rest of
+  astroquery. [#3609]
+- ``query_region_maps``, ``query_region_catalogs``, and ``query_region_spectra`` now also accept
+  multiple coordinates (a list, or a non-scalar ``SkyCoord``); one query is run per position and the
+  per-mission tables are stacked with a ``query_index`` column. [#3609]
+
+gaia
+^^^^
+
+- The ``coordinate`` keyword of ``query_object``, ``query_object_async``, ``cone_search``, and
+  ``cone_search_async`` is deprecated in favor of ``coordinates`` for consistency with the rest of
+  astroquery. [#3609]
+- ``query_object``, ``query_object_async``, ``cone_search``, and ``cone_search_async`` now also
+  accept multiple coordinates (a list, or a non-scalar ``SkyCoord``); one query is run per position
+  and the results are combined (stacked tables, or a list of jobs for the cone-search methods).
+  [#3609]
+
+heasarc
+^^^^^^^
+
+- The ``position`` keyword of ``query_region`` is deprecated in favor of ``coordinates`` for
+  consistency with the rest of astroquery. [#3609]
+- ``query_region`` now also accepts multiple coordinates (a list, or a non-scalar ``SkyCoord``);
+  one query is run per position and the results are stacked into a single table with a
+  ``query_index`` column. [#3609]
+
+ipac.irsa.ibe
+^^^^^^^^^^^^^
+
+- The ``coordinate`` keyword of ``query_region``, ``query_region_sia``, and ``query_region_async`` is
+  deprecated in favor of ``coordinates`` for consistency with the rest of astroquery. [#3609]
+- ``query_region`` and ``query_region_sia`` now also accept multiple coordinates (a list, or a
+  non-scalar ``SkyCoord``); one query is run per position and the results are stacked into a single
+  table with a ``query_index`` column. [#3609]
+
+noirlab
+^^^^^^^
+
+- The ``coordinate`` keyword of ``query_region`` is deprecated in favor of ``coordinates`` for
+  consistency with the rest of astroquery. [#3609]
+- ``query_region`` now also accepts multiple coordinates (a list, or a non-scalar ``SkyCoord``);
+  one query is run per position and the results are stacked into a single table with a
+  ``query_index`` column. [#3609]
+
+ogle
+^^^^
+
+- The ``coord`` keyword of ``query_region`` and ``query_region_async`` is deprecated in favor of
+  ``coordinates`` for consistency with the rest of astroquery. [#3609]
+
 Service fixes and enhancements
 ------------------------------
 
@@ -233,6 +316,13 @@ Infrastructure, Utility and Other Changes and Additions
 
 - Workaround upstream bug when caching a response using pyvo. [#3586]
 
+- New ``astroquery.utils.multicoord.support_multiple_coordinates`` decorator: single-position
+  query methods decorated with it accept a list of coordinates or a non-scalar ``SkyCoord`` and
+  loop over the positions with bounded, rate-limited parallelism. The defaults (3 parallel
+  requests, at least 0.3 s between submissions) are deliberately conservative — none of the
+  affected archives publish request-rate limits — and are configurable via
+  ``astroquery.utils.multicoord.conf``. [#3609]
+
 utils.tap
 ^^^^^^^^^
 

astroquery/alma/core.py

@@ -20,11 +20,13 @@
 from astropy import units as u
 from astropy.time import Time
 from astropy.coordinates import SkyCoord
+from astropy.utils.decorators import deprecated_renamed_argument
 
 from pyvo.dal.sia2 import SIA2_PARAMETERS_DESC, SIA2Service
 
 from ..exceptions import LoginError
 from ..utils import commons
+from ..utils.multicoord import support_multiple_coordinates
 from ..utils.process_asyncs import async_to_sync
 from ..query import BaseQuery, QueryWithLogin, BaseVOQuery
 from .tapsql import (_gen_pos_sql, _gen_str_sql, _gen_numeric_sql,
@@ -506,7 +508,8 @@ def query_object_async(self, object_name, *, public=True,
                                 payload=payload, enhanced_results=enhanced_results,
                                 **kwargs)
 
-    def query_region_async(self, coordinate, radius, *, public=True,
+    @deprecated_renamed_argument("coordinate", "coordinates", since="0.4.12")
+    def query_region_async(self, coordinates, radius, *, public=True,
                            science=True, payload=None, enhanced_results=False,
                            **kwargs):
         """
@@ -533,7 +536,7 @@ def query_region_async(self, coordinate, radius, *, public=True,
         rad = radius
         if not isinstance(radius, u.Quantity):
             rad = radius*u.deg
-        obj_coord = commons.parse_coordinates(coordinate).icrs
+        obj_coord = commons.parse_coordinates(coordinates).icrs
         ra_dec = '{}, {}'.format(obj_coord.to_string(), rad.to(u.deg).value)
         if payload is None:
             payload = {}
@@ -546,6 +549,61 @@ def query_region_async(self, coordinate, radius, *, public=True,
                                 payload=payload, enhanced_results=enhanced_results,
                                 **kwargs)
 
+    @deprecated_renamed_argument("coordinate", "coordinates", since="0.4.12")
+    @support_multiple_coordinates()
+    def query_region(self, coordinates, radius, *, public=True,
+                     science=True, payload=None, enhanced_results=False,
+                     verbose=False, **kwargs):
+        """
+        Query the ALMA archive with a source name and radius.
+
+        Multiple positions can be queried at once by passing a list of
+        coordinates (or coordinate strings) or a vector
+        `~astropy.coordinates.SkyCoord`: one query is run per position and
+        the results are stacked into a single table with a ``query_index``
+        column mapping each row back to the input position.
+
+        Parameters
+        ----------
+        coordinates : str / `astropy.coordinates`
+            the identifier or coordinates around which to query.  A list of
+            coordinates or a vector `~astropy.coordinates.SkyCoord` triggers
+            one query per position.
+        radius : str / `~astropy.units.Quantity`, optional
+            the radius of the region
+        public : bool
+            True to return only public datasets, False to return private only,
+            None to return both
+        science : bool
+            True to return only science datasets, False to return only
+            calibration, None to return both
+        payload : dict
+            Dictionary of additional keywords.  See `help`.
+        enhanced_results : bool
+            True to return a table with quantities instead of just values. It
+            also returns the footprints as `regions` objects.
+        verbose : bool
+            Whether to show warnings when parsing the result.
+
+        Returns
+        -------
+        table : A `~astropy.table.Table` object.
+        """
+        if payload is not None:
+            # do not mutate the caller's dict; query_region_async appends the
+            # position to payload['ra_dec'] in place, which would otherwise
+            # accumulate positions across the calls of a multi-coordinate query
+            payload = dict(payload)
+        response = self.query_region_async(coordinates, radius, public=public,
+                                           science=science, payload=payload,
+                                           enhanced_results=enhanced_results,
+                                           **kwargs)
+        if kwargs.get('get_query_payload'):
+            return response
+        result = self._parse_result(response, verbose=verbose)
+        self.table = result
+        return result
+
     def query_async(self, payload, *, public=True, science=True,
                     legacy_columns=False, get_query_payload=False,
                     maxrec=None, enhanced_results=False, **kwargs):

astroquery/alma/tests/test_alma.py

@@ -12,6 +12,7 @@
 from astropy.io import votable
 from astropy.coordinates import SkyCoord
 from astropy.time import Time
+from astropy.utils.exceptions import AstropyDeprecationWarning
 import pyvo
 
 from astroquery.alma import Alma
@@ -364,6 +365,32 @@ def test_query():
         language='ADQL', maxrec=None, uploads=None)
 
 
+def test_query_region_coordinate_deprecated():
+    # the old ``coordinate`` keyword should still work but emit a
+    # deprecation warning (renamed to ``coordinates``, issue #2803)
+    alma = Alma()
+    alma._get_dataarchive_url = Mock()
+    new_payload = alma.query_region(coordinates='1 2', radius=1*u.deg,
+                                    get_query_payload=True)
+    with pytest.warns(AstropyDeprecationWarning):
+        old_payload = alma.query_region(coordinate='1 2', radius=1*u.deg,
+                                        get_query_payload=True)
+    assert old_payload == new_payload
+
+
+def test_query_region_multiple_coordinates():
+    # a list of coordinates runs one query per position; with
+    # ``get_query_payload`` a list of per-position payloads is returned
+    alma = Alma()
+    alma._get_dataarchive_url = Mock()
+    payloads = alma.query_region(['1 2', '3 4'], radius=1*u.deg,
+                                 get_query_payload=True)
+    assert isinstance(payloads, list)
+    assert len(payloads) == 2
+    assert "CIRCLE('ICRS',1.0,2.0,1.0)" in payloads[0]
+    assert "CIRCLE('ICRS',3.0,4.0,1.0)" in payloads[1]
+
+
 @pytest.mark.filterwarnings("ignore::astropy.utils.exceptions.AstropyUserWarning")
 def test_enhanced_table():
     pytest.importorskip('regions')

astroquery/alma/tests/test_alma_remote.py

@@ -337,7 +337,7 @@ def test_query(self, tmp_path, alma):
     def test_misc(self, alma):
         # miscellaneous set of common tests
         #
-        # alma.query_region(coordinate=orionkl_coords, radius=4 * u.arcmin,
+        # alma.query_region(coordinates=orionkl_coords, radius=4 * u.arcmin,
         #                  public=False, science=False)
 
         result = alma.query_object('M83', public=True, science=True)

astroquery/esa/euclid/core.py

@@ -29,6 +29,7 @@
 from astroquery.utils import commons
 from astroquery.utils.tap import TapPlus
 from astroquery.utils.tap import taputils
+from ...utils.multicoord import support_multiple_coordinates
 from . import conf
 
 
@@ -384,15 +385,20 @@ def launch_job_async(self, query, *, name=None, dump_to_file=False, output_file=
         except Exception as exx:
             log.error(f'Query failed: {query}, {str(exx)}')
 
-    def query_object(self, coordinate, *, radius=None, width=None, height=None,
+    @deprecated_renamed_argument("coordinate", "coordinates", since="0.4.12")
+    @support_multiple_coordinates()
+    def query_object(self, coordinates, *, radius=None, width=None, height=None,
                      async_job=False, verbose=False, columns=None):
         """
         Searches for objects around a given position with the default catalog sascat_pvpr01.mer_final_cat_pvpr01
 
         Parameters
         ----------
-        coordinate : astropy.coordinate, mandatory
-            coordinates center point
+        coordinates : astropy.coordinate, mandatory
+            coordinates center point. A list of coordinates or a non-scalar
+            `~astropy.coordinates.SkyCoord` runs one query per position and
+            the resulting tables are stacked, with a ``query_index`` column
+            mapping each row back to the input position.
         radius : astropy.units, required if no 'width' nor 'height' are provided
             radius (deg)
         width : astropy.units, required if no 'radius' is provided
@@ -411,7 +417,7 @@ def query_object(self, coordinate, *, radius=None, width=None, height=None,
         -------
         The job results (astropy.table)
         """
-        coord = commons.parse_coordinates(coordinate)
+        coord = commons.parse_coordinates(coordinates)
 
         if radius is not None:
             job = self.__cone_search(coord, radius, async_job=async_job, verbose=verbose, columns=columns)
@@ -437,14 +443,14 @@ def query_object(self, coordinate, *, radius=None, width=None, height=None,
                 job = super().launch_job(query, verbose=verbose, format_with_results_compressed=('votable_gzip',))
         return job.get_results()
 
-    def __cone_search(self, coordinate, radius, *, table_name=None, ra_column_name=None, dec_column_name=None,
+    def __cone_search(self, coordinates, radius, *, table_name=None, ra_column_name=None, dec_column_name=None,
                       async_job=False, verbose=False, columns=None):
         """Cone search sorted by distance
         TAP & TAP+
 
         Parameters
         ----------
-        coordinate : astropy.coordinate, mandatory
+        coordinates : astropy.coordinate, mandatory
             coordinates center point
         radius : astropy.units, mandatory
             radius
@@ -478,7 +484,7 @@ def __cone_search(self, coordinate, radius, *, table_name=None, ra_column_name=N
             raise ValueError(f"Invalid ra or dec column names: ra, {ra_column_name}, dec, {dec_column_name}")
 
         radius_deg = None
-        coord = commons.parse_coordinates(coordinate)
+        coord = commons.parse_coordinates(coordinates)
         ra_hours, dec = commons.coord_to_radec(coord)
         ra = ra_hours * 15.0  # Converts to degrees
         if radius is not None:
@@ -519,7 +525,9 @@ def __cone_search(self, coordinate, radius, *, table_name=None, ra_column_name=N
 
         return job
 
-    def cone_search(self, coordinate, radius, *,
+    @deprecated_renamed_argument("coordinate", "coordinates", since="0.4.12")
+    @support_multiple_coordinates()
+    def cone_search(self, coordinates, radius, *,
                     table_name=None,
                     ra_column_name=None,
                     dec_column_name=None,
@@ -535,8 +543,11 @@ def cone_search(self, coordinate, radius, *,
 
         Parameters
         ----------
-        coordinate : astropy.coordinate, mandatory
-            coordinates center point
+        coordinates : astropy.coordinate, mandatory
+            coordinates center point. A list of coordinates or a non-scalar
+            `~astropy.coordinates.SkyCoord` runs one query per position; since
+            this method returns a job object, a list of jobs (one per position,
+            in input order) is returned when multiple positions are given.
         radius : astropy.units, mandatory
             radius
         table_name : str, optional, default the table defined for the selected environment
@@ -570,7 +581,7 @@ def cone_search(self, coordinate, radius, *,
         """
 
         radius_deg = None
-        coord = commons.parse_coordinates(coordinate)
+        coord = commons.parse_coordinates(coordinates)
         ra_hours, dec = commons.coord_to_radec(coord)
         ra = ra_hours * 15.0  # Converts to degrees
         if radius is not None:
@@ -1453,9 +1464,9 @@ def __is_multiple(self, value):
 
         return not isinstance(value, int) and ((isinstance(value, (list, tuple)) and len(value) > 1) or ',' in value)
 
-    @deprecated_renamed_argument(('instrument', 'id'), (None, None), since='0.4.12')
-    def get_cutout(self, *, file_path=None, coordinate, radius, output_file=None, verbose=False, instrument=None,
-                   id=None):
+    @deprecated_renamed_argument(('coordinate', 'instrument', 'id'), ('coordinates', None, None), since='0.4.12')
+    def get_cutout(self, *, file_path=None, coordinates=None, radius=None, output_file=None, verbose=False,
+                   instrument=None, id=None):
         """
         Downloads a cutout from a MER mosaic (background-subtracted image) for a given
         fits file path, centered on a coordinate and with a specified radius.
@@ -1466,7 +1477,7 @@ def get_cutout(self, *, file_path=None, coordinate, radius, output_file=None, ve
         ----------
         file_path : str, mandatory, default None
             file path for the product on the server (MER mosaic)
-        coordinate : astropy.coordinate or Simbad/VizieR/NED name (str), mandatory
+        coordinates : astropy.coordinate or Simbad/VizieR/NED name (str), mandatory
             coordinates center point
         radius : astropy.units, mandatory
             the radius of the cutout to generate
@@ -1480,14 +1491,14 @@ def get_cutout(self, *, file_path=None, coordinate, radius, output_file=None, ve
         The fits file is downloaded, and the local path where the cutout is saved is returned
         """
 
-        if file_path is None or coordinate is None or radius is None:
+        if file_path is None or coordinates is None or radius is None:
             raise ValueError(self.__ERROR_MSG_REQUESTED_GENERIC)
 
         # Parse POS
         radius_deg = Angle(self.__get_quantity_input(radius, "radius")).to_value(u.deg)
         if radius_deg > 0.5:
             raise ValueError(self.__ERROR_MSG_REQUESTED_RADIUS)
-        coord = commons.parse_coordinates(coordinate)
+        coord = commons.parse_coordinates(coordinates)
         ra_hours, dec = commons.coord_to_radec(coord)
         ra = ra_hours * 15.0  # Converts to degrees
         pos = """CIRCLE,{ra},{dec},{radius}""".format(**{'ra': ra, 'dec': dec, 'radius': radius_deg})