Coverage for src/metaclass_registry/core.py: 83%

457 statements  

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

1""" 

2Generic metaclass infrastructure for automatic plugin registration. 

3 

4This module provides reusable metaclass infrastructure for Pattern A registry systems 

5(1:1 class-to-plugin mapping with automatic discovery). It eliminates code duplication 

6across MicroscopeHandlerMeta, StorageBackendMeta, and ContextProviderMeta. 

7 

8Pattern Selection Guide: 

9----------------------- 

10Use AutoRegisterMeta (Pattern A) when: 

11- You have a 1:1 mapping between classes and plugins 

12- Plugins should be automatically discovered and registered 

13- Registration happens at class definition time 

14- Simple metadata (just a key and maybe one secondary registry) 

15 

16Use Service Pattern (Pattern B) when: 

17- You have many-to-one mapping (multiple items per plugin) 

18- Complex metadata (FunctionMetadata with 8+ fields) 

19- Need aggregation across multiple sources 

20- Examples: Function registry, Format registry 

21 

22Use Functional Registry (Pattern C) when: 

23- Simple type-to-handler mappings 

24- No state needed 

25- Functional programming style preferred 

26- Examples: Widget creation registries 

27 

28Use Manual Registration (Pattern D) when: 

29- Complex initialization logic required 

30- Explicit control over registration timing needed 

31- Very few plugins (< 3) 

32- Examples: ZMQ servers, Pipeline steps 

33 

34Architecture: 

35------------ 

36AutoRegisterMeta uses a configuration-driven approach: 

371. RegistryConfig defines registration behavior 

382. The nominal registry root owns that configuration as ``__registry_config__`` 

393. AutoRegisterMeta applies the configuration during class creation 

40 

41This keeps domain semantics on their nominal owner while eliminating duplicated 

42metaclass wrappers and caller-side discovery inference. 

43""" 

44 

45import logging 

46import threading 

47from abc import ABCMeta 

48from collections.abc import Callable, Hashable, Iterable, Iterator 

49from contextlib import ExitStack 

50from dataclasses import dataclass 

51from enum import Enum, EnumMeta 

52from typing import Any, cast 

53 

54from .cache import ( 

55 CacheConfig, 

56 RegistryCacheManager, 

57 deserialize_plugin_class, 

58 get_package_file_mtimes, 

59 serialize_plugin_class, 

60) 

61from .discovery import ( 

62 discover_registry_classes, 

63 discover_registry_classes_recursive, 

64 import_module_preserving_root_logging, 

65) 

66from .exceptions import DiscoveryError, DuplicateRegistryKeyError 

67 

68logger = logging.getLogger(__name__) 

69 

70# Type aliases for clarity 

71RegistryKey = Hashable 

72RegistryDict = dict[RegistryKey, Any] 

73KeyExtractor = Callable[[str, type], RegistryKey] 

74 

75# Constants for key sources 

76PRIMARY_KEY = "primary" 

77 

78# Declared in a class body: the registered class this class takes the key from. 

79REPLACES_REGISTERED_ATTRIBUTE = "__replaces_registered__" 

80 

81# Set on a class whose key came from the family's key extractor, so that a 

82# subclass derives its own key instead of inheriting the stamped one. 

83_DERIVED_KEY_MARKER = "__registry_key_derived__" 

84 

85# Set on a class when it registers. A class rebuilt from a copy of the 

86# registered class's namespace (``dataclass(slots=True)`` does this) carries 

87# the same token in its own namespace; a subclass or an unrelated class does not. 

88_DECLARATION_TOKEN = "__registry_declaration__" 

89 

90_ABSENT: Any = object() 

91 

92 

93def _describe(value: object) -> str: 

94 """Name a registered value by module and qualified name when it has them.""" 

95 module = getattr(value, "__module__", None) 

96 qualname = getattr(value, "__qualname__", None) 

97 if module is None or qualname is None: 

98 return repr(value) 

99 return f"{module}.{qualname}" 

100 

101 

102def is_same_declaration(registered: object, candidate: object) -> bool: 

103 """Whether two class objects come from one class statement. 

104 

105 ``importlib.reload``, a re-import and a second run of the same function 

106 body build a new class object for a declaration that already registered: 

107 the module and qualified name are the declaration's identity, the object 

108 is not. ``dataclass(slots=True)`` rebuilds the class by calling the 

109 metaclass with a copy of its namespace, before the qualified name is 

110 restored: that class has the same module and name and carries the 

111 registered class's declaration token in its own namespace. 

112 """ 

113 if not isinstance(registered, type) or not isinstance(candidate, type): 

114 return False 

115 if registered.__module__ != candidate.__module__: 

116 return False 

117 if registered.__qualname__ == candidate.__qualname__: 

118 return True 

119 token = vars(registered).get(_DECLARATION_TOKEN) 

120 return ( 

121 token is not None 

122 and vars(candidate).get(_DECLARATION_TOKEN) is token 

123 and registered.__name__ == candidate.__name__ 

124 ) 

125 

126 

127def register_once( 

128 registry_dict: "RegistryDict", 

129 key: RegistryKey, 

130 value: Any, 

131 *, 

132 registry_name: str, 

133 replaces: object = None, 

134 superseded_values: tuple[object, ...] = (), 

135) -> Any: 

