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

27 statements  

« prev     ^ index     » next       coverage.py v6.5.0, created at 2023-01-06 01:41 -0800

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 ._collections import CollectionRecord 

37 from ._database import Database, StaticTablesContext 

38 from ._datasets import DatasetRecordStorageManager 

39 from ._dimensions import DimensionRecordStorageManager 

40 

41 

42class ObsCoreTableManager(VersionedExtension): 

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

44 

45 @classmethod 

46 @abstractmethod 

47 def initialize( 

48 cls, 

49 db: Database, 

50 context: StaticTablesContext, 

51 *, 

52 universe: DimensionUniverse, 

53 config: Mapping, 

54 datasets: Type[DatasetRecordStorageManager], 

55 dimensions: DimensionRecordStorageManager, 

56 ) -> ObsCoreTableManager: 

57 """Construct an instance of the manager. 

58 

59 Parameters 

60 ---------- 

61 db : `Database` 

62 Interface to the underlying database engine and namespace. 

63 context : `StaticTablesContext` 

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

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

66 implemented with this manager. 

67 universe : `DimensionUniverse` 

68 All dimensions known to the registry. 

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

70 Configuration of the obscore manager. 

71 datasets : `type` 

72 Type of dataset manager. 

73 dimensions: `DimensionRecordStorageManager` 

74 Manager for Registry dimensions. 

75 

76 Returns 

77 ------- 

78 manager : `ObsCoreTableManager` 

79 An instance of a concrete `ObsCoreTableManager` subclass. 

80 """ 

81 raise NotImplementedError() 

82 

83 @abstractmethod 

84 def config_json(self) -> str: 

85 """Dump configuration in JSON format. 

86 

87 Returns 

88 ------- 

89 json : `str` 

90 Configuration serialized in JSON format. 

91 """ 

92 raise NotImplementedError() 

93 

94 def add_datasets(self, refs: Iterable[DatasetRef]) -> int: 

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

96 

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

98 collection. 

99 

100 Parameters 

101 ---------- 

102 refs : `iterable` [ `DatasetRef` ] 

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

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

105 the dataset is ignored. 

106 

107 Returns 

108 ------- 

109 count : `int` 

110 Actual number of records inserted into obscore table. 

111 

112 Notes 

113 ----- 

114 Dataset data types and collection names are checked against configured 

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

116 ignored and not added to the obscore table. 

117 

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

119 method should return immediately. 

120 

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

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

123 dataset table with "ON DELETE CASCADE" option. 

124 """ 

125 raise NotImplementedError() 

126 

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

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

129 

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

131 a TAGGED collection. 

132 

133 Parameters 

134 ---------- 

135 refs : `iterable` [ `DatasetRef` ] 

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

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

138 the dataset is ignored. 

139 collection : `CollectionRecord` 

140 Collection record for a TAGGED collection. 

141 

142 Returns 

143 ------- 

144 count : `int` 

145 Actual number of records inserted into obscore table. 

146 

147 Notes 

148 ----- 

149 Dataset data types and collection names are checked against configured 

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

151 ignored and not added to the obscore table. 

152 

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

154 method should return immediately. 

155 """ 

156 raise NotImplementedError() 

157 

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

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

160 

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

162 TAGGED collection. 

163 

164 Parameters 

165 ---------- 

166 refs : `iterable` [ `DatasetRef` ] 

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

168 collection : `CollectionRecord` 

169 Collection record for a TAGGED collection. 

170 

171 Returns 

172 ------- 

173 count : `int` 

174 Actual number of records removed from obscore table. 

175 

176 Notes 

177 ----- 

178 Dataset data types and collection names are checked against configured 

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

180 ignored and not added to the obscore table. 

181 

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

183 method should return immediately. 

184 """ 

185 raise NotImplementedError()