Docs fixes, guards around regions import

Co-authored-by: Copilot <copilot@github.com>

More doc fixes

Co-authored-by: Copilot <copilot@github.com>

Typos

Co-authored-by: Copilot <copilot@github.com>

Author: snbianco

astroquery/mast/__init__.py

@@ -20,9 +20,6 @@ class Conf(_config.ConfigNamespace):
     ssoserver = _config.ConfigItem(
         'https://ssoportal.stsci.edu',
         'MAST SSO Portal server.')
-    catalogs_server = _config.ConfigItem(
-        'https://catalogs.mast.stsci.edu',
-        'Catalogs.MAST server.')
     timeout = _config.ConfigItem(
         600,
         'Time limit for requests from the STScI server.')
@@ -38,6 +35,7 @@ class Conf(_config.ConfigNamespace):
 conf = Conf()
 
 from . import utils
+from .catalog_collection import CatalogCollection
 from .collections import Catalogs, CatalogsClass
 from .cutouts import Hapcut, HapcutClass, Tesscut, TesscutClass, Zcut, ZcutClass
 from .missions import MastMissions, MastMissionsClass
@@ -48,6 +46,7 @@ class Conf(_config.ConfigNamespace):
     "ObservationsClass",
     "Catalogs",
     "CatalogsClass",
+    "CatalogCollection",
     "MastMissions",
     "MastMissionsClass",
     "Mast",

astroquery/mast/catalog_collection.py

@@ -208,7 +208,7 @@ def supported_adql_functions(self):
 
     def get_catalog_metadata(self, catalog):
         """
-        For a given catalog, cache and return metadata about its columns and capabilties.
+        For a given catalog, cache and return metadata about its columns and capabilities.
 
         Parameters
         ----------
@@ -310,8 +310,8 @@ def _fetch_catalogs(self):
 
         Returns
         -------
-        list of str
-            List of catalog names.
+        `~astropy.table.Table`
+            A table containing the catalog names and descriptions for this collection.
         """
         log.debug(f"Fetching available tables for collection '{self.name}' from MAST TAP service.")
         query = "SELECT TOP 5000 table_name, description FROM tap_schema.tables"
@@ -334,8 +334,9 @@ def _fetch_adql_supported_functions(self):
 
         Returns
         -------
-        list
-            A list of supported ADQL functions.
+        set
+            A set of supported ADQL geometry functions (e.g. "POINT", "CIRCLE", "CONTAINS", etc.) for
+            this collection's TAP service.
         """
         adql_functions = ["CIRCLE", "POLYGON", "POINT", "CONTAINS", "INTERSECTS"]
         supported = set()

astroquery/mast/collections.py

@@ -19,7 +19,6 @@
 from astropy.table import Row, Table
 from astropy.time import Time
 from astropy.utils.decorators import deprecated, deprecated_renamed_argument
-from regions import CircleSkyRegion, PolygonSkyRegion
 
 from .. import log
 from ..exceptions import InputWarning, InvalidQueryError, NoResultsWarning
@@ -29,6 +28,12 @@
 from .catalog_collection import CatalogCollection
 from .core import MastQueryWithLogin
 
+try:
+    from regions import CircleSkyRegion, PolygonSkyRegion
+    HAS_REGIONS = True
+except ImportError:
+    HAS_REGIONS = False
+
 __all__ = ["Catalogs", "CatalogsClass"]
 
 
@@ -232,7 +237,7 @@ def query_criteria(
     ):
         """
         Query a MAST catalog from a given collection using criteria filters. To return columns for a given
-        collection and catalog, use `~astroquery.mast.collections.get_catalog_metadata`.
+        collection and catalog, use `~astroquery.mast.CatalogsClass.get_column_metadata`.
 
         Parameters
         ----------