136 """Store ``value`` under ``key``; a key never silently changes hands. 

137 

138 Returns the value that ``value`` took the key from, or ``None``. 

139 

140 - The same object again is a no-op. 

141 - A class from the same declaration (see ``is_same_declaration``) takes 

142 the key from its earlier object. 

143 - ``replaces`` names the registered value this one is declared to take 

144 the key from; the key must hold exactly that value. 

145 - ``superseded_values`` are values registered by a class that the 

146 registering class has just taken over from (secondary registries). 

147 - Anything else raises ``DuplicateRegistryKeyError``. 

148 """ 

149 existing = dict.get(registry_dict, key, _ABSENT) 

150 if existing is value: 

151 return None 

152 if existing is _ABSENT: 

153 if replaces is not None: 

154 raise DuplicateRegistryKeyError( 

155 f"{_describe(value)} declares {REPLACES_REGISTERED_ATTRIBUTE} = " 

156 f"{_describe(replaces)}, but {registry_name} key {key!r} is not registered." 

157 ) 

158 registry_dict[key] = value 

159 return None 

160 if ( 

161 is_same_declaration(existing, value) 

162 or existing is replaces 

163 or any(existing is superseded for superseded in superseded_values) 

164 ): 

165 registry_dict[key] = value 

166 return existing 

167 if replaces is not None: 

168 raise DuplicateRegistryKeyError( 

169 f"{_describe(value)} declares {REPLACES_REGISTERED_ATTRIBUTE} = " 

170 f"{_describe(replaces)}, but {registry_name} key {key!r} is registered to " 

171 f"{_describe(existing)}." 

172 ) 

173 raise DuplicateRegistryKeyError( 

174 f"{registry_name} key {key!r} is already registered to {_describe(existing)}; " 

175 f"{_describe(value)} cannot register under the same key. Give it its own key, or " 

176 f"declare {REPLACES_REGISTERED_ATTRIBUTE} = {getattr(existing, '__name__', 'TheOther')} " 

177 f"in its class body if it is meant to take the key over." 

178 ) 

179 

180 

181class RegistryKeyAttribute(str, Enum): 

182 """Common class-attribute names used as registry keys.""" 

183 

184 REGISTRY_KEY = "registry_key" 

185 STRATEGY_KEY = "strategy_key" 

186 STRATEGY_LABEL = "strategy_label" 

187 VALUE_TYPE_LABEL = "value_type_label" 

188 LAYOUT_KEY = "layout_key" 

189 

190 

191class SecondaryRegistryDict(dict[RegistryKey, Any]): 

192 """ 

193 Dict for secondary registries that auto-triggers primary registry discovery. 

194 

195 When accessed, this dict triggers discovery of the primary registry, 

196 which populates both the primary and secondary registries. 

197 """ 

198 

199 def __init__(self, primary_registry: "LazyDiscoveryDict") -> None: 

200 super().__init__() 

201 self._primary_registry = primary_registry 

202 

203 def _ensure_discovered(self) -> None: 

204 """Trigger discovery of primary registry (which populates this secondary registry).""" 

205 if hasattr(self._primary_registry, "_discover"): 

206 self._primary_registry._discover() 

207 

208 def __getitem__(self, key: RegistryKey) -> Any: 

209 self._ensure_discovered() 

210 return super().__getitem__(key) 

211 

212 def __contains__(self, key: object) -> bool: 

213 self._ensure_discovered() 

214 return super().__contains__(key) 

215 

216 def __iter__(self) -> Iterator[RegistryKey]: 

217 self._ensure_discovered() 

218 return super().__iter__() 

219 

220 def __len__(self) -> int: 

221 self._ensure_discovered() 

222 return super().__len__() 

223 

224 def keys(self) -> Any: 

225 self._ensure_discovered() 

226 return super().keys() 

227 

228 def values(self) -> Any: 

229 self._ensure_discovered() 

230 return super().values() 

231 

232 def items(self) -> Any: 

233 self._ensure_discovered() 

234 return super().items() 

235 

236 def get(self, key: RegistryKey, default: Any = None) -> Any: 

237 self._ensure_discovered() 

238 return super().get(key, default) 

239 

240 

241class LazyDiscoveryDict(dict[RegistryKey, Any]): 

242 """ 

243 Dict that auto-discovers plugins on first access with optional caching. 

244 

245 Supports caching discovered plugins to speed up subsequent application starts. 

246 Cache is validated against package version and file modification times. 

247 

248 Thread-safe: Uses locking to ensure discovery happens only once 

249 even when accessed from multiple threads simultaneously. 

250 """ 

251 

252 def __init__(self, enable_cache: bool = True) -> None: 

253 """ 

254 Initialize lazy discovery dict. 

255 

256 Args: 

257 enable_cache: If True, use caching to speed up discovery 

258 """ 

259 super().__init__() 

260 self._base_class: type | None = None 

261 self._config: RegistryConfig | None = None 

262 self._discovered = False 

263 self._enable_cache = enable_cache 

264 self._cache_manager: RegistryCacheManager[type] | None = None 

265 self._discovery_lock = threading.RLock() # Reentrant lock for same-thread re-entry 

266 self._discovery_package: str | None = None # Store for pickling support 

267 

268 def _set_config(self, base_class: type, config: "RegistryConfig") -> None: 

269 self._base_class = base_class 

270 self._config = config 

271 self._discovery_package = config.discovery_package # Store for pickling support 

272 

273 # Initialize cache manager if caching is enabled 

274 if self._enable_cache and config.discovery_package: 

275 try: 

