Coverage for python/lsst/daf/butler/registry/interfaces/_opaque.py: 87%

39 statements  

« prev     ^ index     » next       coverage.py v7.3.1, created at 2023-10-02 08:00 +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 software is dual licensed under the GNU General Public License and also 

10# under a 3-clause BSD license. Recipients may choose which of these licenses 

11# to use; please see the files gpl-3.0.txt and/or bsd_license.txt, 

12# respectively. If you choose the GPL option then the following text applies 

13# (but note that there is still no warranty even if you opt for BSD instead): 

14# 

15# This program is free software: you can redistribute it and/or modify 

16# it under the terms of the GNU General Public License as published by 

17# the Free Software Foundation, either version 3 of the License, or 

18# (at your option) any later version. 

19# 

20# This program is distributed in the hope that it will be useful, 

21# but WITHOUT ANY WARRANTY; without even the implied warranty of 

22# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 

23# GNU General Public License for more details. 

24# 

25# You should have received a copy of the GNU General Public License 

26# along with this program. If not, see <http://www.gnu.org/licenses/>. 

27 

28"""Interfaces for the objects that manage opaque (logical) tables within a 

29`Registry`. 

30""" 

31 

32from __future__ import annotations 

33 

34__all__ = ["OpaqueTableStorageManager", "OpaqueTableStorage"] 

35 

36from abc import ABC, abstractmethod 

37from collections.abc import Iterable, Iterator, Mapping 

38from typing import TYPE_CHECKING, Any 

39 

40from ...core.ddl import TableSpec 

41from ._database import Database, StaticTablesContext 

42from ._versioning import VersionedExtension, VersionTuple 

43 

44if TYPE_CHECKING: 

45 from ...core.datastore import DatastoreTransaction 

46 

47 

48class OpaqueTableStorage(ABC): 

49 """An interface that manages the records associated with a particular 

50 opaque table in a `Registry`. 

51 

52 Parameters 

53 ---------- 

54 name : `str` 

55 Name of the opaque table. 

56 """ 

57 

58 def __init__(self, name: str): 

59 self.name = name 

60 

61 @abstractmethod 

62 def insert(self, *data: dict, transaction: DatastoreTransaction | None = None) -> None: 

63 """Insert records into the table. 

64 

65 Parameters 

66 ---------- 

67 *data 

68 Each additional positional argument is a dictionary that represents 

69 a single row to be added. 

70 transaction : `DatastoreTransaction`, optional 

71 Transaction object that can be used to enable an explicit rollback 

72 of the insert to be registered. Can be ignored if rollback is 

73 handled via a different mechanism, such as by a database. Can be 

74 `None` if no external transaction is available. 

75 """ 

76 raise NotImplementedError() 

77 

78 @abstractmethod 

79 def ensure(self, *data: dict, transaction: DatastoreTransaction | None = None) -> None: 

80 """Insert records into the table, skipping rows that already exist. 

81 

82 Parameters 

83 ---------- 

84 *data 

85 Each additional positional argument is a dictionary that represents 

86 a single row to be added. 

87 transaction : `DatastoreTransaction`, optional 

88 Transaction object that can be used to enable an explicit rollback 

89 of the insert to be registered. Can be ignored if rollback is 

90 handled via a different mechanism, such as by a database. Can be 

91 `None` if no external transaction is available. 

92 """ 

93 raise NotImplementedError() 

94 

95 @abstractmethod 

96 def replace(self, *data: dict, transaction: DatastoreTransaction | None = None) -> None: 

97 """Insert records into the table, replacing if previously existing 

98 but different. 

99 

100 Parameters 

101 ---------- 

102 *data 

103 Each additional positional argument is a dictionary that represents 

104 a single row to be added. 

105 transaction : `DatastoreTransaction`, optional 

106 Transaction object that can be used to enable an explicit rollback 

107 of the insert to be registered. Can be ignored if rollback is 

108 handled via a different mechanism, such as by a database. Can be 

109 `None` if no external transaction is available. 

110 """ 

111 raise NotImplementedError() 

112 

113 @abstractmethod 

114 def fetch(self, **where: Any) -> Iterator[Mapping[Any, Any]]: 

115 """Retrieve records from an opaque table. 

116 

117 Parameters 

118 ---------- 

119 **where 

120 Additional keyword arguments are interpreted as equality 

121 constraints that restrict the returned rows (combined with AND); 

122 keyword arguments are column names and values are the values they 

123 must have. 

124 

125 Yields 

126 ------ 

127 row : `dict` 

128 A dictionary representing a single result row. 

129 """ 

