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
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-17 00:39 +0000
1"""
2Generic caching system for plugin registries.
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.
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
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 )
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"""
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
42from .exceptions import DiscoveryError
44logger = logging.getLogger(__name__)
47def get_cache_file_path(cache_name: str, *, create: bool = True) -> Path:
48 """
49 Get XDG-compliant cache file path.
51 Args:
52 cache_name: Name of the cache file
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
60 from . import _home
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 )
67 # Create metaclass-registry subdirectory
68 cache_dir = cache_home / "metaclass-registry"
69 if create:
70 cache_dir.mkdir(parents=True, exist_ok=True)
72 return cache_dir / cache_name
75T = TypeVar("T") # Generic type for cached items
78class CacheKeyCodec:
79 """JSON-safe, reversible representation for registry keys."""
81 PRIMITIVE_KIND = "primitive"
82 ENUM_KIND = "enum"
83 TUPLE_KIND = "tuple"
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}")
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)
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
120def _decode_enum_cache_key(payload: dict[str, Any]) -> Enum:
121 import importlib
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"]]
130def _decode_tuple_cache_key(payload: dict[str, Any]) -> tuple[Any, ...]:
131 return tuple(CacheKeyCodec.decode(item) for item in payload["items"])
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}
141@dataclass
142class CacheConfig:
143 """Configuration for registry caching behavior."""
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
150class RegistryCacheManager(Generic[T]):
151 """
152 Generic cache manager for plugin registries.
154 Handles caching, validation, and reconstruction of registry data
155 with support for version checking, age-based invalidation, and
156 custom serialization.
158 Type Parameters:
159 T: Type of items being cached (e.g., FunctionMetadata, Type[Plugin])
160 """
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.
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")
192 def load_cache(self) -> dict[Hashable, T] | None:
193 """
194 Load cached items with validation.
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
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
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
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
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
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
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
264 logger.debug(f"✅ Loaded {len(items)} items from {self.cache_name} cache")
265 return items
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.
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 }
286 # Add file mtimes if provided
287 if file_mtimes:
288 cache_data["file_mtimes"] = file_mtimes
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}")
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}")
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")
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.
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.
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
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
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
348 return True
351# Serializers for metaclass registries (Pattern A)
354def serialize_plugin_class(plugin_class: type) -> dict[str, Any]:
355 """
356 Serialize a plugin class to JSON-compatible dict.
358 Args:
359 plugin_class: Plugin class to serialize
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 }
371def deserialize_plugin_class(data: dict[str, Any]) -> type:
372 """
373 Deserialize a plugin class from JSON-compatible dict.
375 Args:
376 data: Dictionary with module and class name
378 Returns:
379 Reconstructed plugin class
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
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.
403 Args:
404 package_path: Package path (e.g., "openhcs.microscopes")
405 recursive: Whether nested package files participate in discovery.
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}
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