276 self._cache_manager = RegistryCacheManager( 

277 cache_name=f"{config.registry_name.replace(' ', '_')}_registry", 

278 version_getter=self._get_version, 

279 serializer=serialize_plugin_class, 

280 deserializer=deserialize_plugin_class, 

281 config=CacheConfig( 

282 max_age_days=7, check_mtimes=True # Validate file modifications 

283 ), 

284 file_mtimes_getter=self._get_discovery_file_mtimes, 

285 ) 

286 except Exception as e: 

287 logger.debug(f"Failed to initialize cache manager: {e}") 

288 self._cache_manager = None 

289 

290 def _get_version(self) -> str: 

291 """ 

292 Get version from the discovery package for cache validation. 

293 

294 Returns: 

295 Version string or 'unknown' if unable to determine 

296 """ 

297 try: 

298 # Try to get version from the root package 

299 if self._discovery_package: 

300 root_package = self._discovery_package.split(".")[0] 

301 mod = __import__(root_package) 

302 return getattr(mod, "__version__", "unknown") 

303 except Exception: 

304 return "unknown" 

305 return "unknown" 

306 

307 def _get_discovery_file_mtimes(self) -> dict[str, float]: 

308 """Return the complete source inventory for this discovery package.""" 

309 

310 if not self._discovery_package or self._config is None: 

311 return {} 

312 return get_package_file_mtimes( 

313 self._discovery_package, 

314 recursive=self._config.discovery_recursive, 

315 ) 

316 

317 def _has_discovery_configuration(self) -> bool: 

318 """Own the shared configuration/root admission for both discovery scopes.""" 

319 if not self._config or not self._config.discovery_package: 

320 return False 

321 if self._base_class is None: 

322 raise RuntimeError("Discovery configuration has no nominal registry root") 

323 return True 

324 

325 def _scope_paths(self) -> Iterable[str] | None: 

326 """Import the declared scope; a plain module has no child modules to scan.""" 

327 config = cast(RegistryConfig, self._config) 

328 module = import_module_preserving_root_logging(cast(str, config.discovery_package)) 

329 spec = module.__spec__ 

330 if spec is None: 

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

332 return spec.submodule_search_locations 

333 

334 def _discovery_failed(self) -> None: 

335 self._discovered = False 

336 

337 def _discover(self) -> None: 

338 """Build members once under the registry lock; failed builds remain incomplete.""" 

339 if not self._has_discovery_configuration(): 

340 return 

341 with self._discovery_lock: 

342 if self._discovered: 

343 return 

344 with ExitStack() as failure: 

345 failure.callback(self._discovery_failed) 

346 # Same-thread imports may read the registry while declarations register. 

347 self._discovered = True 

348 config = cast(RegistryConfig, self._config) 

349 if self._cache_manager: 

350 cached_plugins = self._cache_manager.load_cache() 

351 if cached_plugins is not None: 

352 for key, plugin in cached_plugins.items(): 

353 register_once(self, key, plugin, registry_name=config.registry_name) 

354 failure.pop_all() 

355 return 

356 

357 paths = self._scope_paths() 

358 if paths is not None: 

359 discover = config.discovery_function or ( 

360 discover_registry_classes_recursive 

361 if config.discovery_recursive 

362 else discover_registry_classes 

363 ) 

364 discover(paths, f"{config.discovery_package}.", cast(type, self._base_class)) 

365 if self._cache_manager: 

366 self._cache_manager.save_cache(dict(self), self._get_discovery_file_mtimes()) 

367 failure.pop_all() 

368 

369 def discover_matching(self, module_filter: Callable[[str], bool]) -> None: 

370 """Admit selected modules through the original discovery/import owner. 

371 

372 Selection is not full discovery and never publishes a complete cache. 

373 Domain declarations supply eligibility; their ordinary metaclass still 

374 owns registration. Selected import errors propagate rather than turning 

375 an incomplete selection into apparent absence. 

376 """ 

377 if not self._has_discovery_configuration(): 

378 return 

379 config = cast(RegistryConfig, self._config) 

380 if config.discovery_recursive or config.discovery_function: 

381 raise ValueError("Selected discovery requires the flat discovery owner") 

382 with self._discovery_lock: 

383 if self._discovered: 

384 return 

385 paths = self._scope_paths() 

386 if paths is None: 

387 return 

388 discover_registry_classes( 

389 paths, 

390 f"{config.discovery_package}.", 

391 cast(type, self._base_class), 

392 module_filter=module_filter, 

393 ) 

394 

395 def __getitem__(self, key: RegistryKey) -> Any: 

396 with self._discovery_lock: 

397 self._discover() 

398 return super().__getitem__(key) 

399 

400 def __contains__(self, key: object) -> bool: 

401 with self._discovery_lock: 

402 self._discover() 

403 return super().__contains__(key) 

404 

405 def __iter__(self) -> Iterator[RegistryKey]: 

406 with self._discovery_lock: 

407 self._discover() 

408 return super().__iter__() 

409 

410 def __len__(self) -> int: 

411 with self._discovery_lock: 

412 self._discover() 

413 return super().__len__() 

414 

415 def keys(self) -> Any: 

416 with self._discovery_lock: 

417 self._discover() 

418 return super().keys() 

419 

420 def values(self) -> Any: 

421 with self._discovery_lock: 

422 self._discover() 

423 return super().values() 

424 

425 def items(self) -> Any: 

426 with self._discovery_lock: 

427 self._discover() 

428 return super().items() 

429 

430 def get(self, key: RegistryKey, default: Any = None) -> Any: 

