Coverage for python/lsst/pipe/base/connectionTypes.py : 70%

Hot-keys 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 connection types to be used within a
23`PipelineTaskConnections` class.
24"""
26__all__ = ["InitInput", "InitOutput", "Input", "PrerequisiteInput",
27 "Output", "BaseConnection"]
29import dataclasses
30import typing
31from typing import Callable, Iterable, Optional
33from lsst.daf.butler import (
34 CollectionSearch,
35 DatasetRef,
36 DatasetType,
37 DimensionUniverse,
38 ExpandedDataCoordinate,
39 Registry,
40)
43@dataclasses.dataclass(frozen=True)
44class BaseConnection:
45 """Base class used for declaring PipelineTask connections
47 Parameters
48 ----------
49 name : `str`
50 The name used to identify the dataset type
51 storageClass : `str`
52 The storage class used when (un)/persisting the dataset type
53 multiple : `bool`
54 Indicates if this connection should expect to contain multiple objects
55 of the given dataset type
56 """
57 name: str
58 storageClass: str
59 doc: str = ""
60 multiple: bool = False
62 def __get__(self, inst, klass):
63 """Descriptor method
65 This is a method used to turn a connection into a descriptor.
66 When a connection is added to a connection class, it is a class level
67 variable. This method makes accessing this connection, on the
68 instance of the connection class owning this connection, return a
69 result specialized for that instance. In the case of connections
70 this specifically means names specified in a config instance will
71 be visible instead of the default names for the connection.
72 """
73 # If inst is None, this is being accessed by the class and not an
74 # instance, return this connection itself
75 if inst is None:
76 return self
77 # If no object cache exists, create one to track the instances this
78 # connection has been accessed by
79 if not hasattr(inst, '_connectionCache'):
80 object.__setattr__(inst, '_connectionCache', {})
81 # Look up an existing cached instance
82 idSelf = id(self)
83 if idSelf in inst._connectionCache:
84 return inst._connectionCache[idSelf]
85 # Accumulate the parameters that define this connection
86 params = {}
87 for field in dataclasses.fields(self):
88 params[field.name] = getattr(self, field.name)
89 # Get the name override defined by the instance of the connection class
90 params['name'] = inst._nameOverrides[self.varName]
91 # Return a new instance of this connection specialized with the
92 # information provided by the connection class instance
93 return inst._connectionCache.setdefault(idSelf, self.__class__(**params))
96@dataclasses.dataclass(frozen=True)
97class DimensionedConnection(BaseConnection):
98 """Class used for declaring PipelineTask connections that includes
99 dimensions
101 Parameters
102 ----------
103 name : `str`
104 The name used to identify the dataset type
105 storageClass : `str`
106 The storage class used when (un)/persisting the dataset type
107 multiple : `bool`
108 Indicates if this connection should expect to contain multiple objects
109 of the given dataset type
110 dimensions : iterable of `str`
111 The `lsst.daf.butler.Butler` `lsst.daf.butler.Registry` dimensions used
112 to identify the dataset type identified by the specified name
113 """
114 dimensions: typing.Iterable[str] = ()
116 def makeDatasetType(self, universe: DimensionUniverse):
117 """Construct a true `DatasetType` instance with normalized dimensions.
118 Parameters
119 ----------
120 universe : `lsst.daf.butler.DimensionUniverse`
121 Set of all known dimensions to be used to normalize the dimension
122 names specified in config.
123 Returns
124 -------
125 datasetType : `DatasetType`
126 The `DatasetType` defined by this connection.
127 """
128 return DatasetType(self.name,
129 universe.extract(self.dimensions),
130 self.storageClass)
133@dataclasses.dataclass(frozen=True)
134class BaseInput(DimensionedConnection):
135 """Class used for declaring PipelineTask input connections
137 Parameters
138 ----------
139 name : `str`
140 The default name used to identify the dataset type
141 storageClass : `str`
142 The storage class used when (un)/persisting the dataset type
143 multiple : `bool`
144 Indicates if this connection should expect to contain multiple objects
145 of the given dataset type
146 dimensions : iterable of `str`
147 The `lsst.daf.butler.Butler` `lsst.daf.butler.Registry` dimensions used
148 to identify the dataset type identified by the specified name
149 deferLoad : `bool`
150 Indicates that this dataset type will be loaded as a
151 `lsst.daf.butler.DeferredDatasetHandle`. PipelineTasks can use this
152 object to load the object at a later time.
153 """
154 deferLoad: bool = False
157@dataclasses.dataclass(frozen=True)
158class Input(BaseInput):
159 pass
162@dataclasses.dataclass(frozen=True)
163class PrerequisiteInput(BaseInput):
164 """Class used for declaring PipelineTask prerequisite connections
166 Parameters
167 ----------
168 name : `str`
169 The default name used to identify the dataset type
170 storageClass : `str`
171 The storage class used when (un)/persisting the dataset type
172 multiple : `bool`
173 Indicates if this connection should expect to contain multiple objects
174 of the given dataset type
175 dimensions : iterable of `str`
176 The `lsst.daf.butler.Butler` `lsst.daf.butler.Registry` dimensions used
177 to identify the dataset type identified by the specified name
178 deferLoad : `bool`
179 Indicates that this dataset type will be loaded as a
180 `lsst.daf.butler.DeferredDatasetHandle`. PipelineTasks can use this
181 object to load the object at a later time.
182 lookupFunction: `typing.Callable`, optional
183 An optional callable function that will look up PrerequisiteInputs
184 using the DatasetType, registry, quantum dataId, and input collections
185 passed to it. If no function is specified, the default temporal spatial
186 lookup will be used.
187 """
188 lookupFunction: Optional[Callable[[DatasetType, Registry, ExpandedDataCoordinate, CollectionSearch],
189 Iterable[DatasetRef]]] = None
192@dataclasses.dataclass(frozen=True)
193class Output(DimensionedConnection):
194 pass
197@dataclasses.dataclass(frozen=True)
198class InitInput(BaseConnection):
199 pass
202@dataclasses.dataclass(frozen=True)
203class InitOutput(BaseConnection):
204 pass