Coverage for src/metaclass_registry/strategies.py: 99%

233 statements  

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

1"""Strategy-family mixins for ``AutoRegisterMeta`` registries. 

2 

3Each mixin derives a family's registry key from one declaration on its concrete 

4members (an enum member, a nominal value type, or a context predicate plus 

5inheritance) and selects members from the registry, so callers never keep 

6dispatch tables beside the family. 

7""" 

8 

9from __future__ import annotations 

10 

11from abc import ABC, abstractmethod 

12from collections.abc import Callable, Hashable, Iterable, Mapping, MutableMapping 

13from dataclasses import dataclass, field 

14from enum import Enum 

15from functools import cache 

16from typing import Any, ClassVar, Generic, TypeGuard, TypeVar, cast 

17 

18from .core import ( 

19 AutoRegisterMeta, 

20 LazyDiscoveryDict, 

21 RegistryConfig, 

22 RegistryFamily, 

23 RegistryKeyAttribute, 

24 extract_key_from_class_name, 

25) 

26 

27_EnumT = TypeVar("_EnumT", bound=Enum) 

28_MemberT = TypeVar("_MemberT") 

29_ContextT = TypeVar("_ContextT") 

30_StrategyT = TypeVar("_StrategyT", bound="EnumKeyedStrategyMixin[Any]") 

31_TypeStrategyT = TypeVar("_TypeStrategyT", bound="NominalTypeKeyedStrategyMixin") 

32_ContextStrategyT = TypeVar( 

33 "_ContextStrategyT", 

34 bound="MostDerivedContextStrategyMixin[Any]", 

35) 

36ContextStrategyTypes = tuple[type[_ContextStrategyT], ...] 

37 

38 

39NominalTypeMember = type[Any] | tuple[type[Any], ...] 

40 

41 

42_FAMILY_PROJECTION_RESETS: list[Callable[[], None]] = [] 

43_ProjectionT = TypeVar("_ProjectionT", bound=Callable[..., Any]) 

44 

45 

46def _family_projection(function: _ProjectionT) -> _ProjectionT: 

47 """Memoize a registry-derived view until the next family member is declared.""" 

48 projection = cache(function) 

49 _FAMILY_PROJECTION_RESETS.append(projection.cache_clear) 

50 return cast(_ProjectionT, projection) 

51 

52 

53def _invalidate_family_projections() -> None: 

54 for reset in _FAMILY_PROJECTION_RESETS: 

55 reset() 

56 

57 

58class RegisteredStrategyTypesMixin(Generic[_MemberT]): 

59 """Shared projection of an AutoRegisterMeta registry into concrete classes.""" 

60 

61 __registry__: ClassVar[Mapping[Any, type[Any]]] 

62 

63 def __init_subclass__(cls, **kwargs: Any) -> None: 

64 super().__init_subclass__(**kwargs) 

65 _invalidate_family_projections() 

66 

67 @classmethod 

68 @_family_projection 

69 def registered_strategy_types(cls) -> tuple[type[_MemberT], ...]: 

70 """Return registered concrete strategy classes.""" 

71 return tuple( 

72 dict.fromkeys(cast(type[_MemberT], item) for item in cls.__registry__.values()) 

73 ) 

74 

75 

76def enum_key_from_class(name: str, cls: type[EnumKeyedStrategyMixin[Any]]) -> Hashable | None: 

77 """Return the enum-value registry key declared directly on one strategy.""" 

78 del name 

79 member = cls.__dict__.get(cls.__enum_member_attr__) 

80 if isinstance(member, Enum): 

81 value: Hashable = member.value 

82 return value 

83 return None 

84 

85 

86class StrategyLabelRegistryMixin: 

87 """Shared AutoRegister protocol for strategy roots keyed by strategy_label.""" 

88 

89 __registry_key__ = RegistryKeyAttribute.STRATEGY_LABEL.value 

90 __skip_if_no_key__ = True 

91 __registry_family__ = RegistryFamily(RegistryKeyAttribute.STRATEGY_LABEL) 

92 strategy_label: ClassVar[str | None] = None 

93 

94 

95class EnumKeyedStrategyMixin(Generic[_EnumT]): 

