Coverage for python/lsst/pipe/base/butlerQuantumContext.py: 12%
Shortcuts on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
Shortcuts on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# This file is part of pipe_base.
2#
3# Developed for the LSST Data Management System.
4# This product includes software developed by the LSST Project
5# (http://www.lsst.org).
6# See the COPYRIGHT file at the top-level directory of this distribution
7# for details of code ownership.
8#
9# This program is free software: you can redistribute it and/or modify
10# it under the terms of the GNU General Public License as published by
11# the Free Software Foundation, either version 3 of the License, or
12# (at your option) any later version.
13#
14# This program is distributed in the hope that it will be useful,
15# but WITHOUT ANY WARRANTY; without even the implied warranty of
16# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17# GNU General Public License for more details.
18#
19# You should have received a copy of the GNU General Public License
20# along with this program. If not, see <http://www.gnu.org/licenses/>.
22"""Module defining a butler like object specialized to a specific quantum.
23"""
25__all__ = ("ButlerQuantumContext",)
27from typing import Any, List, Sequence, Union
29from lsst.daf.butler import Butler, DatasetRef, Quantum
31from .connections import DeferredDatasetRef, InputQuantizedConnection, OutputQuantizedConnection
32from .struct import Struct
35class ButlerQuantumContext:
36 """A Butler-like class specialized for a single quantum
38 A ButlerQuantumContext class wraps a standard butler interface and
39 specializes it to the context of a given quantum. What this means
40 in practice is that the only gets and puts that this class allows
41 are DatasetRefs that are contained in the quantum.
43 In the future this class will also be used to record provenance on
44 what was actually get and put. This is in contrast to what the
45 preflight expects to be get and put by looking at the graph before
46 execution.
48 Parameters
49 ----------
50 butler : `lsst.daf.butler.Butler`
51 Butler object from/to which datasets will be get/put
52 quantum : `lsst.daf.butler.core.Quantum`
53 Quantum object that describes the datasets which will be get/put by a
54 single execution of this node in the pipeline graph. All input
55 dataset references must be resolved (i.e. satisfy
56 ``DatasetRef.id is not None``) prior to constructing the
57 `ButlerQuantumContext`.
59 Notes
60 -----
61 Most quanta in any non-trivial graph will not start with resolved dataset
62 references, because they represent processing steps that can only run
63 after some other quanta have produced their inputs. At present, it is the
64 responsibility of ``lsst.ctrl.mpexec.SingleQuantumExecutor`` to resolve all
65 datasets prior to constructing `ButlerQuantumContext` and calling
66 `runQuantum`, and the fact that this precondition is satisfied by code in
67 a downstream package is considered a problem with the
68 ``pipe_base/ctrl_mpexec`` separation of concerns that will be addressed in
69 the future.
70 """
72 def __init__(self, butler: Butler, quantum: Quantum):
73 self.quantum = quantum
74 self.registry = butler.registry
75 self.allInputs = set()
76 self.allOutputs = set()
77 for refs in quantum.inputs.values():
78 for ref in refs:
79 self.allInputs.add((ref.datasetType, ref.dataId))
80 for refs in quantum.outputs.values():
81 for ref in refs:
82 self.allOutputs.add((ref.datasetType, ref.dataId))
83 self.__butler = butler
85 def _get(self, ref: DatasetRef) -> Any:
86 # Butler methods below will check for unresolved DatasetRefs and
87 # raise appropriately, so no need for us to do that here.
88 if isinstance(ref, DeferredDatasetRef):
89 self._checkMembership(ref.datasetRef, self.allInputs)
90 return self.__butler.getDirectDeferred(ref.datasetRef)
92 else:
93 self._checkMembership(ref, self.allInputs)
94 return self.__butler.getDirect(ref)
96 def _put(self, value: Any, ref: DatasetRef):
97 self._checkMembership(ref, self.allOutputs)
98 self.__butler.put(value, ref)
100 def get(self, dataset: Union[InputQuantizedConnection, List[DatasetRef], DatasetRef]) -> Any:
101 """Fetches data from the butler
103 Parameters
104 ----------
105 dataset
106 This argument may either be an `InputQuantizedConnection` which
107 describes all the inputs of a quantum, a list of
108 `~lsst.daf.butler.DatasetRef`, or a single
109 `~lsst.daf.butler.DatasetRef`. The function will get and return
110 the corresponding datasets from the butler.
112 Returns
113 -------
114 return : `object`
115 This function returns arbitrary objects fetched from the bulter.
116 The structure these objects are returned in depends on the type of
117 the input argument. If the input dataset argument is a
118 `InputQuantizedConnection`, then the return type will be a
119 dictionary with keys corresponding to the attributes of the
120 `InputQuantizedConnection` (which in turn are the attribute
121 identifiers of the connections). If the input argument is of type
122 `list` of `~lsst.daf.butler.DatasetRef` then the return type will
123 be a list of objects. If the input argument is a single
124 `~lsst.daf.butler.DatasetRef` then a single object will be
125 returned.
127 Raises
128 ------
129 ValueError
130 Raised if a `DatasetRef` is passed to get that is not defined in
131 the quantum object
132 """
133 if isinstance(dataset, InputQuantizedConnection):
134 retVal = {}
135 for name, ref in dataset:
136 if isinstance(ref, list):
137 val = [self._get(r) for r in ref]
138 else:
139 val = self._get(ref)
140 retVal[name] = val
141 return retVal
142 elif isinstance(dataset, list):
143 return [self._get(x) for x in dataset]
144 elif isinstance(dataset, DatasetRef) or isinstance(dataset, DeferredDatasetRef):
145 return self._get(dataset)
146 else:
147 raise TypeError("Dataset argument is not a type that can be used to get")
149 def put(
150 self,
151 values: Union[Struct, List[Any], Any],
152 dataset: Union[OutputQuantizedConnection, List[DatasetRef], DatasetRef],
153 ):
154 """Puts data into the butler
156 Parameters
157 ----------
158 values : `Struct` or `list` of `object` or `object`
159 The data that should be put with the butler. If the type of the
160 dataset is `OutputQuantizedConnection` then this argument should be
161 a `Struct` with corresponding attribute names. Each attribute
162 should then correspond to either a list of object or a single
163 object depending of the type of the corresponding attribute on
164 dataset. I.e. if ``dataset.calexp`` is
165 ``[datasetRef1, datasetRef2]`` then ``values.calexp`` should be
166 ``[calexp1, calexp2]``. Like wise if there is a single ref, then
167 only a single object need be passed. The same restriction applies
168 if dataset is directly a `list` of `DatasetRef` or a single
169 `DatasetRef`.
170 dataset
171 This argument may either be an `InputQuantizedConnection` which
172 describes all the inputs of a quantum, a list of
173 `lsst.daf.butler.DatasetRef`, or a single
174 `lsst.daf.butler.DatasetRef`. The function will get and return
175 the corresponding datasets from the butler.
177 Raises
178 ------
179 ValueError
180 Raised if a `DatasetRef` is passed to put that is not defined in
181 the quantum object, or the type of values does not match what is
182 expected from the type of dataset.
183 """
184 if isinstance(dataset, OutputQuantizedConnection):
185 if not isinstance(values, Struct):
186 raise ValueError(
187 "dataset is a OutputQuantizedConnection, a Struct with corresponding"
188 " attributes must be passed as the values to put"
189 )
190 for name, refs in dataset:
191 valuesAttribute = getattr(values, name)
192 if isinstance(refs, list):
193 if len(refs) != len(valuesAttribute):
194 raise ValueError(f"There must be a object to put for every Dataset ref in {name}")
195 for i, ref in enumerate(refs):
196 self._put(valuesAttribute[i], ref)
197 else:
198 self._put(valuesAttribute, refs)
199 elif isinstance(dataset, list):
200 if not isinstance(values, Sequence):
201 raise ValueError("Values to put must be a sequence")
202 if len(dataset) != len(values):
203 raise ValueError("There must be a common number of references and values to put")
204 for i, ref in enumerate(dataset):
205 self._put(values[i], ref)
206 elif isinstance(dataset, DatasetRef):
207 self._put(values, dataset)
208 else:
209 raise TypeError("Dataset argument is not a type that can be used to put")
211 def _checkMembership(self, ref: Union[List[DatasetRef], DatasetRef], inout: set):
212 """Internal function used to check if a DatasetRef is part of the input
213 quantum
215 This function will raise an exception if the ButlerQuantumContext is
216 used to get/put a DatasetRef which is not defined in the quantum.
218 Parameters
219 ----------
220 ref : `list` of `DatasetRef` or `DatasetRef`
221 Either a list or a single `DatasetRef` to check
222 inout : `set`
223 The connection type to check, e.g. either an input or an output.
224 This prevents both types needing to be checked for every operation,
225 which may be important for Quanta with lots of `DatasetRef`.
226 """
227 if not isinstance(ref, list):
228 ref = [ref]
229 for r in ref:
230 if (r.datasetType, r.dataId) not in inout:
231 raise ValueError("DatasetRef is not part of the Quantum being processed")