Coverage for src/metaclass_registry/cache.py: 84%

173 statements  

« prev     ^ index     » next       coverage.py v7.17.3, created at 2026-11-17 00:39 +0000

1""" 

2Generic caching system for plugin registries. 

3 

4Provides unified caching for both function registries (Pattern B) and 

5metaclass registries (Pattern A), eliminating code duplication and 

6ensuring consistent cache behavior across the codebase. 

7 

8Architecture: 

9- RegistryCacheManager: Generic cache manager for any registry type 

10- Supports version validation, age-based invalidation, mtime checking 

11- JSON-based serialization with custom serializers/deserializers 

12- XDG-compliant cache locations 

13 

14Usage: 

15 # For function registries 

16 cache_mgr = RegistryCacheManager( 

17 cache_name="scikit_image_functions", 

18 version_getter=lambda: skimage.__version__, 

19 serializer=serialize_function_metadata, 

20 deserializer=deserialize_function_metadata 

21 ) 

22 

23 # For metaclass registries 

24 cache_mgr = RegistryCacheManager( 

25 cache_name="microscope_handlers", 

26 version_getter=lambda: openhcs.__version__, 

27 serializer=serialize_plugin_class, 

28 deserializer=deserialize_plugin_class 

29 ) 

30""" 

31 

32import importlib 

33import json 

34import logging 

35import time 

36from collections.abc import Callable, Hashable 

37from dataclasses import dataclass 

38from enum import Enum, EnumMeta 

39from pathlib import Path 

40from typing import Any, Generic, TypeVar, cast 

41 

42from .exceptions import DiscoveryError 

43 

44logger = logging.getLogger(__name__) 

45 

46 

47def get_cache_file_path(cache_name: str, *, create: bool = True) -> Path: 

48 """ 

49 Get XDG-compliant cache file path. 

50 

51 Args: 

52 cache_name: Name of the cache file 

53 

54 Returns: 

55 Path to cache file in XDG cache directory 

56 """ 

57 # Use XDG_CACHE_HOME if set, otherwise default to ~/.cache 

58 import os 

59 

60 from . import _home 

61 

62 cache_home_value = os.environ.get("XDG_CACHE_HOME") 

63 cache_home = ( 

64 Path(cache_home_value) if cache_home_value else Path(_home.get_home_dir()) / ".cache" 

65 ) 

66 

67 # Create metaclass-registry subdirectory 

68 cache_dir = cache_home / "metaclass-registry" 

69 if create: 

70 cache_dir.mkdir(parents=True, exist_ok=True) 

71 

72 return cache_dir / cache_name 

73 

74 

75T = TypeVar("T") # Generic type for cached items 

76 

77 

78class CacheKeyCodec: 

79 """JSON-safe, reversible representation for registry keys.""" 

80 

81 PRIMITIVE_KIND = "primitive" 

82 ENUM_KIND = "enum" 

83 TUPLE_KIND = "tuple" 

84 

85 @classmethod 

86 def encode(cls, key: Any) -> dict[str, Any]: 

87 if isinstance(key, (str, int, float, bool)) or key is None: 

88 return {"kind": cls.PRIMITIVE_KIND, "value": key} 

89 if isinstance(key, Enum): 

90 return { 

91 "kind": cls.ENUM_KIND, 

92 "module": key.__class__.__module__, 

93 "class_name": key.__class__.__name__, 

94 "member_name": key.name, 

95 } 

96 if isinstance(key, tuple): 

97 return { 

98 "kind": cls.TUPLE_KIND, 

99 "items": [cls.encode(item) for item in key], 

100 } 

101 raise TypeError(f"Unsupported registry cache key type: {type(key)!r}") 

102 

103 @classmethod 

104 def decode(cls, payload: dict[str, Any]) -> Hashable: 

105 kind = payload["kind"] 

106 try: 

107 decoder = CACHE_KEY_DECODERS[kind] 

108 except KeyError as exc: 