431 with self._discovery_lock: 

432 self._discover() 

433 return super().get(key, default) 

434 

435 def __getstate__(self) -> dict[RegistryKey, Any]: 

436 """ 

437 Return state for pickling, excluding non-picklable objects. 

438 

439 The _discovery_lock and _cache_manager are excluded since they contain 

440 non-picklable objects (RLock and potentially closures). 

441 """ 

442 state = dict(self) # Copy the dict contents 

443 state.update( 

444 { 

445 "_base_class": self._base_class, 

446 "_config": self._config, 

447 "_discovered": self._discovered, 

448 "_enable_cache": self._enable_cache, 

449 "_discovery_package": self._discovery_package, 

450 # Exclude: _discovery_lock, _cache_manager 

451 } 

452 ) 

453 return state 

454 

455 def __setstate__(self, state: dict[RegistryKey, Any]) -> None: 

456 """ 

457 Restore state from pickle, recreating non-picklable objects. 

458 

459 The _discovery_lock is recreated as a new RLock. 

460 The _cache_manager is set to None and will be reinitialized if needed. 

461 """ 

462 # Restore dict contents 

463 for key, value in state.items(): 

464 if isinstance(key, str) and key.startswith("_"): 

465 setattr(self, key, value) 

466 else: 

467 self[key] = value 

468 # Recreate non-picklable objects 

469 self._discovery_lock = threading.RLock() 

470 self._cache_manager = None # Will be reinitialized if needed 

471 

472 

473@dataclass(frozen=True) 

474class SecondaryRegistry: 

475 """Configuration for a secondary registry (e.g., metadata handlers).""" 

476 

477 registry_dict: RegistryDict 

478 key_source: str # 'primary' or attribute name 

479 attr_name: str # Attribute to check on the class 

480 

481 

482@dataclass(frozen=True) 

483class RegistryFamily: 

484 """Declarative registry-family configuration for ``AutoRegisterMeta`` roots. 

485 

486 ``AutoRegisterMeta`` historically used low-level class attributes such as 

487 ``__registry_key__`` and ``__skip_if_no_key__``. Those attributes remain 

488 the compatibility surface, but registry roots can now declare one nominal 

489 family object and let the metaclass install the legacy attributes. 

490 """ 

491 

492 key_attribute: str | RegistryKeyAttribute 

493 skip_if_no_key: bool = True 

494 registry_name: str | None = None 

495 

496 @property 

497 def key_attribute_name(self) -> str: 

498 """Return the string attribute name consumed by ``AutoRegisterMeta``.""" 

499 if isinstance(self.key_attribute, RegistryKeyAttribute): 

500 return self.key_attribute.value 

501 return self.key_attribute 

502 

503 def apply_to_class(self, cls: type, explicit_attrs: dict) -> None: 

504 """Install legacy metaclass attributes for compatibility/introspection.""" 

505 if "__registry_key__" not in explicit_attrs: 

506 setattr(cls, "__registry_key__", self.key_attribute_name) 

507 if "__skip_if_no_key__" not in explicit_attrs: 

508 setattr(cls, "__skip_if_no_key__", self.skip_if_no_key) 

509 if self.registry_name is not None and "__registry_name__" not in explicit_attrs: 

510 setattr(cls, "__registry_name__", self.registry_name) 

511 

512 

513@dataclass(frozen=True) 

514class RegistryConfig: 

515 """ 

516 Configuration for automatic class registration behavior. 

517 

518 This dataclass encapsulates all the configuration needed for metaclass 

519 registration, making the pattern explicit and easy to understand. 

520 

521 Attributes: 

522 registry_dict: Dictionary to register classes into (e.g., MICROSCOPE_HANDLERS) 

523 key_attribute: Name of class attribute containing the registration key 

524 (e.g., '_microscope_type', '_backend_type', '_context_type') 

525 key_extractor: Optional function to derive key from class name if key_attribute 

526 is not set. Signature: (class_name: str, cls: Type) -> str 

527 skip_if_no_key: If True, skip registration when key_attribute is None. 

528 If False, require either key_attribute or key_extractor. 

529 secondary_registries: Optional list of secondary registry configurations 

530 log_registration: If True, log debug message when class is registered 

531 registry_name: Human-readable name for logging (e.g., 'microscope handler') 

532 discovery_package: Explicit package name to auto-discover (e.g., 

533 'openhcs.microscopes'). ``None`` keeps registration local to 

534 declarations imported by the application. 

535 discovery_recursive: If True, use recursive discovery (default: False) 

536 

537 Examples: 

538 # Microscope handlers with name-based key extraction and secondary registry 

539 RegistryConfig( 

540 registry_dict=MICROSCOPE_HANDLERS, 

541 key_attribute='_microscope_type', 

542 key_extractor=extract_key_from_handler_suffix, 

543 skip_if_no_key=False, 

544 secondary_registries=[ 

545 SecondaryRegistry( 

546 registry_dict=METADATA_HANDLERS, 

547 key_source=PRIMARY_KEY, 

548 attr_name='_metadata_handler_class' 

549 ) 

550 ], 

551 log_registration=True, 

552 registry_name='microscope handler' 

553 ) 

554 

555 # Storage backends with explicit key and skip-if-none behavior 

556 RegistryConfig( 

557 registry_dict=STORAGE_BACKENDS, 

558 key_attribute='_backend_type', 

559 skip_if_no_key=True, 

560 registry_name='storage backend' 

561 ) 

562 

563 # Context providers with simple explicit key 

564 RegistryConfig( 

565 registry_dict=CONTEXT_PROVIDERS, 

566 key_attribute='_context_type', 

567 skip_if_no_key=True, 

568 registry_name='context provider' 

569 ) 

570 """ 

