Coverage for python/lsst/daf/butler/registry/interfaces/_obscore.py: 60%

28 statements  

« prev     ^ index     » next       coverage.py v6.5.0, created at 2023-02-01 10:03 +0000

1# This file is part of daf_butler. 

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

21from __future__ import annotations 

22 

23"""Interfaces for classes that manage obscore table(s) in a `Registry`. 

24""" 

25 

26__all__ = ["ObsCoreTableManager"] 

27 

28from abc import abstractmethod 

29from collections.abc import Mapping 

30from typing import TYPE_CHECKING, Iterable, Type 

31 

32from ._versioning import VersionedExtension 

33 

34if TYPE_CHECKING: 34 ↛ 35line 34 didn't jump to line 35, because the condition on line 34 was never true

35 from ...core import DatasetRef, DimensionUniverse 

36 from ..queries import SqlQueryContext 

37 from ._collections import CollectionRecord 

38 from ._database import Database, StaticTablesContext 

39 from ._datasets import DatasetRecordStorageManager 

40 from ._dimensions import DimensionRecordStorageManager 

41 

42 

43class ObsCoreTableManager(VersionedExtension): 

44 """An interface for populating ObsCore tables(s).""" 

45 

46 @classmethod 

47 @abstractmethod 

48 def initialize( 

49 cls, 

50 db: Database, 

51 context: StaticTablesContext, 

52 *, 

53 universe: DimensionUniverse, 

54 config: Mapping, 

55 datasets: Type[DatasetRecordStorageManager], 

56 dimensions: DimensionRecordStorageManager, 

57 ) -> ObsCoreTableManager: 

58 """Construct an instance of the manager. 

59 

60 Parameters 

61 ---------- 

62 db : `Database` 

63 Interface to the underlying database engine and namespace. 

64 context : `StaticTablesContext` 

65 Context object obtained from `Database.declareStaticTables`; used 

66 to declare any tables that should always be present in a layer 

67 implemented with this manager. 

68 universe : `DimensionUniverse` 

69 All dimensions known to the registry. 

70 config : `dict` [ `str`, `Any` ] 

71 Configuration of the obscore manager. 

72 datasets : `type` 

73 Type of dataset manager. 

74 dimensions: `DimensionRecordStorageManager` 

75 Manager for Registry dimensions. 

76 

77 Returns 

78 ------- 

79 manager : `ObsCoreTableManager` 

80 An instance of a concrete `ObsCoreTableManager` subclass. 

81 """ 

82 raise NotImplementedError() 

83 

84 @abstractmethod 

85 def config_json(self) -> str: 

86 """Dump configuration in JSON format. 

87 

88 Returns 

89 ------- 

90 json : `str` 

91 Configuration serialized in JSON format. 

92 """ 

93 raise NotImplementedError() 

94 

95 def add_datasets(self, refs: Iterable[DatasetRef], context: SqlQueryContext) -> int: 

96 """Possibly add datasets to the obscore table. 

97 

98 This method should be called when new datasets are added to a RUN 

99 collection. 

100 

101 Parameters 

102 ---------- 

103 refs : `iterable` [ `DatasetRef` ] 

104 Dataset refs to add. Dataset refs have to be completely expanded. 

105 If a record with the same dataset ID is already in obscore table, 

106 the dataset is ignored. 

107 context : `SqlQueryContext` 

108 Context used to execute queries for additional dimension metadata. 

109 

110 Returns 

111 ------- 

112 count : `int` 

113 Actual number of records inserted into obscore table. 

114 

115 Notes 

116 ----- 

117 Dataset data types and collection names are checked against configured 

118 list of collections and dataset types, non-matching datasets are 

119 ignored and not added to the obscore table. 

120 

121 When configuration parameter ``collection_type`` is not "RUN", this 

122 method should return immediately. 

123 

124 Note that there is no matching method to remove datasets from obscore 

125 table, we assume that removal happens via foreign key constraint to 

126 dataset table with "ON DELETE CASCADE" option. 

127 """ 

128 raise NotImplementedError() 

129 

130 def associate( 

131 self, refs: Iterable[DatasetRef], collection: CollectionRecord, context: SqlQueryContext 

132 ) -> int: 

133 """Possibly add datasets to the obscore table. 

134 

135 This method should be called when existing datasets are associated with 

136 a TAGGED collection. 

137 

138 Parameters 

139 ---------- 

140 refs : `iterable` [ `DatasetRef` ] 

141 Dataset refs to add. Dataset refs have to be completely expanded. 

142 If a record with the same dataset ID is already in obscore table, 

143 the dataset is ignored. 

144 collection : `CollectionRecord` 

145 Collection record for a TAGGED collection. 

146 context : `SqlQueryContext` 

147 Context used to execute queries for additional dimension metadata. 

148 

149 Returns 

150 ------- 

151 count : `int` 

152 Actual number of records inserted into obscore table. 

153 

154 Notes 

155 ----- 

156 Dataset data types and collection names are checked against configured 

157 list of collections and dataset types, non-matching datasets are 

158 ignored and not added to the obscore table. 

159 

160 When configuration parameter ``collection_type`` is not "TAGGED", this 

161 method should return immediately. 

162 """ 

163 raise NotImplementedError() 

164 

165 def disassociate(self, refs: Iterable[DatasetRef], collection: CollectionRecord) -> int: 

166 """Possibly remove datasets from the obscore table. 

167 

168 This method should be called when datasets are disassociated from a 

169 TAGGED collection. 

170 

171 Parameters 

172 ---------- 

173 refs : `iterable` [ `DatasetRef` ] 

174 Dataset refs to remove. Dataset refs have to be resolved. 

175 collection : `CollectionRecord` 

176 Collection record for a TAGGED collection. 

177 

178 Returns 

179 ------- 

180 count : `int` 

181 Actual number of records removed from obscore table. 

182 

183 Notes 

184 ----- 

185 Dataset data types and collection names are checked against configured 

186 list of collections and dataset types, non-matching datasets are 

187 ignored and not added to the obscore table. 

188 

189 When configuration parameter ``collection_type`` is not "TAGGED", this 

190 method should return immediately. 

191 """ 

192 raise NotImplementedError()