Rename Query.general to x_general to mark as experimental

python/lsst/daf/butler/queries/_query.py

@@ -310,7 +310,7 @@ def dimension_records(self, element: str) -> DimensionRecordQueryResults:
         result_spec = DimensionRecordResultSpec(element=self._driver.universe[element])
         return DimensionRecordQueryResults(self._driver, tree, result_spec)
 
-    def general(
+    def x_general(
         self,
         dimensions: DimensionGroup,
         *names: str,
@@ -320,6 +320,8 @@ def general(
     ) -> GeneralQueryResults:
         """Execute query returning general result.
 
+        **This is an experimental interface and may change at any time.**
+
         Parameters
         ----------
         dimensions : `DimensionGroup`

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

@@ -2428,7 +2428,7 @@ def queryDatasetAssociations(
         )
         with self._query() as query:
             query = query.join_dataset_search(datasetType, resolved_collections)
-            result = query.general(
+            result = query.x_general(
                 datasetType.dimensions,
                 dataset_fields={datasetType.name: {"dataset_id", "run", "collection", "timespan"}},
             )

python/lsst/daf/butler/remote_butler/_registry.py

@@ -521,7 +521,7 @@ def queryDatasetAssociations(
         )
         with self._butler.query() as query:
             query = query.join_dataset_search(datasetType, resolved_collections)
-            result = query.general(
+            result = query.x_general(
                 datasetType.dimensions,
                 dataset_fields={datasetType.name: {"dataset_id", "run", "collection", "timespan"}},
             )

python/lsst/daf/butler/tests/butler_queries.py

@@ -310,7 +310,7 @@ def test_general_query(self) -> None:
         # Do simple dimension queries.
         with butler.query() as query:
             query = query.join_dimensions(dimensions)
-            rows = list(query.general(dimensions).order_by("detector"))
+            rows = list(query.x_general(dimensions).order_by("detector"))
             self.assertEqual(
                 rows,
                 [
@@ -321,7 +321,7 @@ def test_general_query(self) -> None:
                 ],
             )
             rows = list(
-                query.general(dimensions, "detector.full_name", "purpose").order_by(
+                query.x_general(dimensions, "detector.full_name", "purpose").order_by(
                     "-detector.purpose", "full_name"
                 )
             )
@@ -355,7 +355,7 @@ def test_general_query(self) -> None:
                 ],
             )
             rows = list(
-                query.general(dimensions, "detector.full_name", "purpose").where(
+                query.x_general(dimensions, "detector.full_name", "purpose").where(
                     "instrument = 'Cam1' AND purpose = 'WAVEFRONT'"
                 )
             )
@@ -370,7 +370,7 @@ def test_general_query(self) -> None:
                     },
                 ],
             )
-            result = query.general(dimensions, dimension_fields={"detector": {"full_name"}})
+            result = query.x_general(dimensions, dimension_fields={"detector": {"full_name"}})
             self.assertEqual(set(row["detector.full_name"] for row in result), {"Aa", "Ab", "Ba", "Bb"})
 
         # Use "flat" whose dimension group includes implied dimension.
@@ -381,7 +381,7 @@ def test_general_query(self) -> None:
         with butler.query() as query:
             query = query.join_dataset_search("flat", "imported_g")
             # This just returns data IDs.
-            rows = list(query.general(dimensions).order_by("detector"))
+            rows = list(query.x_general(dimensions).order_by("detector"))
             self.assertEqual(
                 rows,
                 [
@@ -391,7 +391,7 @@ def test_general_query(self) -> None:
                 ],
             )
 
-            result = query.general(dimensions, dataset_fields={"flat": ...}).order_by("detector")
+            result = query.x_general(dimensions, dataset_fields={"flat": ...}).order_by("detector")
             ids = {row["flat.dataset_id"] for row in result}
             self.assertEqual(
                 ids,
@@ -435,7 +435,7 @@ def test_general_query(self) -> None:
         with butler.query() as query:
             query = query.join_dataset_search("flat", ["tagged"])
 
-            result = query.general(dimensions, "flat.dataset_id", "flat.run", "flat.collection")
+            result = query.x_general(dimensions, "flat.dataset_id", "flat.run", "flat.collection")
             row_tuples = list(result.iter_tuples(flat))
             self.assertEqual(len(row_tuples), 2)
             self.assertEqual({row_tuple.refs[0] for row_tuple in row_tuples}, {flat1, flat2})
@@ -444,7 +444,7 @@ def test_general_query(self) -> None:
         # Query calib collection.
         with butler.query() as query:
             query = query.join_dataset_search("flat", ["calib"])
-            result = query.general(
+            result = query.x_general(
                 dimensions, "flat.dataset_id", "flat.run", "flat.collection", "flat.timespan"
             )
             row_tuples = list(result.iter_tuples(flat))
@@ -459,7 +459,7 @@ def test_general_query(self) -> None:
         # Query both tagged and calib collection.
         with butler.query() as query:
             query = query.join_dataset_search("flat", ["tagged", "calib"])
-            result = query.general(
+            result = query.x_general(
                 dimensions, "flat.dataset_id", "flat.run", "flat.collection", "flat.timespan"
             )
             row_tuples = list(result.iter_tuples(flat))
@@ -482,7 +482,7 @@ def test_query_ingest_date(self) -> None:
         # for schema versions 1 and 2 of datasets manager.
         with butler.query() as query:
             query = query.join_dataset_search("flat", "imported_g")
-            rows = list(query.general(dimensions, dataset_fields={"flat": ...}))
+            rows = list(query.x_general(dimensions, dataset_fields={"flat": ...}))
             self.assertEqual(len(rows), 3)
             for row in rows:
                 self.assertIsInstance(row["flat.ingest_date"], astropy.time.Time)
@@ -491,14 +491,14 @@ def test_query_ingest_date(self) -> None:
         with butler.query() as query:
             query = query.join_dataset_search("flat", "imported_g")
             query1 = query.where("flat.ingest_date < before_ingest", bind={"before_ingest": before_ingest})
-            rows = list(query1.general(dimensions))
+            rows = list(query1.x_general(dimensions))
             self.assertEqual(len(rows), 0)
             query1 = query.where("flat.ingest_date >= before_ingest", bind={"before_ingest": before_ingest})
-            rows = list(query1.general(dimensions))
+            rows = list(query1.x_general(dimensions))
             self.assertEqual(len(rows), 3)
             # Same with a time in string literal.
             query1 = query.where(f"flat.ingest_date < T'mjd/{before_ingest.tai.mjd}'")
-            rows = list(query1.general(dimensions))
+            rows = list(query1.x_general(dimensions))
             self.assertEqual(len(rows), 0)
 
     def test_implied_union_record_query(self) -> None:

python/lsst/daf/butler/transfers/_context.py

@@ -365,7 +365,7 @@ def _computeDatasetAssociations(self) -> dict[str, list[DatasetAssociation]]:
             )
             with self._butler.query() as query:
                 query = query.join_dataset_search(datasetType, resolved_collections)
-                result = query.general(
+                result = query.x_general(
                     datasetType.dimensions,
                     dataset_fields={datasetType.name: {"dataset_id", "run", "collection", "timespan"}},
                 )