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
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-17 00:39 +0000
1"""
2Generic metaclass infrastructure for automatic plugin registration.
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.
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)
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
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
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
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
41This keeps domain semantics on their nominal owner while eliminating duplicated
42metaclass wrappers and caller-side discovery inference.
43"""
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
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
68logger = logging.getLogger(__name__)
70# Type aliases for clarity
71RegistryKey = Hashable
72RegistryDict = dict[RegistryKey, Any]
73KeyExtractor = Callable[[str, type], RegistryKey]
75# Constants for key sources
76PRIMARY_KEY = "primary"
78# Declared in a class body: the registered class this class takes the key from.
79REPLACES_REGISTERED_ATTRIBUTE = "__replaces_registered__"
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__"
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__"
90_ABSENT: Any = object()
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}"
102def is_same_declaration(registered: object, candidate: object) -> bool:
103 """Whether two class objects come from one class statement.
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 )
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.
138 Returns the value that ``value`` took the key from, or ``None``.
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 )
181class RegistryKeyAttribute(str, Enum):
182 """Common class-attribute names used as registry keys."""
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"
191class SecondaryRegistryDict(dict[RegistryKey, Any]):
192 """
193 Dict for secondary registries that auto-triggers primary registry discovery.
195 When accessed, this dict triggers discovery of the primary registry,
196 which populates both the primary and secondary registries.
197 """
199 def __init__(self, primary_registry: "LazyDiscoveryDict") -> None:
200 super().__init__()
201 self._primary_registry = primary_registry
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()
208 def __getitem__(self, key: RegistryKey) -> Any:
209 self._ensure_discovered()
210 return super().__getitem__(key)
212 def __contains__(self, key: object) -> bool:
213 self._ensure_discovered()
214 return super().__contains__(key)
216 def __iter__(self) -> Iterator[RegistryKey]:
217 self._ensure_discovered()
218 return super().__iter__()
220 def __len__(self) -> int:
221 self._ensure_discovered()
222 return super().__len__()
224 def keys(self) -> Any:
225 self._ensure_discovered()
226 return super().keys()
228 def values(self) -> Any:
229 self._ensure_discovered()
230 return super().values()
232 def items(self) -> Any:
233 self._ensure_discovered()
234 return super().items()
236 def get(self, key: RegistryKey, default: Any = None) -> Any:
237 self._ensure_discovered()
238 return super().get(key, default)
241class LazyDiscoveryDict(dict[RegistryKey, Any]):
242 """
243 Dict that auto-discovers plugins on first access with optional caching.
245 Supports caching discovered plugins to speed up subsequent application starts.
246 Cache is validated against package version and file modification times.
248 Thread-safe: Uses locking to ensure discovery happens only once
249 even when accessed from multiple threads simultaneously.
250 """
252 def __init__(self, enable_cache: bool = True) -> None:
253 """
254 Initialize lazy discovery dict.
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
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
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
290 def _get_version(self) -> str:
291 """
292 Get version from the discovery package for cache validation.
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"
307 def _get_discovery_file_mtimes(self) -> dict[str, float]:
308 """Return the complete source inventory for this discovery package."""
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 )
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
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
334 def _discovery_failed(self) -> None:
335 self._discovered = False
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
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()
369 def discover_matching(self, module_filter: Callable[[str], bool]) -> None:
370 """Admit selected modules through the original discovery/import owner.
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 )
395 def __getitem__(self, key: RegistryKey) -> Any:
396 with self._discovery_lock:
397 self._discover()
398 return super().__getitem__(key)
400 def __contains__(self, key: object) -> bool:
401 with self._discovery_lock:
402 self._discover()
403 return super().__contains__(key)
405 def __iter__(self) -> Iterator[RegistryKey]:
406 with self._discovery_lock:
407 self._discover()
408 return super().__iter__()
410 def __len__(self) -> int:
411 with self._discovery_lock:
412 self._discover()
413 return super().__len__()
415 def keys(self) -> Any:
416 with self._discovery_lock:
417 self._discover()
418 return super().keys()
420 def values(self) -> Any:
421 with self._discovery_lock:
422 self._discover()
423 return super().values()
425 def items(self) -> Any:
426 with self._discovery_lock:
427 self._discover()
428 return super().items()
430 def get(self, key: RegistryKey, default: Any = None) -> Any:
431 with self._discovery_lock:
432 self._discover()
433 return super().get(key, default)
435 def __getstate__(self) -> dict[RegistryKey, Any]:
436 """
437 Return state for pickling, excluding non-picklable objects.
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
455 def __setstate__(self, state: dict[RegistryKey, Any]) -> None:
456 """
457 Restore state from pickle, recreating non-picklable objects.
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
473@dataclass(frozen=True)
474class SecondaryRegistry:
475 """Configuration for a secondary registry (e.g., metadata handlers)."""
477 registry_dict: RegistryDict
478 key_source: str # 'primary' or attribute name
479 attr_name: str # Attribute to check on the class
482@dataclass(frozen=True)
483class RegistryFamily:
484 """Declarative registry-family configuration for ``AutoRegisterMeta`` roots.
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 """
492 key_attribute: str | RegistryKeyAttribute
493 skip_if_no_key: bool = True
494 registry_name: str | None = None
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
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)
513@dataclass(frozen=True)
514class RegistryConfig:
515 """
516 Configuration for automatic class registration behavior.
518 This dataclass encapsulates all the configuration needed for metaclass
519 registration, making the pattern explicit and easy to understand.
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)
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 )
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 )
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 """
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
584class AutoRegisterMeta(ABCMeta):
585 """
586 Generic metaclass for automatic plugin registration (Pattern A).
588 This metaclass automatically registers concrete classes in a global registry
589 when they are defined, eliminating the need for manual registration calls.
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
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)
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
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 """
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.
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__``.
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
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)
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
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
699 # Auto-wrap secondary registries with SecondaryRegistryDict
700 if config.secondary_registries:
701 import sys
702 from dataclasses import replace
704 wrapped_secondaries: list[SecondaryRegistry] = []
705 module = sys.modules.get(new_class.__module__)
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)
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
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)
739 # Rebuild config with wrapped secondary registries
740 config = replace(config, secondary_registries=wrapped_secondaries)
742 registry_config.registry_dict._set_config(new_class, config)
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
751 # Get or derive the registration key
752 key = mcs._get_registration_key(name, new_class, registry_config)
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)
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 )
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 )
782 # Log registration if enabled
783 if registry_config.log_registration:
784 logger.debug(f"Auto-registered {name} as '{key}' {registry_config.registry_name}")
786 return new_class
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
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
822 return None
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 )
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.
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)
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)
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)
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)
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
952 registry_name = re.sub(r"([A-Z])", r" \1", clean_name).strip().lower()
954 logger.debug(
955 f"Auto-configured registry for {new_class.__name__}: "
956 f"key_attribute={key_attribute}, registry_name={registry_name}"
957 )
959 if not isinstance(key_attribute, str):
960 raise TypeError(f"Registry key attribute for {new_class.__name__} must be a string")
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 )
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 )
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
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
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
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 )
1055class RegisteredEnumMeta(AutoRegisterMeta, EnumMeta):
1056 """Metaclass for enum families that also need AutoRegisterMeta membership."""
1059# Helper functions for common key extraction patterns
1062def extract_key_from_class_name(name: str, cls: type) -> str:
1063 """Use the concrete class name as its registry key."""
1064 return name
1067def make_suffix_extractor(suffix: str) -> KeyExtractor:
1068 """
1069 Create a key extractor that removes a suffix from class names.
1071 Args:
1072 suffix: The suffix to remove (e.g., 'Handler', 'Backend')
1074 Returns:
1075 A key extractor function
1077 Examples:
1078 extract_handler = make_suffix_extractor('Handler')
1079 extract_handler('ImageXpressHandler', cls) -> 'imagexpress'
1081 extract_backend = make_suffix_extractor('Backend')
1082 extract_backend('DiskStorageBackend', cls) -> 'diskstorage'
1083 """
1084 suffix_len = len(suffix)
1086 def extractor(name: str, cls: type) -> str:
1087 if name.endswith(suffix):
1088 return name[:-suffix_len].lower()
1089 return name.lower()
1091 return extractor
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")