96 """Mixin for AutoRegisterMeta ABC families keyed by enum member values. 

97 

98 Concrete strategies declare the enum member they implement. The mixin 

99 derives the JSON-safe registry key before AutoRegisterMeta registers the 

100 concrete class, avoiding repeated ``label = enum.value`` boilerplate. 

101 """ 

102 

103 __registry_key__ = RegistryKeyAttribute.STRATEGY_LABEL.value 

104 __skip_if_no_key__ = True 

105 __registry_family__ = RegistryFamily(RegistryKeyAttribute.STRATEGY_LABEL) 

106 __enum_member_attr__: ClassVar[str] = "strategy_key" 

107 __registry__: ClassVar[Mapping[Any, type[Any]]] 

108 __key_extractor__: ClassVar[Any] 

109 strategy_label: ClassVar[str | None] = None 

110 

111 def __init_subclass__(cls, **kwargs: Any) -> None: 

112 super().__init_subclass__(**kwargs) 

113 _invalidate_family_projections() 

114 if "__key_extractor__" not in cls.__dict__: 

115 cls.__key_extractor__ = staticmethod(enum_key_from_class) 

116 

117 @classmethod 

118 def for_enum_member(cls: type[_StrategyT], member: _EnumT) -> _StrategyT: 

119 """Instantiate the registered strategy for an enum member.""" 

120 strategy_type = cls.strategy_type_for_enum_member(member) 

121 return cast(_StrategyT, strategy_type()) 

122 

123 @classmethod 

124 @_family_projection 

125 def strategy_type_for_enum_member( 

126 cls: type[_StrategyT], 

127 member: _EnumT, 

128 ) -> type[_StrategyT]: 

129 """Return the registered strategy class for an enum member.""" 

130 return cast(type[_StrategyT], cls.__registry__[member.value]) 

131 

132 @classmethod 

133 @_family_projection 

134 def registered_strategy_types( 

135 cls: type[_StrategyT], 

136 ) -> tuple[type[_StrategyT], ...]: 

137 """Return one registered strategy class per declared enum member. 

138 

139 Registry cache backends may preserve JSON-safe string forms of non-string 

140 enum keys alongside the original key. The enum member declared on the 

141 strategy is the semantic identity, so collapse aliases there. 

142 """ 

143 strategy_types: dict[tuple[type[Enum], Enum] | int, type[_StrategyT]] = {} 

144 for strategy_type in cls.__registry__.values(): 

145 member = strategy_type.__dict__.get(cls.__enum_member_attr__) 

146 key: tuple[type[Enum], Enum] | int 

147 if isinstance(member, Enum): 

148 key = (type(member), member) 

149 else: 

150 key = id(strategy_type) 

151 if key not in strategy_types: 

152 strategy_types[key] = cast(type[_StrategyT], strategy_type) 

153 return tuple(strategy_types.values()) 

154 

155 

156class NominalTypeKeyedStrategyMixin(RegisteredStrategyTypesMixin[_TypeStrategyT]): 

157 """Mixin for strategies selected by nominal runtime value types. 

158 

159 Concrete strategies declare their owning Python type in ``value_type``. 

160 The mixin derives a JSON-safe registry key from that nominal type, so 

161 ``AutoRegisterMeta`` never stores raw type objects as registry/cache keys. 

162 """ 

163 

164 value_type: ClassVar[NominalTypeMember | None] = None 

165 value_type_label: ClassVar[str | None] = None 

166 

167 def __init_subclass__(cls, **kwargs: Any) -> None: 

168 super().__init_subclass__(**kwargs) 

169 member = cls.value_type 

170 if not _is_nominal_type_member(member): 

171 return 

172 if cls.__dict__.get("value_type_label") is None: 

173 cls.value_type_label = _nominal_type_key(member) 

174 

175 @classmethod 

176 def for_nominal_value( 

177 cls: type[_TypeStrategyT], 

178 value: object, 

179 ) -> _TypeStrategyT | None: 

180 """Instantiate the most specific registered strategy owning ``value``.""" 

181 strategy_types = cls.strategy_types_for_nominal_value(value) 

182 return None if not strategy_types else cast(_TypeStrategyT, strategy_types[0]()) 

183 

184 @classmethod 

185 def require_nominal_value( 

186 cls: type[_TypeStrategyT], 

187 value: object, 

188 *, 

189 context: str, 

190 ) -> _TypeStrategyT: 