571 

572 registry_dict: RegistryDict 

573 key_attribute: str 

574 key_extractor: KeyExtractor | None = None 

575 skip_if_no_key: bool = False 

576 secondary_registries: list[SecondaryRegistry] | None = None 

577 log_registration: bool = True 

578 registry_name: str = "plugin" 

579 discovery_package: str | None = None 

580 discovery_recursive: bool = False 

581 discovery_function: Callable[..., Any] | None = None # Custom discovery function 

582 

583 

584class AutoRegisterMeta(ABCMeta): 

585 """ 

586 Generic metaclass for automatic plugin registration (Pattern A). 

587 

588 This metaclass automatically registers concrete classes in a global registry 

589 when they are defined, eliminating the need for manual registration calls. 

590 

591 Features: 

592 - Skips abstract classes (checks __abstractmethods__) 

593 - Supports explicit keys via class attributes 

594 - Supports derived keys via key extraction functions 

595 - Supports secondary registries (e.g., metadata handlers) 

596 - Configurable skip-if-no-key behavior 

597 - Debug logging for registration events 

598 

599 Usage: 

600 # Create domain-specific metaclass 

601 class MicroscopeHandlerMeta(AutoRegisterMeta): 

602 def __new__(mcs, name, bases, attrs): 

603 return super().__new__(mcs, name, bases, attrs, 

604 registry_config=_MICROSCOPE_REGISTRY_CONFIG) 

605 

606 # Use in class definition 

607 class ImageXpressHandler(MicroscopeHandler, metaclass=MicroscopeHandlerMeta): 

608 _microscope_type = 'imagexpress' # Optional if key_extractor is provided 

609 _metadata_handler_class = ImageXpressMetadata # Optional secondary registration 

610 

611 Design Principles: 

612 - Explicit configuration over magic behavior 

613 - Preserve all domain-specific features 

614 - Zero breaking changes to existing code 

615 - Easy to understand and debug 

616 """ 

617 

618 def __new__( 

619 mcs: type["AutoRegisterMeta"], 

620 name: str, 

621 bases: tuple[type, ...], 

622 attrs: dict[str, Any], 

623 registry_config: RegistryConfig | None = None, 

624 **class_kwargs: Any, 

625 ) -> type: 

626 """ 

627 Create a new class and register it if appropriate. 

628 

629 Args: 

630 name: Name of the class being created 

631 bases: Base classes 

632 attrs: Class attributes dictionary 

633 registry_config: Configuration for registration behavior. 

634 If None, auto-configures from class attributes or skips registration. 

635 class_kwargs: Class keywords, passed on to ``__init_subclass__``. 

636 

637 Returns: 

638 The newly created class 

639 """ 

640 registry_family = attrs.get("__registry_family__") 

641 declared_registry_config = attrs.get("__registry_config__") 

642 if declared_registry_config is not None: 

643 if not isinstance(declared_registry_config, RegistryConfig): 

644 raise TypeError("__registry_config__ must be a RegistryConfig") 

645 if registry_config is not None and registry_config is not declared_registry_config: 

646 raise ValueError("Registry configuration must have one authoritative declaration") 

647 registry_config = declared_registry_config 

648 elif registry_config is None: 

649 inherited_registry_configs: list[RegistryConfig] = [] 

650 for base in bases: 

651 inherited_registry_config = getattr( 

652 base, 

653 "__registry_config__", 

654 None, 

655 ) 

656 if not isinstance(inherited_registry_config, RegistryConfig): 

657 continue 

658 if all( 

659 inherited_registry_config is not existing_config 

660 for existing_config in inherited_registry_configs 

661 ): 

662 inherited_registry_configs.append(inherited_registry_config) 

663 if len(inherited_registry_configs) > 1: 

664 raise TypeError(f"{name} inherits multiple registry configuration authorities") 

665 registry_config = inherited_registry_configs[0] if inherited_registry_configs else None 

666 

667 # Create the class using ABCMeta 

668 new_class: type = super().__new__(mcs, name, bases, attrs, **class_kwargs) 

669 if isinstance(registry_family, RegistryFamily): 

670 registry_family.apply_to_class(new_class, attrs) 

671 if declared_registry_config is not None: 

672 declared_registry = attrs.get("__registry__") 

673 if ( 

674 "__registry__" in attrs 

675 and declared_registry is not declared_registry_config.registry_dict 

676 ): 

677 raise ValueError( 

678 f"{name}.__registry__ must be the registry owned by " "its __registry_config__" 

679 ) 

680 setattr(new_class, "__registry__", declared_registry_config.registry_dict) 

681 

682 # Auto-configure registry if not provided but class has __registry__ attributes 

683 if registry_config is None: 

684 registry_config = mcs._auto_configure_registry(new_class, attrs) 

685 if registry_config is None: 

686 # No config and no auto-config possible 

687 mcs._reject_replacement_without_registration( 

688 new_class, attrs, "it belongs to no registry" 

689 ) 

690 return new_class 

691 

692 # Set up lazy discovery if registry dict supports it (only once for base class) 

693 if ( 

694 isinstance(registry_config.registry_dict, LazyDiscoveryDict) 

695 and not registry_config.registry_dict._config 

696 ): 