130 raise NotImplementedError() 

131 

132 @abstractmethod 

133 def delete(self, columns: Iterable[str], *rows: dict) -> None: 

134 """Remove records from an opaque table. 

135 

136 Parameters 

137 ---------- 

138 columns: `~collections.abc.Iterable` of `str` 

139 The names of columns that will be used to constrain the rows to 

140 be deleted; these will be combined via ``AND`` to form the 

141 ``WHERE`` clause of the delete query. 

142 *rows 

143 Positional arguments are the keys of rows to be deleted, as 

144 dictionaries mapping column name to value. The keys in all 

145 dictionaries must be exactly the names in ``columns``. 

146 """ 

147 raise NotImplementedError() 

148 

149 name: str 

150 """The name of the logical table this instance manages (`str`). 

151 """ 

152 

153 

154class OpaqueTableStorageManager(VersionedExtension): 

155 """An interface that manages the opaque tables in a `Registry`. 

156 

157 `OpaqueTableStorageManager` primarily serves as a container and factory for 

158 `OpaqueTableStorage` instances, which each provide access to the records 

159 for a different (logical) opaque table. 

160 

161 Notes 

162 ----- 

163 Opaque tables are primarily used by `Datastore` instances to manage their 

164 internal data in the same database that hold the `Registry`, but are not 

165 limited to this. 

166 

167 While an opaque table in a multi-layer `Registry` may in fact be the union 

168 of multiple tables in different layers, we expect this to be rare, as 

169 `Registry` layers will typically correspond to different leaf `Datastore` 

170 instances (each with their own opaque table) in a `ChainedDatastore`. 

171 """ 

172 

173 def __init__(self, *, registry_schema_version: VersionTuple | None = None): 

174 super().__init__(registry_schema_version=registry_schema_version) 

175 

176 @classmethod 

177 @abstractmethod 

178 def initialize( 

179 cls, db: Database, context: StaticTablesContext, registry_schema_version: VersionTuple | None = None 

180 ) -> OpaqueTableStorageManager: 

181 """Construct an instance of the manager. 

182 

183 Parameters 

184 ---------- 

185 db : `Database` 

186 Interface to the underlying database engine and namespace. 

187 context : `StaticTablesContext` 

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

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

190 implemented with this manager. 

191 registry_schema_version : `VersionTuple` or `None` 

192 Schema version of this extension as defined in registry. 

193 

194 Returns 

195 ------- 

196 manager : `OpaqueTableStorageManager` 

197 An instance of a concrete `OpaqueTableStorageManager` subclass. 

198 """ 

199 raise NotImplementedError() 

200 

201 def __getitem__(self, name: str) -> OpaqueTableStorage: 

202 """Interface to `get` that raises `LookupError` instead of returning 

203 `None` on failure. 

204 """ 

205 r = self.get(name) 

206 if r is None: 

207 raise LookupError(f"No logical table with name '{name}' found.") 

208 return r 

209 

210 @abstractmethod 

211 def get(self, name: str) -> OpaqueTableStorage | None: 

212 """Return an object that provides access to the records associated with 

213 an opaque logical table. 

214 

215 Parameters 

216 ---------- 

217 name : `str` 

218 Name of the logical table. 

219 

220 Returns 

221 ------- 

222 records : `OpaqueTableStorage` or `None` 

223 The object representing the records for the given table in this 

224 layer, or `None` if there are no records for that table in this 

225 layer. 

226 

227 Notes 

228 ----- 

229 Opaque tables must be registered with the layer (see `register`) by 

230 the same client before they can safely be retrieved with `get`. 

231 Unlike most other manager classes, the set of opaque tables cannot be 

232 obtained from an existing data repository. 

233 """ 

234 raise NotImplementedError() 

235 

236 @abstractmethod 

237 def register(self, name: str, spec: TableSpec) -> OpaqueTableStorage: 

238 """Ensure that this layer can hold records for the given opaque logical 

239 table, creating new tables as necessary. 

240 

241 Parameters 

242 ---------- 

243 name : `str` 

244 Name of the logical table. 

245 spec : `TableSpec` 

246 Schema specification for the table to be created. 

247 

248 Returns 

249 ------- 

250 records : `OpaqueTableStorage` 

251 The object representing the records for the given element in this 

252 layer. 

253 

254 Notes 

255 ----- 

256 This operation may not be invoked within a transaction context block. 

257 """ 

258 raise NotImplementedError()