191 """Require an explicitly registered strategy for ``value``.""" 

192 strategy = cls.for_nominal_value(value) 

193 if strategy is None: 

194 raise TypeError( 

195 f"{context} has no registered nominal strategy for " 

196 f"{type(value).__module__}.{type(value).__qualname__}." 

197 ) 

198 return cast(_TypeStrategyT, strategy) 

199 

200 @classmethod 

201 def strategy_types_for_nominal_value( 

202 cls: type[_TypeStrategyT], 

203 value: object, 

204 ) -> tuple[type[_TypeStrategyT], ...]: 

205 """Return registered strategy classes ordered by runtime MRO specificity.""" 

206 value_type: Any = type(value) 

207 return cls.strategy_types_for_nominal_type(value_type) 

208 

209 @classmethod 

210 @_family_projection 

211 def strategy_types_for_nominal_type( 

212 cls: type[_TypeStrategyT], 

213 value_type: type[Any], 

214 ) -> tuple[type[_TypeStrategyT], ...]: 

215 """Return registered strategy classes ordered by type MRO specificity.""" 

216 return cls.order_nominal_strategy_members( 

217 value_type, 

218 cls.nominal_strategy_members(), 

219 ) 

220 

221 @classmethod 

222 def nominal_strategy_members( 

223 cls: type[_TypeStrategyT], 

224 ) -> Iterable[tuple[type[_TypeStrategyT], NominalTypeMember | None]]: 

225 """Derive nominal members from the existing registered declarations.""" 

226 for strategy_type in cls.registered_strategy_types(): 

227 yield strategy_type, strategy_type.value_type 

228 

229 @classmethod 

230 def order_nominal_strategy_members( 

231 cls: type[_TypeStrategyT], 

232 value_type: type[Any], 

233 members: Iterable[tuple[type[_TypeStrategyT], NominalTypeMember | None]], 

234 ) -> tuple[type[_TypeStrategyT], ...]: 

235 """Order derived operation members using the family's existing MRO law.""" 

236 value_mro = value_type.mro() 

237 matches: list[tuple[int, type[_TypeStrategyT]]] = [] 

238 for strategy_type, member in members: 

239 if _is_nominal_type_member(member) and issubclass(value_type, member): 

240 distance = cls.nominal_type_distance(value_mro, member) 

241 matches.append((distance, strategy_type)) 

242 matches.sort(key=lambda item: item[0]) 

243 return tuple(strategy_type for _, strategy_type in matches) 

244 

245 @staticmethod 

246 def nominal_type_distance( 

247 value_mro: list[type[Any]], 

248 member: NominalTypeMember, 

249 ) -> int: 

250 """Return the MRO distance from a runtime value to a registered member.""" 

251 if isinstance(member, tuple): 

252 return min( 

253 NominalTypeKeyedStrategyMixin.nominal_type_distance(value_mro, item) 

254 for item in member 

255 ) 

256 if member not in value_mro: 

257 return len(value_mro) 

258 return value_mro.index(member) 

259 

260 

261def _is_nominal_type_member(value: object) -> TypeGuard[NominalTypeMember]: 

262 if isinstance(value, type): 

263 return True 

264 return ( 

265 isinstance(value, tuple) and bool(value) and all(isinstance(item, type) for item in value) 

266 ) 

267 

268 

269def _nominal_type_key(value: NominalTypeMember) -> str: 

270 if isinstance(value, tuple): 

271 return "|".join(_nominal_type_key(item) for item in value) 

272 return f"{value.__module__}.{value.__qualname__}" 

273 

274 

275class NominalTypeStrategyFamilyMixin(NominalTypeKeyedStrategyMixin): 

276 """AutoRegisterMeta declaration surface for nominal-type strategy roots.""" 

277 

278 __registry_key__ = RegistryKeyAttribute.VALUE_TYPE_LABEL.value 

279 __skip_if_no_key__ = True 

280 __registry_family__ = RegistryFamily(RegistryKeyAttribute.VALUE_TYPE_LABEL) 

281 value_type: ClassVar[NominalTypeMember | None] = None 

282 value_type_label: ClassVar[str | None] = None 

283 

284 

285class MostDerivedContextStrategyMeta(AutoRegisterMeta): 