697 config = registry_config 

698 

699 # Auto-wrap secondary registries with SecondaryRegistryDict 

700 if config.secondary_registries: 

701 import sys 

702 from dataclasses import replace 

703 

704 wrapped_secondaries: list[SecondaryRegistry] = [] 

705 module = sys.modules.get(new_class.__module__) 

706 

707 for sec_reg in config.secondary_registries: 

708 # Check if secondary registry needs wrapping 

709 if isinstance(sec_reg.registry_dict, dict) and not isinstance( 

710 sec_reg.registry_dict, SecondaryRegistryDict 

711 ): 

712 # Create a new SecondaryRegistryDict wrapping the primary registry 

713 wrapped_dict = SecondaryRegistryDict(registry_config.registry_dict) 

714 # Copy any existing entries from the old dict 

715 wrapped_dict.update(sec_reg.registry_dict) 

716 

717 # Find and update the module global variable 

718 if module: 

719 for var_name, var_value in vars(module).items(): 

720 if var_value is sec_reg.registry_dict: 

721 setattr(module, var_name, wrapped_dict) 

722 logger.debug( 

723 "Auto-wrapped secondary registry %r in %s", 

724 var_name, 

725 new_class.__module__, 

726 ) 

727 break 

728 

729 # Create new SecondaryRegistry with wrapped dict 

730 wrapped_sec_reg = SecondaryRegistry( 

731 registry_dict=wrapped_dict, 

732 key_source=sec_reg.key_source, 

733 attr_name=sec_reg.attr_name, 

734 ) 

735 wrapped_secondaries.append(wrapped_sec_reg) 

736 else: 

737 wrapped_secondaries.append(sec_reg) 

738 

739 # Rebuild config with wrapped secondary registries 

740 config = replace(config, secondary_registries=wrapped_secondaries) 

741 

742 registry_config.registry_dict._set_config(new_class, config) 

743 

744 # Only register concrete classes (not abstract base classes) 

745 if not bases or getattr(new_class, "__abstractmethods__", None): 

746 mcs._reject_replacement_without_registration( 

747 new_class, attrs, "it is abstract and does not register" 

748 ) 

749 return new_class 

750 

751 # Get or derive the registration key 

752 key = mcs._get_registration_key(name, new_class, registry_config) 

753 

754 # Handle missing key 

755 if key is None: 

756 mcs._reject_replacement_without_registration(new_class, attrs, "it has no registry key") 

757 return mcs._handle_missing_key(name, registry_config, new_class) 

758 

759 # Register in primary registry 

760 replaces = attrs.get(REPLACES_REGISTERED_ATTRIBUTE) 

761 if replaces is not None and not isinstance(replaces, type): 

762 raise TypeError( 

763 f"{_describe(new_class)} declares {REPLACES_REGISTERED_ATTRIBUTE} = " 

764 f"{replaces!r}; it must be the registered class this class replaces." 

765 ) 

766 superseded = mcs._register_class( 

767 new_class, 

768 key, 

769 registry_config, 

770 replaces=replaces, 

771 ) 

772 

773 # Handle secondary registrations 

774 if registry_config.secondary_registries: 

775 mcs._register_secondary( 

776 new_class, 

777 key, 

778 registry_config.secondary_registries, 

779 superseded=superseded, 

780 ) 

781 

782 # Log registration if enabled 

783 if registry_config.log_registration: 

784 logger.debug(f"Auto-registered {name} as '{key}' {registry_config.registry_name}") 

785 

786 return new_class 

787 

788 @staticmethod 

789 def _get_registration_key( 

790 name: str, 

791 cls: type, 

792 config: RegistryConfig, 

793 ) -> RegistryKey | None: 

794 """Get the registration key for a class (explicit or derived).""" 

795 # Try explicit key first. A key that registration stamped on an 

796 # ancestor after deriving it is that ancestor's key, not a declaration 

797 # this class inherits: the class derives its own. 

798 key = getattr(cls, config.key_attribute, None) 

799 if key is not None and config.key_extractor is not None: 

800 key_owner = next( 

801 (base for base in cls.__mro__ if config.key_attribute in vars(base)), 

802 None, 

803 ) 

804 if ( 

805 key_owner is not None 

806 and key_owner is not cls 

807 and vars(key_owner).get(_DERIVED_KEY_MARKER, False) 

808 ): 

809 key = None 

810 if key is not None: 

811 if not isinstance(key, Hashable): 

812 raise TypeError(f"Registry key {key!r} declared by {cls.__name__} is not hashable") 

813 return key 

814 

815 # Try key extractor if provided 

816 if config.key_extractor is not None: 

817 derived_key = config.key_extractor(name, cls) 

818 if derived_key is not None: 

819 setattr(cls, _DERIVED_KEY_MARKER, True) 

820 return derived_key 

821 

822 return None 

823 

824 @staticmethod 

825 def _handle_missing_key(name: str, config: RegistryConfig, new_class: type) -> type: 

826 """Handle case where no registration key is available.""" 

827 if config.skip_if_no_key: 

828 if config.log_registration: 

829 logger.debug(f"Skipping registration for {name} - no {config.key_attribute}") 

830 return new_class # Return the class, just don't register it 

831 else: 

832 raise ValueError( 

833 f"Class {name} must have {config.key_attribute} attribute " 

834 f"or provide a key_extractor in registry config" 

835 ) 

836 

837 @classmethod 