109 raise ValueError(f"Unsupported registry cache key kind: {kind!r}") from exc 

110 return decoder(payload) 

111 

112 

113def _decode_primitive_cache_key(payload: dict[str, Any]) -> Hashable: 

114 value = payload["value"] 

115 if not isinstance(value, Hashable): 

116 raise TypeError(f"Cached primitive key {value!r} is not hashable") 

117 return value 

118 

119 

120def _decode_enum_cache_key(payload: dict[str, Any]) -> Enum: 

121 import importlib 

122 

123 enum_module = importlib.import_module(payload["module"]) 

124 enum_type = vars(enum_module)[payload["class_name"]] 

125 if not isinstance(enum_type, EnumMeta): 

126 raise TypeError(f"Cached enum owner {enum_type!r} is not an Enum type") 

127 return enum_type[payload["member_name"]] 

128 

129 

130def _decode_tuple_cache_key(payload: dict[str, Any]) -> tuple[Any, ...]: 

131 return tuple(CacheKeyCodec.decode(item) for item in payload["items"]) 

132 

133 

134CACHE_KEY_DECODERS: dict[str, Callable[[dict[str, Any]], Hashable]] = { 

135 CacheKeyCodec.PRIMITIVE_KIND: _decode_primitive_cache_key, 

136 CacheKeyCodec.ENUM_KIND: _decode_enum_cache_key, 

137 CacheKeyCodec.TUPLE_KIND: _decode_tuple_cache_key, 

138} 

139 

140 

141@dataclass 

142class CacheConfig: 

143 """Configuration for registry caching behavior.""" 

144 

145 max_age_days: int = 7 # Maximum cache age before invalidation 

146 check_mtimes: bool = False # Check file modification times 

147 cache_version: str = "1.0" # Cache format version 

148 

149 

150class RegistryCacheManager(Generic[T]): 

151 """ 

152 Generic cache manager for plugin registries. 

153 

154 Handles caching, validation, and reconstruction of registry data 

155 with support for version checking, age-based invalidation, and 

156 custom serialization. 

157 

158 Type Parameters: 

159 T: Type of items being cached (e.g., FunctionMetadata, Type[Plugin]) 

160 """ 

161 

162 def __init__( 

163 self, 

164 cache_name: str, 

165 version_getter: Callable[[], str], 

166 serializer: Callable[[T], dict[str, Any]], 

167 deserializer: Callable[[dict[str, Any]], T], 

168 config: CacheConfig | None = None, 

169 file_mtimes_getter: Callable[[], dict[str, float]] | None = None, 

170 ): 

171 """ 

172 Initialize cache manager. 

173 

174 Args: 

175 cache_name: Name for the cache file (e.g., "microscope_handlers") 

176 version_getter: Function that returns current version string 

177 serializer: Function to serialize item to JSON-compatible dict 

178 deserializer: Function to deserialize dict back to item 

179 config: Optional cache configuration 

180 file_mtimes_getter: Optional authoritative inventory of source files used by 

181 discovery. When provided, added files invalidate the cache as well as 

182 modified and removed files. 

183 """ 

184 self.cache_name = cache_name 

185 self.version_getter = version_getter 

186 self.serializer = serializer 

187 self.deserializer = deserializer 

188 self.config = config or CacheConfig() 

189 self.file_mtimes_getter = file_mtimes_getter 

190 self._cache_path = get_cache_file_path(f"{cache_name}.json") 

191 

192 def load_cache(self) -> dict[Hashable, T] | None: 

193 """ 

194 Load cached items with validation. 

195 

196 Returns: 

197 Dictionary of cached items, or None if cache is invalid 

198 """ 

199 if not self._cache_path.exists(): 

200 logger.debug(f"No cache found for {self.cache_name}") 

201 return None 

202 

203 try: 

204 with open(self._cache_path) as f: 

205 cache_data = json.load(f) 

206 except json.JSONDecodeError: 

