Add default value to query classes to allow usage to be detected

The components parameter is deprecated. Warn if False is specified
explicitly in addition to raising if any other value is used.

python/lsst/daf/butler/_registry_shim.py

@@ -53,6 +53,7 @@
 from .registry._collection_type import CollectionType
 from .registry._defaults import RegistryDefaults
 from .registry.queries import DataCoordinateQueryResults, DatasetQueryResults, DimensionRecordQueryResults
+from .utils import _DefaultMarker, _Marker
 
 if TYPE_CHECKING:
     from .direct_butler import DirectButler
@@ -281,7 +282,7 @@ def queryDatasetTypes(
         self,
         expression: Any = ...,
         *,
-        components: bool = False,
+        components: bool | _Marker = _DefaultMarker,
         missing: list[str] | None = None,
     ) -> Iterable[DatasetType]:
         # Docstring inherited from a base class.
@@ -309,7 +310,7 @@ def queryDatasets(
         dataId: DataId | None = None,
         where: str = "",
         findFirst: bool = False,
-        components: bool = False,
+        components: bool | _Marker = _DefaultMarker,
         bind: Mapping[str, Any] | None = None,
         check: bool = True,
         **kwargs: Any,
@@ -337,7 +338,7 @@ def queryDataIds(
         datasets: Any = None,
         collections: CollectionArgType | None = None,
         where: str = "",
-        components: bool = False,
+        components: bool | _Marker = _DefaultMarker,
         bind: Mapping[str, Any] | None = None,
         check: bool = True,
         **kwargs: Any,
@@ -363,7 +364,7 @@ def queryDimensionRecords(
         datasets: Any = None,
         collections: CollectionArgType | None = None,
         where: str = "",
-        components: bool = False,
+        components: bool | _Marker = _DefaultMarker,
         bind: Mapping[str, Any] | None = None,
         check: bool = True,
         **kwargs: Any,

python/lsst/daf/butler/registry/sql_registry.py

@@ -40,6 +40,7 @@
 import sqlalchemy
 from lsst.daf.relation import LeafRelation, Relation
 from lsst.resources import ResourcePathExpression
+from lsst.utils.introspection import find_outside_stacklevel
 from lsst.utils.iteration import ensure_iterable
 
 from .._column_tags import DatasetColumnTag
@@ -85,7 +86,7 @@
 from ..registry.interfaces import ChainedCollectionRecord, ReadOnlyDatabaseError, RunRecord
 from ..registry.managers import RegistryManagerInstances, RegistryManagerTypes
 from ..registry.wildcards import CollectionWildcard, DatasetTypeWildcard
-from ..utils import transactional
+from ..utils import transactional, _DefaultMarker, _Marker
 
 if TYPE_CHECKING:
     from .._butler_config import ButlerConfig
@@ -1703,7 +1704,7 @@ def queryDatasetTypes(
         self,
         expression: Any = ...,
         *,
-        components: bool = False,
+        components: bool | _Marker = _DefaultMarker,
         missing: list[str] | None = None,
     ) -> Iterable[DatasetType]:
         """Iterate over the dataset types whose names match an expression.
@@ -1735,11 +1736,18 @@ def queryDatasetTypes(
         lsst.daf.butler.registry.DatasetTypeExpressionError
             Raised when ``expression`` is invalid.
         """
-        if components is not False:
-            raise DatasetTypeError(
-                "Dataset component queries are no longer supported by Registry.  Use "
-                "DatasetType methods to obtain components from parent dataset types instead."
-            )
+        if components is not _DefaultMarker:
+            if components is not False:
+                raise DatasetTypeError(
+                    "Dataset component queries are no longer supported by Registry.  Use "
+                    "DatasetType methods to obtain components from parent dataset types instead."
+                )
+            else:
+                warnings.warn(
+                    "The components parameter is ignored. It will be removed after v27.",
+                    category=FutureWarning,
+                    stacklevel=find_outside_stacklevel("lsst.daf.butler"),
+                )
         wildcard = DatasetTypeWildcard.from_expression(expression)
         return self._managers.datasets.resolve_wildcard(wildcard, missing=missing)
 
@@ -1966,7 +1974,7 @@ def queryDatasets(
         dataId: DataId | None = None,
         where: str = "",
         findFirst: bool = False,
-        components: bool = False,
+        components: bool | _Marker = _DefaultMarker,
         bind: Mapping[str, Any] | None = None,
         check: bool = True,
         **kwargs: Any,
@@ -2068,11 +2076,18 @@ def queryDatasets(
         query), and then use multiple (generally much simpler) calls to
         `queryDatasets` with the returned data IDs passed as constraints.
         """
-        if components is not False:
-            raise DatasetTypeError(
-                "Dataset component queries are no longer supported by Registry.  Use "
-                "DatasetType methods to obtain components from parent dataset types instead."
-            )
+        if components is not _DefaultMarker:
+            if components is not False:
+                raise DatasetTypeError(
+                    "Dataset component queries are no longer supported by Registry.  Use "
+                    "DatasetType methods to obtain components from parent dataset types instead."
+                )
+            else:
+                warnings.warn(
+                    "The components parameter is ignored. It will be removed after v27.",
+                    category=FutureWarning,
+                    stacklevel=find_outside_stacklevel("lsst.daf.butler"),
+                )
         doomed_by: list[str] = []
         data_id = self._standardize_query_data_id_args(dataId, doomed_by=doomed_by, **kwargs)
         resolved_dataset_types, collection_wildcard = self._standardize_query_dataset_args(
@@ -2138,7 +2153,7 @@ def queryDataIds(
         datasets: Any = None,
         collections: CollectionArgType | None = None,
         where: str = "",
-        components: bool = False,
+        components: bool | _Marker = _DefaultMarker,
         bind: Mapping[str, Any] | None = None,
         check: bool = True,
         **kwargs: Any,
@@ -2231,11 +2246,18 @@ def queryDataIds(
         lsst.daf.butler.registry.UserExpressionError
             Raised when ``where`` expression is invalid.
         """
-        if components is not False:
-            raise DatasetTypeError(
-                "Dataset component queries are no longer supported by Registry.  Use "
-                "DatasetType methods to obtain components from parent dataset types instead."
-            )
+        if components is not _DefaultMarker:
+            if components is not False:
+                raise DatasetTypeError(
+                    "Dataset component queries are no longer supported by Registry.  Use "
+                    "DatasetType methods to obtain components from parent dataset types instead."
+                )
+            else:
+                warnings.warn(
+                    "The components parameter is ignored. It will be removed after v27.",
+                    category=FutureWarning,
+                    stacklevel=find_outside_stacklevel("lsst.daf.butler"),
+                )
         requested_dimensions = self.dimensions.conform(dimensions)
         doomed_by: list[str] = []
         data_id = self._standardize_query_data_id_args(dataId, doomed_by=doomed_by, **kwargs)
@@ -2269,7 +2291,7 @@ def queryDimensionRecords(
         datasets: Any = None,
         collections: CollectionArgType | None = None,
         where: str = "",
-        components: bool = False,
+        components: bool | _Marker = _DefaultMarker,
         bind: Mapping[str, Any] | None = None,
         check: bool = True,
         **kwargs: Any,
@@ -2344,11 +2366,18 @@ def queryDimensionRecords(
         lsst.daf.butler.registry.UserExpressionError
             Raised when ``where`` expression is invalid.
         """
-        if components is not False:
-            raise DatasetTypeError(
-                "Dataset component queries are no longer supported by Registry.  Use "
-                "DatasetType methods to obtain components from parent dataset types instead."
-            )
+        if components is not _DefaultMarker:
+            if components is not False:
+                raise DatasetTypeError(
+                    "Dataset component queries are no longer supported by Registry.  Use "
+                    "DatasetType methods to obtain components from parent dataset types instead."
+                )
+            else:
+                warnings.warn(
+                    "The components parameter is ignored. It will be removed after v27.",
+                    category=FutureWarning,
+                    stacklevel=find_outside_stacklevel("lsst.daf.butler"),
+                )
         if not isinstance(element, DimensionElement):
             try:
                 element = self.dimensions[element]

python/lsst/daf/butler/utils.py

@@ -132,3 +132,15 @@ def globToRegex(expressions: str | EllipsisType | None | list[str]) -> list[str
             res = e
         results.append(res)
     return results
+
+
+class _Marker:
+    """Private class to use as a default value when you want to know that
+    a default parameter has been over-ridden.
+    """
+
+
+_DefaultMarker = _Marker()
+"""Default value to give to a parameter when you want to know if the value
+has been over-ridden.
+"""

tests/test_testRepo.py

@@ -171,7 +171,8 @@ def testAddDataIdValue(self):
     def testAddDatasetType(self):
         # 1 for StructuredDataNoComponents, 1 for StructuredData (components
         # not included).
-        self.assertEqual(len(list(self.butler.registry.queryDatasetTypes(components=False))), 2)
+        with self.assertWarns(FutureWarning):
+            self.assertEqual(len(list(self.butler.registry.queryDatasetTypes(components=False))), 2)
 
         # Testing the DatasetType objects is not practical, because all tests
         # need a DimensionUniverse. So just check that we have the dataset