838 def _auto_configure_registry( 

839 cls: type["AutoRegisterMeta"], 

840 new_class: type, 

841 attrs: dict[str, Any], 

842 ) -> RegistryConfig | None: 

843 """ 

844 Auto-configure registry from metaclass OR base class attributes. 

845 

846 Priority: 

847 1. Metaclass attributes (__registry_dict__, __registry_key__ on metaclass) 

848 2. Base class attributes (__registry_key__ on class, auto-create __registry__) 

849 3. Parent class __registry__ (inherit from parent) 

850 

851 Returns: 

852 RegistryConfig if auto-configuration successful, None otherwise 

853 """ 

854 # Check if the metaclass has __registry_dict__ attribute (old style) 

855 registry_dict = getattr(cls, "__registry_dict__", None) 

856 

857 # If no metaclass registry, check if base class wants auto-creation or inheritance 

858 if registry_dict is None: 

859 # First check if any parent class has __registry__ (inherit from parent) 

860 # This takes priority over creating a new registry 

861 for base in new_class.__mro__[1:]: # Skip self 

862 if hasattr(base, "__registry__"): 

863 registry_dict = getattr(base, "__registry__") 

864 key_attribute = getattr(base, "__registry_key__", None) 

865 key_extractor = getattr(base, "__key_extractor__", None) 

866 skip_if_no_key = getattr(base, "__skip_if_no_key__", True) 

867 secondary_registries = getattr(base, "__secondary_registries__", None) 

868 registry_name = getattr(base, "__registry_name__", None) 

869 break 

870 else: 

871 # No parent registry found - check if class explicitly defines a 

872 # registry family or __registry_key__ (only create new registry 

873 # from the class body, or from an inherited registry protocol 

874 # mixin that does not own a registry itself). 

875 registry_family = attrs.get("__registry_family__") 

876 key_attribute = attrs.get("__registry_key__") 

877 if key_attribute is None and isinstance(registry_family, RegistryFamily): 

878 key_attribute = registry_family.key_attribute_name 

879 inherited_registry_base = None 

880 if key_attribute is None: 

881 for base in new_class.__mro__[1:]: 

882 inherited_key_attribute = getattr(base, "__registry_key__", None) 

883 if inherited_key_attribute is not None: 

884 inherited_registry_base = base 

885 key_attribute = inherited_key_attribute 

886 break 

887 if key_attribute is not None: 

888 # Check if class already provides its own __registry__ dict 

889 # (allows opting out of LazyDiscoveryDict) 

890 if "__registry__" in attrs: 

891 registry_dict = attrs["__registry__"] 

892 else: 

893 # Auto-create registry dict and store on the class 

894 registry_dict = LazyDiscoveryDict() 

895 setattr(new_class, "__registry__", registry_dict) 

896 

897 # Get other optional attributes from class. Explicit legacy 

898 # class attributes override the family/inherited declaration. 

899 key_extractor = attrs.get("__key_extractor__") 

900 if key_extractor is None and inherited_registry_base is not None: 

901 key_extractor = getattr(inherited_registry_base, "__key_extractor__", None) 

902 if "__skip_if_no_key__" in attrs: 

903 skip_if_no_key = attrs["__skip_if_no_key__"] 

904 elif isinstance(registry_family, RegistryFamily): 

905 skip_if_no_key = registry_family.skip_if_no_key 

906 elif inherited_registry_base is not None: 

907 skip_if_no_key = getattr( 

908 inherited_registry_base, "__skip_if_no_key__", True 

909 ) 

910 else: 

911 skip_if_no_key = True 

912 secondary_registries = attrs.get("__secondary_registries__") 

913 if secondary_registries is None and inherited_registry_base is not None: 

914 secondary_registries = getattr( 

915 inherited_registry_base, "__secondary_registries__", None 

916 ) 

917 if "__registry_name__" in attrs: 

918 registry_name = attrs["__registry_name__"] 

919 elif isinstance(registry_family, RegistryFamily): 

920 registry_name = registry_family.registry_name 

921 elif inherited_registry_base is not None: 

922 registry_name = getattr(inherited_registry_base, "__registry_name__", None) 

923 else: 

924 registry_name = None 

925 else: 

926 return None # No registry configuration found 

927 else: 

928 # Old style: get from metaclass 

929 key_attribute = getattr(cls, "__registry_key__", "_registry_key") 

930 key_extractor = getattr(cls, "__key_extractor__", None) 

931 skip_if_no_key = getattr(cls, "__skip_if_no_key__", True) 

932 secondary_registries = getattr(cls, "__secondary_registries__", None) 

933 registry_name = getattr(cls, "__registry_name__", None) 

934 

935 # Auto-derive registry name if not provided 

936 if registry_name is None: 

937 # Derive from class name: "StorageBackend" → "storage backend" 

938 # The family is named after the class that owns the registry, so 

939 # messages about any member name the family. 

940 registry_owner = next( 

941 (base for base in new_class.__mro__ if "__registry__" in vars(base)), 

942 new_class, 

943 ) 

944 clean_name = registry_owner.__name__ 

945 for suffix in ["Base", "Meta", "Handler", "Registry"]: 

946 if clean_name.endswith(suffix): 

947 clean_name = clean_name[: -len(suffix)] 

948 break 

949 # Convert CamelCase to space-separated lowercase 

950 import re 

951 

952 registry_name = re.sub(r"([A-Z])", r" \1", clean_name).strip().lower() 

953 

954 logger.debug( 

955 f"Auto-configured registry for {new_class.__name__}: " 

956 f"key_attribute={key_attribute}, registry_name={registry_name}" 

957 ) 

