Hide keyboard shortcuts

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/>. 

21 

22"""Module defining connection types to be used within a 

23`PipelineTaskConnections` class. 

24""" 

25 

26__all__ = ["InitInput", "InitOutput", "Input", "PrerequisiteInput", 

27 "Output", "BaseConnection"] 

28 

29import dataclasses 

30import typing 

31from typing import Callable, Iterable, Optional 

32 

33from lsst.daf.butler import ( 

34 CollectionSearch, 

35 DataCoordinate, 

36 DatasetRef, 

37 DatasetType, 

38 DimensionUniverse, 

39 Registry, 

40) 

41 

42 

43@dataclasses.dataclass(frozen=True) 

44class BaseConnection: 

45 """Base class used for declaring PipelineTask connections 

46 

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 

61 

62 def __get__(self, inst, klass): 

63 """Descriptor method 

64 

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)) 

94 

95 

96@dataclasses.dataclass(frozen=True) 

97class DimensionedConnection(BaseConnection): 

98 """Class used for declaring PipelineTask connections that includes 

99 dimensions 

100 

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] = () 

115 

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) 

131 

132 

133@dataclasses.dataclass(frozen=True) 

134class BaseInput(DimensionedConnection): 

135 """Class used for declaring PipelineTask input connections 

136 

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 

155 

156 

157@dataclasses.dataclass(frozen=True) 

158class Input(BaseInput): 

159 pass 

160 

161 

162@dataclasses.dataclass(frozen=True) 

163class PrerequisiteInput(BaseInput): 

164 """Class used for declaring PipelineTask prerequisite connections 

165 

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, DataCoordinate, CollectionSearch], 

189 Iterable[DatasetRef]]] = None 

190 

191 

192@dataclasses.dataclass(frozen=True) 

193class Output(DimensionedConnection): 

194 pass 

195 

196 

197@dataclasses.dataclass(frozen=True) 

198class InitInput(BaseConnection): 

199 pass 

200 

201 

202@dataclasses.dataclass(frozen=True) 

203class InitOutput(BaseConnection): 

204 pass