Coverage for src/metaclass_registry/discovery.py: 95%
80 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 registry class discovery utility.
4Consolidates duplicated registry discovery patterns across:
5- Library registries (processing backends)
6- Format registries (experimental analysis)
7- Microscope handler registries
8- Storage backend registries
10This module eliminates ~70 lines of duplicated pkgutil + importlib boilerplate
11by providing a single, well-tested discovery function.
12"""
14import importlib
15import inspect
16import logging
17import pkgutil
18import threading
19from collections.abc import Callable, Iterable
20from types import ModuleType
21from typing import NoReturn
23from .exceptions import DiscoveryError
25logger = logging.getLogger(__name__)
26_ROOT_LOGGING_IMPORT_LOCK = threading.RLock()
29def import_module_preserving_root_logging(
30 module_name: str,
31 package: str | None = None,
32) -> ModuleType:
33 """Import a module without transferring root-logger ownership to it.
35 Plugin and callable discovery imports code owned by third parties. Some
36 packages configure the process root logger at import time, which can replace
37 application handlers or write diagnostics into machine-readable stdout.
38 Discovery owns importing those modules, but the hosting application retains
39 ownership of root logging.
41 A temporary handler prevents ordinary ``logging.basicConfig`` calls from
42 installing handlers. The prior root handler set, level, disabled state, and
43 global logging threshold are restored even when the import fails. Named
44 package loggers remain under the imported package's control.
45 """
47 with _ROOT_LOGGING_IMPORT_LOCK:
48 root_logger = logging.getLogger()
49 previous_handlers = tuple(root_logger.handlers)
50 previous_level = root_logger.level
51 previous_disabled = root_logger.disabled
52 previous_disable_threshold = root_logger.manager.disable
53 guard_handler = logging.NullHandler()
54 root_logger.handlers = [guard_handler]
55 try:
56 return importlib.import_module(module_name, package)
57 finally:
58 temporary_handlers = tuple(root_logger.handlers)
59 root_logger.handlers = list(previous_handlers)
60 root_logger.setLevel(previous_level)
61 root_logger.disabled = previous_disabled
62 logging.disable(previous_disable_threshold)
63 previous_handler_ids = {id(handler) for handler in previous_handlers}
64 for handler in temporary_handlers:
65 if id(handler) not in previous_handler_ids:
66 handler.close()
69def discover_registry_classes(
70 package_path: Iterable[str],
71 package_prefix: str,
72 base_class: type,
73 exclude_modules: set[str] | None = None,
74 validation_func: Callable[[type], bool] | None = None,
75 skip_packages: bool = True,
76 module_filter: Callable[[str], bool] | None = None,
77) -> list[type]:
78 """
79 Generic registry class discovery using pkgutil + importlib pattern.
81 Scans a package for classes that inherit from a base class and automatically
82 discovers them for registration. This eliminates duplicated discovery code
83 across different registry systems.
85 Args:
86 package_path: Package __path__ attribute to scan (e.g., openhcs.io.__path__)
87 Accepts any iterable of strings (List, Tuple, _NamespacePath, etc.)
88 package_prefix: Module prefix for importlib (e.g., "openhcs.io.")
89 base_class: Base class to filter for (e.g., StorageBackend)
90 exclude_modules: Set of module name substrings to skip (e.g., {'base', 'registry'})
91 validation_func: Optional function to validate discovered classes
92 Should return True to include, False to exclude
93 skip_packages: If True, skip package directories (default: True)
94 module_filter: Declaration-owned eligibility before import. Selected
95 import failures propagate instead of incomplete absence.
97 Returns:
98 List of discovered registry classes
100 Example:
101 >>> from openhcs.io.base import StorageBackend
102 >>> import openhcs.io
103 >>> backends = discover_registry_classes(
104 ... package_path=openhcs.io.__path__,
105 ... package_prefix="openhcs.io.",
106 ... base_class=StorageBackend,
107 ... exclude_modules={'base', 'backend_registry'}
108 ... )
109 >>> print([b.__name__ for b in backends])
110 ['DiskStorageBackend', 'MemoryStorageBackend', 'ZarrStorageBackend']
111 """
112 registry_classes = []
113 exclude_modules = exclude_modules or set()
115 logger.debug(
116 f"Discovering registry classes: base={base_class.__name__}, "
117 f"prefix={package_prefix}, exclude={exclude_modules}"
118 )
120 for importer, module_name, ispkg in pkgutil.iter_modules(package_path, package_prefix):
121 # Skip packages if requested
122 if ispkg and skip_packages:
123 continue
125 # Skip excluded modules
126 if any(excluded in module_name for excluded in exclude_modules):
127 logger.debug(f"Skipping excluded module: {module_name}")
128 continue
130 if module_filter is not None and not module_filter(module_name):
131 continue
133 module = import_module_preserving_root_logging(module_name)
134 for name, obj in inspect.getmembers(module, inspect.isclass):
135 if not issubclass(obj, base_class) or obj is base_class:
136 continue
137 if obj.__module__ != module_name:
138 continue
139 if validation_func and not validation_func(obj):
140 logger.debug(f"Validation failed for {obj.__name__}")
141 continue
142 logger.debug(f"Discovered registry class: {obj.__name__} from {module_name}")
143 registry_classes.append(obj)
145 logger.info(
146 f"Discovered {len(registry_classes)} registry classes for {base_class.__name__}: "
147 f"{[cls.__name__ for cls in registry_classes]}"
148 )
150 return registry_classes
153def _walk_import_failed(module_name: str) -> NoReturn:
154 raise DiscoveryError(f"Cannot discover package {module_name}")
157def discover_registry_classes_recursive(
158 package_path: Iterable[str],
159 package_prefix: str,
160 base_class: type,
161 exclude_modules: set[str] | None = None,
162 validation_func: Callable[[type], bool] | None = None,
163) -> list[type]:
164 """
165 Recursive version of discover_registry_classes that walks entire package tree.
167 Uses pkgutil.walk_packages instead of iter_modules to recursively scan
168 all subpackages. Useful for deeply nested registry structures.
170 Args:
171 package_path: Package __path__ attribute to scan
172 Accepts any iterable of strings (List, Tuple, _NamespacePath, etc.)
173 package_prefix: Module prefix for importlib
174 base_class: Base class to filter for
175 exclude_modules: Set of module name substrings to skip
176 validation_func: Optional function to validate discovered classes
178 Returns:
179 List of discovered registry classes
181 Example:
182 >>> from openhcs.processing.backends.lib_registry.unified_registry import (
183 ... LibraryRegistryBase,
184 ... )
185 >>> import openhcs.processing.backends.experimental_analysis
186 >>> registries = discover_registry_classes_recursive(
187 ... package_path=openhcs.processing.backends.experimental_analysis.__path__,
188 ... package_prefix="openhcs.processing.backends.experimental_analysis.",
189 ... base_class=MicroscopeFormatRegistryBase,
190 ... exclude_modules={'base'}
191 ... )
192 """
193 registry_classes = []
194 exclude_modules = exclude_modules or set()
196 logger.debug(
197 f"Discovering registry classes (recursive): base={base_class.__name__}, "
198 f"prefix={package_prefix}, exclude={exclude_modules}"
199 )
201 # Walk through all modules in the package tree
202 for importer, modname, ispkg in pkgutil.walk_packages(
203 package_path, prefix=package_prefix, onerror=_walk_import_failed
204 ):
205 # Skip packages (only process modules)
206 if ispkg:
207 continue
209 # Skip excluded modules
210 if any(excluded in modname for excluded in exclude_modules):
211 logger.debug(f"Skipping excluded module: {modname}")
212 continue
214 module = import_module_preserving_root_logging(modname)
215 for attr_name in dir(module):
216 attr = getattr(module, attr_name)
217 if not isinstance(attr, type) or not issubclass(attr, base_class) or attr is base_class:
218 continue
219 if validation_func and not validation_func(attr):
220 logger.debug(f"Validation failed for {attr.__name__}")
221 continue
222 logger.debug(f"Discovered registry class: {attr.__name__} from {modname}")
223 registry_classes.append(attr)
225 logger.info(
226 "Discovered %d registry classes (recursive) for %s: %s",
227 len(registry_classes),
228 base_class.__name__,
229 [cls.__name__ for cls in registry_classes],
230 )
232 return registry_classes