@@ -243,10 +248,10 @@ def query_criteria(
         coordinates : str or `~astropy.coordinates` object, optional
             The target around which to search. It may be specified as a string (e.g., '350 -80') or as an
             Astropy coordinates object.
-        region : str | iterable | `~astropy.regions.CircleSkyRegion` | `~astropy.regions.PolygonSkyRegion`, optional
+        region : str | iterable | `~regions.CircleSkyRegion` | `~regions.PolygonSkyRegion`, optional
             The region to search within. It may be specified as a STC-S POLYGON or CIRCLE string
             (e.g., 'CIRCLE 350 -80 0.2'), an iterable of coordinate pairs, or as an
-            `~astropy.regions.CircleSkyRegion` or `~astropy.regions.PolygonSkyRegion`.
+            `~regions.CircleSkyRegion` or `~regions.PolygonSkyRegion`.
         object_name : str, optional
             The name of the object to resolve and search around.
         radius : str or `~astropy.units.Quantity` object, optional
@@ -264,17 +269,17 @@ def query_criteria(
         sort_by : str or list of str, optional
             Column name(s) to sort the results by.
         sort_desc : bool or list of bool, optional
-            Indicates whether to sort in descending order for each column in `sort_by`. If a single bool,
-            applies to all columns. If a list, must match length of `sort_by`. Default is False (ascending order).
+            Indicates whether to sort in descending order for each column in ``sort_by``. If a single bool,
+            applies to all columns. If a list, must match length of ``sort_by``. Default is False (ascending order).
         filters : dict, optional
             Another parameter to specify criteria filters as a dictionary. Use this option when the name of a column
             conflicts with a named parameter of this method.
         version : str, optional
-            Deprecated. The version argument is no longer used. Please use `collection` and `catalog` instead.
+            Deprecated. The version argument is no longer used. Please use ``collection`` and ``catalog`` instead.
         pagesize : int, optional
-            Deprecated. The pagesize argument is no longer used. Please use `limit` instead.
+            Deprecated. The pagesize argument is no longer used. Please use ``limit`` instead.
         page : int, optional
-            Deprecated. The page argument is no longer used. Please use `offset` instead.
+            Deprecated. The page argument is no longer used. Please use ``offset`` instead.
         **criteria
             Keyword arguments representing criteria filters to apply.
 
@@ -464,7 +469,7 @@ def query_region(
     ):
         """
         Query for MAST catalog entries within a specified region using criteria filters. To return columns for a given
-        collection and catalog, use `~astroquery.mast.collections.get_catalog_metadata`.
+        collection and catalog, use `~astroquery.mast.CatalogsClass.get_column_metadata`.
 
         Parameters
         ----------
@@ -473,10 +478,10 @@ def query_region(
             Astropy coordinates object.
         radius : str or `~astropy.units.Quantity` object, optional
             The search radius around the target coordinates or object. Default 0.2 degrees.
-        region : str | iterable | `~astropy.regions.CircleSkyRegion` | `~astropy.regions.PolygonSkyRegion`, optional
+        region : str | iterable | `~regions.CircleSkyRegion` | `~regions.PolygonSkyRegion`, optional
             The region to search within. It may be specified as a STC-S POLYGON or CIRCLE string
             (e.g., 'CIRCLE 350 -80 0.2'), an iterable of coordinate pairs, or as an
-            `~astropy.regions.CircleSkyRegion` or `~astropy.regions.PolygonSkyRegion`.
+            `~regions.CircleSkyRegion` or `~regions.PolygonSkyRegion`.
         collection : str, optional
             The collection to be queried. If None, uses the instance's `collection` attribute.
         catalog : str, optional
@@ -492,17 +497,17 @@ def query_region(
         sort_by : str or list of str, optional
             Column name(s) to sort the results by.
         sort_desc : bool or list of bool, optional
-            Indicates whether to sort in descending order for each column in `sort_by`. If a single bool,
-            applies to all columns. If a list, must match length of `sort_by`. Default is False (ascending order).
+            Indicates whether to sort in descending order for each column in ``sort_by``. If a single bool,
+            applies to all columns. If a list, must match length of ``sort_by``. Default is False (ascending order).
         filters : dict, optional
             Another parameter to specify criteria filters as a dictionary. Use this option when the name of a column
             conflicts with a named parameter of this method.
         version : str, optional
-            Deprecated. The version argument is no longer used. Please use `collection` and `catalog` instead.
+            Deprecated. The version argument is no longer used. Please use ``collection`` and ``catalog`` instead.
         pagesize : int, optional
-            Deprecated. The pagesize argument is no longer used. Please use `limit` instead.
+            Deprecated. The pagesize argument is no longer used. Please use ``limit`` instead.
         page : int, optional
-            Deprecated. The page argument is no longer used. Please use `offset` instead.
+            Deprecated. The page argument is no longer used. Please use ``offset`` instead.
         **criteria
             Keyword arguments representing criteria filters to apply.
 
@@ -597,7 +602,7 @@ def query_object(
     ):
         """
         Query for MAST catalog entries around a specified object name using criteria filters. To return columns
-        for a given collection and catalog, use `~astroquery.mast.collections.get_catalog_metadata`.
+        for a given collection and catalog, use `~astroquery.mast.CatalogsClass.get_column_metadata`.
 
         Parameters
         ----------
@@ -622,17 +627,17 @@ def query_object(
         sort_by : str or list of str, optional
             Column name(s) to sort the results by.
         sort_desc : bool or list of bool, optional
-            Indicates whether to sort in descending order for each column in `sort_by`. If a single bool,
-            applies to all columns. If a list, must match length of `sort_by`. Default is False (ascending order).
+            Indicates whether to sort in descending order for each column in ``sort_by``. If a single bool,
+            applies to all columns. If a list, must match length of ``sort_by``. Default is False (ascending order).
         filters : dict, optional
             Another parameter to specify criteria filters as a dictionary. Use this option when the name of a column
             conflicts with a named parameter of this method.
         version : str, optional
-            Deprecated. The version argument is no longer used. Please use `collection` and `catalog` instead.
+            Deprecated. The version argument is no longer used. Please use ``collection`` and ``catalog`` instead.
         pagesize : int, optional
-            Deprecated. The pagesize argument is no longer used. Please use `limit` instead.
+            Deprecated. The pagesize argument is no longer used. Please use ``limit`` instead.
         page : int, optional
-            Deprecated. The page argument is no longer used. Please use `offset` instead.
+            Deprecated. The page argument is no longer used. Please use ``offset`` instead.
         **criteria
             Keyword arguments representing criteria filters to apply.
 
@@ -1083,17 +1088,18 @@ def _create_adql_region(self, region):
 
         # Case 2: region is an astropy region object
         # TODO: When released, change these to use `CircleSphericalSkyRegion` and `PolygonSphericalSkyRegion`
-        elif isinstance(region, CircleSkyRegion):
-            center = region.center.icrs
-            radius = region.radius.to(u.deg).value
-            return f"CIRCLE('ICRS',{center.ra.deg},{center.dec.deg},{radius})"
-        elif isinstance(region, PolygonSkyRegion):
-            verts = region.vertices.icrs
-            point_string = ",".join(f"{v.ra.deg},{v.dec.deg}" for v in verts)
-            return f"POLYGON('ICRS',{point_string})"
+        if HAS_REGIONS:
+            if isinstance(region, CircleSkyRegion):
+                center = region.center.icrs
+                radius = region.radius.to(u.deg).value
+                return f"CIRCLE('ICRS',{center.ra.deg},{center.dec.deg},{radius})"
+            elif isinstance(region, PolygonSkyRegion):
+                verts = region.vertices.icrs
+                point_string = ",".join(f"{v.ra.deg},{v.dec.deg}" for v in verts)
+                return f"POLYGON('ICRS',{point_string})"
 
         # Case 3: region is an iterable of coordinate pairs
-        elif isinstance(region, Iterable):
+        if isinstance(region, Iterable):
             # Expect something like [(ra1, dec1), (ra2, dec2), ...]
             try:
                 points = [float(x) for point in region for x in point]

astroquery/mast/tests/data/README.rst

@@ -99,7 +99,7 @@ To generate `~astroquery.mast.tests.data.tap_columns.vot`, use the following:
     >>> result = tap_service.run_sync(query)
     >>> writeto(result.votable, 'tap_columns.vot')  # doctest: +SKIP
 
-To generate `~astroquery.mast.tests.data.tap_capabilities.vot`, use the following:
+To generate `~astroquery.mast.tests.data.tap_capabilities.xml`, use the following:
 
 .. doctest-remote-data::
 

astroquery/mast/tests/test_mast.py

@@ -21,7 +21,6 @@
 from pyvo.dal import TAPResults
 from pyvo.dal.exceptions import DALQueryError
 from pyvo.io.vosi import parse_capabilities
-from regions import CirclePixelRegion, CircleSkyRegion, PixCoord, PolygonSkyRegion
 from requests import HTTPError, Response
 
 from astroquery.exceptions import (
@@ -34,6 +33,7 @@
     ResolverError,
 )
 from astroquery.mast import (
+    CatalogCollection,
     Catalogs,
     Mast,
     MastMissions,
@@ -50,14 +50,21 @@
 from astroquery.mast.cloud import CloudAccess
 from astroquery.utils.mocks import MockResponse
 
-from ..catalog_collection import DEFAULT_CATALOGS, CatalogCollection, CatalogMetadata
+from ..catalog_collection import DEFAULT_CATALOGS, CatalogMetadata
 
 try:
     # Optional dependency import for cloud access functionality
     from botocore.exceptions import ClientError
 except ImportError:
     pass
 
+try:
+    # Optional dependency import for region handling in collections queries
+    from regions import CirclePixelRegion, CircleSkyRegion, PixCoord, PolygonSkyRegion
+    HAS_REGIONS = True
+except ImportError:
+    HAS_REGIONS = False
+
 DATA_FILES = {'Mast.Caom.Cone': 'caom.json',
               'Mast.Name.Lookup': 'resolver.json',
               'mission_search_results': 'mission_results.json',
@@ -315,7 +322,7 @@ def run_sync_mock(query, **kwargs):
             # Queries to get column metadata
             filename = data_path(DATA_FILES['tap_columns'])
         elif 'WHERE' in query:
-            # Queries with results, keep in mind this is not meaninful and results won't match the query
+            # Queries with results, keep in mind this is not meaningful and results won't match the query
             filename = data_path(DATA_FILES['tap_results'])
         votable = parse(filename)
 
@@ -1797,25 +1804,6 @@ def test_catalogs_create_adql_region(patch_tap):
     )
     assert adql_region == "POLYGON('ICRS',202.4656816,+47.1999842,202.5656816,+47.2999842,202.3656816,+47.0999842)"
 
-    # Astropy region objects
-    cone_region = CircleSkyRegion(
-        center=SkyCoord(10.8, 6.5, unit="deg"),
-        radius=Angle(0.5, unit="deg")
-    )
-    adql_region = Catalogs._create_adql_region(region=cone_region)
-    assert adql_region == "CIRCLE('ICRS',10.8,6.5,0.5)"
-
-    polygon_region = PolygonSkyRegion(
-        SkyCoord(
-            [57.376, 56.391, 56.025, 56.616],
-            [24.053, 24.622, 24.049, 24.291],
-            frame="icrs",
-            unit="deg",
-        )
-    )
-    adql_region = Catalogs._create_adql_region(region=polygon_region)
-    assert adql_region == "POLYGON('ICRS',57.376,24.053,56.391,24.622,56.025,24.049,56.616,24.291)"
-
     # Iterable coord pairs
     adql_region = Catalogs._create_adql_region(
         region=[
@@ -1827,6 +1815,26 @@ def test_catalogs_create_adql_region(patch_tap):
     )
     assert adql_region == "POLYGON('ICRS',57.376,24.053,56.391,24.622,56.025,24.049,56.616,24.291)"
 
+    if HAS_REGIONS:
+        # Astropy region objects
+        cone_region = CircleSkyRegion(
+            center=SkyCoord(10.8, 6.5, unit="deg"),
+            radius=Angle(0.5, unit="deg")
+        )
+        adql_region = Catalogs._create_adql_region(region=cone_region)
+        assert adql_region == "CIRCLE('ICRS',10.8,6.5,0.5)"
+
+        polygon_region = PolygonSkyRegion(
+            SkyCoord(
+                [57.376, 56.391, 56.025, 56.616],
+                [24.053, 24.622, 24.049, 24.291],
+                frame="icrs",
+                unit="deg",
+            )
+        )
+        adql_region = Catalogs._create_adql_region(region=polygon_region)
+        assert adql_region == "POLYGON('ICRS',57.376,24.053,56.391,24.622,56.025,24.049,56.616,24.291)"
+
 
 def test_catalogs_invalid_create_adql_region(patch_tap):
     # Polygon without points
@@ -1855,11 +1863,12 @@ def test_catalogs_invalid_create_adql_region(patch_tap):
             region=[57.376, 24.053, 56.391, 24.622, 56.025, 24.049, 56.616, 24.291]
         )
 
-    # Invalid astropy region
-    with pytest.raises(TypeError, match="Unsupported region type"):
-        Catalogs._create_adql_region(
-            region=CirclePixelRegion(PixCoord(x=42, y=43), 4.2)
-        )
+    if HAS_REGIONS:
+        # Invalid astropy region
+        with pytest.raises(TypeError, match="Unsupported region type"):
+            Catalogs._create_adql_region(
+                region=CirclePixelRegion(PixCoord(x=42, y=43), 4.2)
+            )
 
 
 def test_catalogs_parse_numeric_expression(patch_tap):

astroquery/mast/tests/test_mast_remote.py

@@ -15,6 +15,7 @@
 from requests.models import Response
 
 from astroquery.mast import (
+    CatalogCollection,
     Catalogs,
     Hapcut,
     Mast,
@@ -31,7 +32,7 @@
     MaxResultsWarning,
     NoResultsWarning,
 )
-from ..catalog_collection import DEFAULT_CATALOGS, CatalogCollection, CatalogMetadata
+from ..catalog_collection import DEFAULT_CATALOGS, CatalogMetadata
 from ..utils import ResolverError
 
 
@@ -1163,11 +1164,12 @@ def test_catalogs_query_criteria(self):
         assert not any(result["known_binary"])
         assert all(np.isin(result["sp_class"], ["O", "B"]))
         assert all(
-            (result["gaia_parallax"] < -0.01) | (result["gaia_parallax"] >= 0) | (result["gaia_parallax"] >= -0.3)
+            ((result["gaia_parallax"] < -0.01) | (result["gaia_parallax"] >= 0))
+            & ~(result["gaia_parallax"] < -0.3)
         )
         assert all((result["star_teff"] >= 30000) & (result["star_teff"] <= 50000))
         assert all(result["coordinate_epoch"] == 2016)
-        assert all(np.isin(result["spectral_type_ref"], [51, 18, 59, 1]))
+        assert all(np.isin(result["spectral_type_ref"], [51, 18, 59]))
         assert all(c in result.colnames for c in select_cols)
 
         # Test offset