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

1""" 

2Generic registry class discovery utility. 

3 

4Consolidates duplicated registry discovery patterns across: 

5- Library registries (processing backends) 

6- Format registries (experimental analysis) 

7- Microscope handler registries 

8- Storage backend registries 

9 

10This module eliminates ~70 lines of duplicated pkgutil + importlib boilerplate 

11by providing a single, well-tested discovery function. 

12""" 

13 

14import importlib 

15import inspect 

16import logging 

17import pkgutil 

18import threading 

19from collections.abc import Callable, Iterable 

20from types import ModuleType 

21from typing import NoReturn 

22 

23from .exceptions import DiscoveryError 

24 

25logger = logging.getLogger(__name__) 

26_ROOT_LOGGING_IMPORT_LOCK = threading.RLock() 

27 

28 

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. 

34 

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. 

40 

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 """ 

46 

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() 

67 

68 

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. 

80 

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. 

84 

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. 

96 

97 Returns: 

98 List of discovered registry classes 

99 

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() 

114 

115 logger.debug( 

116 f"Discovering registry classes: base={base_class.__name__}, " 

117 f"prefix={package_prefix}, exclude={exclude_modules}" 

118 ) 

119 

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 

124 

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 

129 

130 if module_filter is not None and not module_filter(module_name): 

131 continue 

132 

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) 

144 

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 ) 

149 

150 return registry_classes 

151 

152 

153def _walk_import_failed(module_name: str) -> NoReturn: 

154 raise DiscoveryError(f"Cannot discover package {module_name}") 

155 

156 

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. 

166 

167 Uses pkgutil.walk_packages instead of iter_modules to recursively scan 

168 all subpackages. Useful for deeply nested registry structures. 

169 

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 

177 

178 Returns: 

179 List of discovered registry classes 

180 

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() 

195 

196 logger.debug( 

197 f"Discovering registry classes (recursive): base={base_class.__name__}, " 

198 f"prefix={package_prefix}, exclude={exclude_modules}" 

199 ) 

200 

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 

208 

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 

213 

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) 

224 

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 ) 

231 

232 return registry_classes