286 """Create one registry for each most-derived context strategy family.""" 

287 

288 REGISTRY_KEY = "strategy_key" 

289 FAMILY_ROOT_MARKER = "__most_derived_context_strategy_template__" 

290 

291 def __new__( 

292 mcs: type[MostDerivedContextStrategyMeta], 

293 name: str, 

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

295 attrs: dict[str, Any], 

296 registry_config: RegistryConfig | None = None, 

297 **class_kwargs: Any, 

298 ) -> type: 

299 starts_context_family = any( 

300 base.__dict__.get(mcs.FAMILY_ROOT_MARKER) is True for base in bases 

301 ) 

302 if starts_context_family: 

303 registry_key = attrs.get("__registry_key__", mcs.REGISTRY_KEY) 

304 key_extractor = attrs.get("__key_extractor__") 

305 if key_extractor is None: 

306 key_extractor = next( 

307 ( 

308 getattr(base, "__key_extractor__", None) 

309 for base in bases 

310 if getattr(base, "__key_extractor__", None) is not None 

311 ), 

312 None, 

313 ) 

314 registry = LazyDiscoveryDict() 

315 attrs["__registry__"] = registry 

316 attrs["__registry_key__"] = registry_key 

317 attrs["__skip_if_no_key__"] = True 

318 attrs["__registry_family__"] = RegistryFamily(registry_key) 

319 return super().__new__( 

320 mcs, 

321 name, 

322 bases, 

323 attrs, 

324 registry_config=RegistryConfig( 

325 registry_dict=registry, 

326 key_attribute=registry_key, 

327 key_extractor=key_extractor, 

328 skip_if_no_key=True, 

329 registry_name=f"{name} most-derived context strategy", 

330 ), 

331 **class_kwargs, 

332 ) 

333 return super().__new__( 

334 mcs, name, bases, attrs, registry_config=registry_config, **class_kwargs 

335 ) 

336 

337 

338class MostDerivedContextStrategyMixin( 

339 RegisteredStrategyTypesMixin[Any], 

340 Generic[_ContextT], 

341 ABC, 

342 metaclass=MostDerivedContextStrategyMeta, 

343): 

344 """Mixin for registry families selected by context and strategy inheritance. 

345 

346 Concrete strategies implement ``matches`` and express precedence through 

347 normal Python inheritance. Selection returns the single most-derived 

348 matching implementation, so callers do not need local if/elif chains, 

349 priority numbers, or repeated registry scans. 

350 """ 

351 

352 __registry_key__: ClassVar[str] = "strategy_key" 

353 __skip_if_no_key__: ClassVar[bool] = True 

354 __registry_family__ = RegistryFamily("strategy_key") 

355 __most_derived_context_strategy_template__: ClassVar[bool] = True 

356 strategy_key: ClassVar[Any | None] = None 

357 strategy_key_attr: ClassVar[str] = "strategy_key" 

358 

359 @classmethod 

360 def for_context( 

361 cls: type[_ContextStrategyT], 

362 context: _ContextT, 

363 *, 

364 required: bool = True, 

365 error_subject: str | None = None, 

366 ) -> _ContextStrategyT | None: 

367 """Instantiate the single most-derived registered strategy for context.""" 

368 owning_strategy_types = cls.owning_strategy_types(context) 

369 if not owning_strategy_types: 

370 if not required: 

371 return None 

372 raise ValueError(f"{cls._error_subject(error_subject)} requires a matching strategy.") 

373 if len(owning_strategy_types) != 1: 

374 names = tuple( 

375 cls._strategy_name(strategy_type) for strategy_type in owning_strategy_types 

376 ) 

377 raise ValueError( 

378 f"{cls._error_subject(error_subject)} requires exactly one " 

379 f"most-derived strategy, got {names!r}." 

380 ) 

381 return owning_strategy_types[0].build_for_context(context) 

382 

383 @classmethod 

384 def owning_strategy_types( 

385 cls: type[_ContextStrategyT], 

386 context: _ContextT, 

387 ) -> ContextStrategyTypes[_ContextStrategyT]: 

388 """Return most-derived registered strategies matching ``context``.""" 

389 matching_strategy_types = tuple( 

390 strategy_type 

391 for strategy_type in cls.registered_strategy_types() 

392 if strategy_type.matches_context(context) 

393 ) 