207 logger.warning(f"Corrupt cache file {self._cache_path}, rebuilding") 

208 self._cache_path.unlink(missing_ok=True) 

209 return None 

210 

211 # Validate cache version 

212 if cache_data.get("cache_version") != self.config.cache_version: 

213 logger.debug(f"Cache version mismatch for {self.cache_name}") 

214 return None 

215 

216 # Validate library/package version 

217 cached_version = cache_data.get("version", "unknown") 

218 current_version = self.version_getter() 

219 if cached_version != current_version: 

220 logger.info( 

221 f"{self.cache_name} version changed " 

222 f"({cached_version} → {current_version}) - cache invalid" 

223 ) 

224 return None 

225 

226 # Validate cache age 

227 cache_timestamp = cache_data.get("timestamp", 0) 

228 cache_age_days = (time.time() - cache_timestamp) / (24 * 3600) 

229 if cache_age_days > self.config.max_age_days: 

230 logger.debug( 

231 f"Cache for {self.cache_name} is {cache_age_days:.1f} days old - rebuilding" 

232 ) 

233 return None 

234 

235 # Validate file mtimes if configured 

236 if self.config.check_mtimes and "file_mtimes" in cache_data: 

237 current_mtimes = ( 

238 self.file_mtimes_getter() if self.file_mtimes_getter is not None else None 

239 ) 

240 if not self._validate_mtimes( 

241 cache_data["file_mtimes"], 

242 current_mtimes=current_mtimes, 

243 ): 

244 logger.debug(f"File modifications detected for {self.cache_name}") 

245 return None 

246 

247 # Deserialize items 

248 items: dict[Hashable, T] = {} 

249 item_entries = cache_data.get("item_entries") 

250 if item_entries is None: 

251 item_entries = [ 

252 {"key": CacheKeyCodec.encode(key), "item": item_data} 

253 for key, item_data in cache_data.get("items", {}).items() 

254 ] 

255 for entry in item_entries: 

256 key = CacheKeyCodec.decode(entry["key"]) 

257 item_data = entry["item"] 

258 try: 

259 items[key] = self.deserializer(item_data) 

260 except Exception as e: 

261 logger.warning(f"Failed to deserialize {key} from cache: {e}") 

262 return None # Invalidate entire cache on any deserialization error 

263 

264 logger.debug(f"✅ Loaded {len(items)} items from {self.cache_name} cache") 

265 return items 

266 

267 def save_cache( 

268 self, 

269 items: dict[Hashable, T], 

270 file_mtimes: dict[str, float] | None = None, 

271 ) -> None: 

272 """ 

273 Save items to cache. 

274 

275 Args: 

276 items: Dictionary of items to cache 

277 file_mtimes: Optional dict of file paths to modification times 

278 """ 

279 cache_data: dict[str, Any] = { 

280 "cache_version": self.config.cache_version, 

281 "version": self.version_getter(), 

282 "timestamp": time.time(), 

283 "item_entries": [], 

284 } 

285 

286 # Add file mtimes if provided 

287 if file_mtimes: 

288 cache_data["file_mtimes"] = file_mtimes 

289 

290 # Serialize items 

291 for key, item in items.items(): 

292 try: 

293 cache_data["item_entries"].append( 

294 { 

295 "key": CacheKeyCodec.encode(key), 

296 "item": self.serializer(item), 

297 } 

298 ) 

299 except Exception as e: 

300 logger.warning(f"Failed to serialize {key} for cache: {e}") 

301 

302 # Save to disk 

303 try: 

304 self._cache_path.parent.mkdir(parents=True, exist_ok=True) 

305 with open(self._cache_path, "w") as f: 

306 json.dump(cache_data, f, indent=2) 

307 logger.debug(f"💾 Saved {len(items)} items to {self.cache_name} cache") 

308 except Exception as e: 

309 logger.warning(f"Failed to save {self.cache_name} cache: {e}") 

310 

311 def clear_cache(self) -> None: 

312 """Clear the cache file.""" 

