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

41 statements  

« prev     ^ index     » next       coverage.py v7.5.0, created at 2024-04-30 02:53 -0700

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 ...ddl import TableSpec 

41from ._database import Database, StaticTablesContext 

42from ._versioning import VersionedExtension, VersionTuple 

43 

44if TYPE_CHECKING: 

45 from ...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 Parameters 

162 ---------- 

163 registry_schema_version : `VersionTuple` or `None`, optional 

164 Version of registry schema. 

165 

166 Notes 

167 ----- 

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

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

170 limited to this. 

171 

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

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

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

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

176 """ 

177 

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

179 super().__init__(registry_schema_version=registry_schema_version) 

180 

181 @classmethod 

182 @abstractmethod 

183 def initialize( 

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

185 ) -> OpaqueTableStorageManager: 

186 """Construct an instance of the manager. 

187 

188 Parameters 

189 ---------- 

190 db : `Database` 

191 Interface to the underlying database engine and namespace. 

192 context : `StaticTablesContext` 

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

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

195 implemented with this manager. 

196 registry_schema_version : `VersionTuple` or `None` 

197 Schema version of this extension as defined in registry. 

198 

199 Returns 

200 ------- 

201 manager : `OpaqueTableStorageManager` 

202 An instance of a concrete `OpaqueTableStorageManager` subclass. 

203 """ 

204 raise NotImplementedError() 

205 

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

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

208 `None` on failure. 

209 """ 

210 r = self.get(name) 

211 if r is None: 

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

213 return r 

214 

215 @abstractmethod 

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

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

218 an opaque logical table. 

219 

220 Parameters 

221 ---------- 

222 name : `str` 

223 Name of the logical table. 

224 

225 Returns 

226 ------- 

227 records : `OpaqueTableStorage` or `None` 

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

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

230 layer. 

231 

232 Notes 

233 ----- 

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

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

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

237 obtained from an existing data repository. 

238 """ 

239 raise NotImplementedError() 

240 

241 @abstractmethod 

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

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

244 table, creating new tables as necessary. 

245 

246 Parameters 

247 ---------- 

248 name : `str` 

249 Name of the logical table. 

250 spec : `TableSpec` 

251 Schema specification for the table to be created. 

252 

253 Returns 

254 ------- 

255 records : `OpaqueTableStorage` 

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

257 layer. 

258 

259 Notes 

260 ----- 

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

262 """ 

263 raise NotImplementedError() 

264 

265 @abstractmethod 

266 def clone(self, db: Database) -> OpaqueTableStorageManager: 

267 """Make an independent copy of this manager instance bound to a new 

268 `Database` instance. 

269 

270 Parameters 

271 ---------- 

272 db : `Database` 

273 New `Database` object to use when instantiating the manager. 

274 

275 Returns 

276 ------- 

277 instance : `OpaqueTableStorageManager` 

278 New manager instance with the same configuration as this instance, 

279 but bound to a new Database object. 

280 """ 

281 raise NotImplementedError()