394 return tuple( 

395 candidate_type 

396 for candidate_type in matching_strategy_types 

397 if not any( 

398 other_type is not candidate_type and issubclass(other_type, candidate_type) 

399 for other_type in matching_strategy_types 

400 ) 

401 ) 

402 

403 @classmethod 

404 def _error_subject(cls, explicit_subject: str | None) -> str: 

405 return explicit_subject or cls.__name__ 

406 

407 @classmethod 

408 def _strategy_name(cls, strategy_type: type[_ContextStrategyT]) -> object: 

409 if cls.strategy_key_attr in strategy_type.__dict__: 

410 return strategy_type.__dict__[cls.strategy_key_attr] 

411 return strategy_type.__name__ 

412 

413 @classmethod 

414 def build_for_context( 

415 cls: type[_ContextStrategyT], 

416 context: _ContextT, 

417 ) -> _ContextStrategyT: 

418 """Instantiate this strategy after context selection.""" 

419 del context 

420 return cls() 

421 

422 @classmethod 

423 def matches_context( 

424 cls: type[_ContextStrategyT], 

425 context: _ContextT, 

426 ) -> bool: 

427 """Return whether this strategy owns ``context`` without custom construction.""" 

428 return cls().matches(context) 

429 

430 @abstractmethod 

431 def matches(self, context: _ContextT) -> bool: 

432 """Return whether this registered strategy owns ``context``.""" 

433 

434 

435class AlwaysMatchesContextMixin(Generic[_ContextT]): 

436 """Mixin for terminal context strategies whose match predicate is unconditional.""" 

437 

438 def matches(self, context: _ContextT) -> bool: 

439 del context 

440 return True 

441 

442 

443class RegisteredLeafClassSpec(ABC, metaclass=AutoRegisterMeta): 

444 """Nominal declaration for generated AutoRegisterMeta leaf classes.""" 

445 

446 __registry_family__ = RegistryFamily("declaration_key") 

447 __key_extractor__ = staticmethod(extract_key_from_class_name) 

448 

449 declaration_key: ClassVar[str | None] = None 

450 class_name: str 

451 base_type: type[object] 

452 

453 @abstractmethod 

454 def class_attributes(self) -> Mapping[str, object]: 

455 """Return semantic class attributes for the generated leaf.""" 

456 

457 def declare_in(self, namespace: MutableMapping[str, object]) -> type[object]: 

458 """Materialize the generated leaf in ``namespace`` and return it.""" 

459 class_name = self.class_name 

460 declared_type = type( 

461 class_name, 

462 (self.base_type,), 

463 { 

464 "__module__": namespace.get("__name__", self.base_type.__module__), 

465 **dict(self.class_attributes()), 

466 }, 

467 ) 

468 namespace[class_name] = declared_type 

469 return declared_type 

470 

471 

472def enum_member_with_payload( 

473 enum_type: type[object], 

474 value: object, 

475 *, 

476 payload_attribute: str, 

477 payload: object, 

478) -> object: 

479 """Construct an enum member while attaching one payload attribute.""" 

480 member: Any = object.__new__(enum_type) 

481 member._value_ = value 

482 member.__dict__[payload_attribute] = payload 

483 return member 

484 

485 

486def str_enum_member_with_payload( 

487 enum_type: type[str], 

488 value: str, 

489 *, 

490 payload_attribute: str, 

491 payload: object, 

492) -> str: 

493 """Construct a string enum member while attaching one payload attribute.""" 

494 member = str.__new__(enum_type, value) 

495 enum_member: Any = member 

496 enum_member._value_ = value 

497 enum_member.__dict__[payload_attribute] = payload 

498 return member 

499 

500 

501@dataclass(frozen=True, slots=True) 

502class GeneratedLeafClassSpec(RegisteredLeafClassSpec): 

503 """Concrete generated-leaf declaration with explicit class and base identity.""" 

504 

505 class_name: str 

506 base_type: type[object] 

507 attributes: Mapping[str, object] = field(default_factory=dict, kw_only=True) 

508 

509 def class_attributes(self) -> Mapping[str, object]: 

510 """Return the declared class attributes for this generated leaf.""" 

511 return self.attributes