958 

959 if not isinstance(key_attribute, str): 

960 raise TypeError(f"Registry key attribute for {new_class.__name__} must be a string") 

961 

962 return RegistryConfig( 

963 registry_dict=registry_dict, 

964 key_attribute=key_attribute, 

965 key_extractor=key_extractor, 

966 skip_if_no_key=skip_if_no_key, 

967 secondary_registries=secondary_registries, 

968 registry_name=registry_name, 

969 ) 

970 

971 @staticmethod 

972 def _reject_replacement_without_registration( 

973 cls: type, 

974 attrs: dict[str, Any], 

975 reason: str, 

976 ) -> None: 

977 """A declared replacement that replaces nothing is an error, not a no-op.""" 

978 replaces = attrs.get(REPLACES_REGISTERED_ATTRIBUTE) 

979 if replaces is None: 

980 return 

981 raise DuplicateRegistryKeyError( 

982 f"{_describe(cls)} declares {REPLACES_REGISTERED_ATTRIBUTE} = " 

983 f"{_describe(replaces)}, but {reason}." 

984 ) 

985 

986 @staticmethod 

987 def _register_class( 

988 cls: type, 

989 key: RegistryKey, 

990 config: RegistryConfig, 

991 replaces: object = None, 

992 ) -> type | None: 

993 """Register class in primary registry; return the class it took the key from.""" 

994 superseded: type | None = register_once( 

995 config.registry_dict, 

996 key, 

997 cls, 

998 registry_name=config.registry_name, 

999 replaces=replaces, 

1000 ) 

1001 setattr(cls, config.key_attribute, key) 

1002 if _DECLARATION_TOKEN not in vars(cls): 

1003 setattr(cls, _DECLARATION_TOKEN, object()) 

1004 return superseded 

1005 

1006 @staticmethod 

1007 def _register_secondary( 

1008 cls: type, 

1009 primary_key: RegistryKey, 

1010 secondary_registries: list[SecondaryRegistry], 

1011 superseded: type | None = None, 

1012 ) -> None: 

1013 """Handle secondary registry registrations.""" 

1014 for sec_reg in secondary_registries: 

1015 value = getattr(cls, sec_reg.attr_name, None) 

1016 if value is None: 

1017 continue 

1018 

1019 # Determine the key for secondary registration 

1020 secondary_key: RegistryKey 

1021 if sec_reg.key_source == PRIMARY_KEY: 

1022 secondary_key = primary_key 

1023 else: 

1024 declared_secondary_key = getattr(cls, sec_reg.key_source, None) 

1025 if declared_secondary_key is None: 

1026 logger.warning( 

1027 f"Cannot register {sec_reg.attr_name} for {cls.__name__} - " 

1028 f"no {sec_reg.key_source} attribute" 

1029 ) 

1030 continue 

1031 if not isinstance(declared_secondary_key, Hashable): 

1032 raise TypeError( 

1033 f"Secondary registry key {declared_secondary_key!r} declared " 

1034 f"by {cls.__name__} is not hashable" 

1035 ) 

1036 secondary_key = declared_secondary_key 

1037 

1038 # Register in secondary registry. The value registered by the 

1039 # class this one took the primary key from goes with it. 

1040 superseded_value = ( 

1041 None if superseded is None else getattr(superseded, sec_reg.attr_name, None) 

1042 ) 

1043 register_once( 

1044 sec_reg.registry_dict, 

1045 secondary_key, 

1046 value, 

1047 registry_name=f"{sec_reg.attr_name} (secondary registry of {cls.__name__})", 

1048 superseded_values=() if superseded_value is None else (superseded_value,), 

1049 ) 

1050 logger.debug( 

1051 f"Auto-registered {sec_reg.attr_name} from {cls.__name__} as '{secondary_key}'" 

1052 ) 

1053 

1054 

1055class RegisteredEnumMeta(AutoRegisterMeta, EnumMeta): 

1056 """Metaclass for enum families that also need AutoRegisterMeta membership.""" 

1057 

1058 

1059# Helper functions for common key extraction patterns 

1060 

1061 

1062def extract_key_from_class_name(name: str, cls: type) -> str: 

1063 """Use the concrete class name as its registry key.""" 

1064 return name 

1065 

1066 

1067def make_suffix_extractor(suffix: str) -> KeyExtractor: 

1068 """ 

1069 Create a key extractor that removes a suffix from class names. 

1070 

1071 Args: 

1072 suffix: The suffix to remove (e.g., 'Handler', 'Backend') 

1073 

1074 Returns: 

1075 A key extractor function 

1076 

1077 Examples: 

1078 extract_handler = make_suffix_extractor('Handler') 

1079 extract_handler('ImageXpressHandler', cls) -> 'imagexpress' 

1080 

1081 extract_backend = make_suffix_extractor('Backend') 

1082 extract_backend('DiskStorageBackend', cls) -> 'diskstorage' 

1083 """ 

1084 suffix_len = len(suffix) 

1085 

1086 def extractor(name: str, cls: type) -> str: 

1087 if name.endswith(suffix): 

1088 return name[:-suffix_len].lower() 

1089 return name.lower() 

1090 

1091 return extractor 

1092 

1093 

1094# Pre-built extractors for common patterns 

1095extract_key_from_handler_suffix = make_suffix_extractor("Handler") 

1096extract_key_from_backend_suffix = make_suffix_extractor("Backend")