313 if self._cache_path.exists(): 

314 self._cache_path.unlink() 

315 logger.info(f"🧹 Cleared {self.cache_name} cache") 

316 

317 def _validate_mtimes( 

318 self, 

319 cached_mtimes: dict[str, float], 

320 *, 

321 current_mtimes: dict[str, float] | None = None, 

322 ) -> bool: 

323 """ 

324 Validate that file modification times haven't changed. 

325 

326 Args: 

327 cached_mtimes: Dictionary of file paths to cached mtimes 

328 current_mtimes: Optional complete current inventory. When present, its paths 

329 must exactly match the cached discovery inventory. 

330 

331 Returns: 

332 True if all mtimes match, False if any file changed 

333 """ 

334 if current_mtimes is not None and current_mtimes.keys() != cached_mtimes.keys(): 

335 return False 

336 

337 for file_path, cached_mtime in cached_mtimes.items(): 

338 path = Path(file_path) 

339 if not path.exists(): 

340 return False # File was deleted 

341 

342 current_mtime = ( 

343 current_mtimes[file_path] if current_mtimes is not None else path.stat().st_mtime 

344 ) 

345 if abs(current_mtime - cached_mtime) > 1.0: # 1 second tolerance 

346 return False # File was modified 

347 

348 return True 

349 

350 

351# Serializers for metaclass registries (Pattern A) 

352 

353 

354def serialize_plugin_class(plugin_class: type) -> dict[str, Any]: 

355 """ 

356 Serialize a plugin class to JSON-compatible dict. 

357 

358 Args: 

359 plugin_class: Plugin class to serialize 

360 

361 Returns: 

362 Dictionary with module and class name 

363 """ 

364 return { 

365 "module": plugin_class.__module__, 

366 "class_name": plugin_class.__name__, 

367 "qualname": plugin_class.__qualname__, 

368 } 

369 

370 

371def deserialize_plugin_class(data: dict[str, Any]) -> type: 

372 """ 

373 Deserialize a plugin class from JSON-compatible dict. 

374 

375 Args: 

376 data: Dictionary with module and class name 

377 

378 Returns: 

379 Reconstructed plugin class 

380 

381 Raises: 

382 ImportError: If module cannot be imported 

383 AttributeError: If class not found in module 

384 """ 

385 declaration: Any = importlib.import_module(data["module"]) 

386 for owner_name in data["qualname"].split("."): 

387 if owner_name == "<locals>": 

388 raise AttributeError("Function-local classes cannot be restored from a registry cache") 

389 declaration = getattr(declaration, owner_name) 

390 if not isinstance(declaration, type): 

391 raise TypeError(f"Cached plugin declaration {data['qualname']!r} is not a class") 

392 return declaration 

393 

394 

395def get_package_file_mtimes( 

396 package_path: str, 

397 *, 

398 recursive: bool = True, 

399) -> dict[str, float]: 

400 """ 

401 Get source modification times for a declared module or package. 

402 

403 Args: 

404 package_path: Package path (e.g., "openhcs.microscopes") 

405 recursive: Whether nested package files participate in discovery. 

406 

407 Returns: 

408 Dictionary mapping file paths to modification times 

409 """ 

410 module = importlib.import_module(package_path) 

411 spec = module.__spec__ 

412 if spec is None: 

413 raise DiscoveryError(f"Discovery scope has no module spec: {module.__name__}") 

414 if spec.submodule_search_locations is None: 

415 if not spec.has_location: 

416 return {} 

417 source = Path(cast(str, spec.origin)) 

418 return {str(source): source.stat().st_mtime} 

419 

420 mtimes = {} 

421 for location in spec.submodule_search_locations: 

422 package_dir = Path(location) 

423 source_files = package_dir.rglob("*.py") if recursive else package_dir.glob("*.py") 

424 for py_file in source_files: 

425 mtimes[str(py_file)] = py_file.stat().st_mtime 

426 return mtimes