From 232636504892333df6ea3b8a0c44a40e9d49bfae Mon Sep 17 00:00:00 2001 From: "David H. Irving" Date: Wed, 16 Oct 2024 16:07:01 -0700 Subject: [PATCH 1/2] Include advanced query system objects in docs `Butler.query` has been public for a while, but the documentation for the `Query` object it returns was not included in the documentation. This change pulls in the user-facing portions of the interface without any of the internal objects. (The internal objects are sometimes referenced from constructors, but those constructors are documented as "do not use".) --- doc/lsst.daf.butler/index.rst | 22 +++++++++++++++++++ python/lsst/daf/butler/queries/_query.py | 3 ++- .../lsst/daf/butler/queries/tree/__init__.py | 1 - 3 files changed, 24 insertions(+), 2 deletions(-) diff --git a/doc/lsst.daf.butler/index.rst b/doc/lsst.daf.butler/index.rst index 7c20d4a538..3b71642a0e 100644 --- a/doc/lsst.daf.butler/index.rst +++ b/doc/lsst.daf.butler/index.rst @@ -104,6 +104,17 @@ Python API reference :no-inherited-members: :skip: RegistryConfig +Advanced query system +--------------------- + +.. automodapi:: lsst.daf.butler.queries + :headings: ^" + :no-main-docstr: + +.. automodapi:: lsst.daf.butler.queries.expression_factory + :headings: ^" + :no-main-docstr: + Example datastores ------------------ @@ -173,6 +184,17 @@ Datastore utilities :headings: ^" :skip: Datastore +Advanced query system internals +------------------------------- + +.. automodapi:: lsst.daf.butler.queries.tree + :no-main-docstr: + :no-inherited-members: + :headings: ^" + :include: Predicate + :skip: DataCoordinateUploadKey + :skip: MaterializationKey + Registry utilities and interfaces --------------------------------- diff --git a/python/lsst/daf/butler/queries/_query.py b/python/lsst/daf/butler/queries/_query.py index bb57a5fb15..32049dad0d 100644 --- a/python/lsst/daf/butler/queries/_query.py +++ b/python/lsst/daf/butler/queries/_query.py @@ -82,7 +82,7 @@ class Query(QueryBase): Notes ----- `Query` objects should never be constructed directly by users; use - `Butler._query` instead. + `Butler.query` instead. A `Query` object represents the first stage of query construction, in which constraints and joins are defined (roughly corresponding to the WHERE and @@ -135,6 +135,7 @@ def constraint_dimensions(self) -> DimensionGroup: @property def expression_factory(self) -> ExpressionFactory: """A factory for column expressions using overloaded operators. + (`~lsst.daf.butler.queries.expression_factory.ExpressionFactory`). Notes ----- diff --git a/python/lsst/daf/butler/queries/tree/__init__.py b/python/lsst/daf/butler/queries/tree/__init__.py index e320695f62..f59363d407 100644 --- a/python/lsst/daf/butler/queries/tree/__init__.py +++ b/python/lsst/daf/butler/queries/tree/__init__.py @@ -35,6 +35,5 @@ from ._query_tree import * LogicalNot.model_rebuild() -del LogicalNot Predicate.model_rebuild() From f27bf9fab4c99228b2af80bb005e4c5a819ecc95 Mon Sep 17 00:00:00 2001 From: "David H. Irving" Date: Thu, 17 Oct 2024 09:39:50 -0700 Subject: [PATCH 2/2] Apply review suggestion to hide symbol --- python/lsst/daf/butler/queries/tree/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/python/lsst/daf/butler/queries/tree/__init__.py b/python/lsst/daf/butler/queries/tree/__init__.py index f59363d407..845fc86f47 100644 --- a/python/lsst/daf/butler/queries/tree/__init__.py +++ b/python/lsst/daf/butler/queries/tree/__init__.py @@ -30,10 +30,10 @@ from ._column_literal import * from ._column_reference import * from ._column_set import * +from ._predicate import LogicalNot as _LogicalNot from ._predicate import * -from ._predicate import LogicalNot from ._query_tree import * -LogicalNot.model_rebuild() +_LogicalNot.model_rebuild() Predicate.model_rebuild()