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
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-17 00:39 +0000
1"""Strategy-family mixins for ``AutoRegisterMeta`` registries.
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"""
9from __future__ import annotations
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
18from .core import (
19 AutoRegisterMeta,
20 LazyDiscoveryDict,
21 RegistryConfig,
22 RegistryFamily,
23 RegistryKeyAttribute,
24 extract_key_from_class_name,
25)
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], ...]
39NominalTypeMember = type[Any] | tuple[type[Any], ...]
42_FAMILY_PROJECTION_RESETS: list[Callable[[], None]] = []
43_ProjectionT = TypeVar("_ProjectionT", bound=Callable[..., Any])
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)
53def _invalidate_family_projections() -> None:
54 for reset in _FAMILY_PROJECTION_RESETS:
55 reset()
58class RegisteredStrategyTypesMixin(Generic[_MemberT]):
59 """Shared projection of an AutoRegisterMeta registry into concrete classes."""
61 __registry__: ClassVar[Mapping[Any, type[Any]]]
63 def __init_subclass__(cls, **kwargs: Any) -> None:
64 super().__init_subclass__(**kwargs)
65 _invalidate_family_projections()
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 )
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
86class StrategyLabelRegistryMixin:
87 """Shared AutoRegister protocol for strategy roots keyed by strategy_label."""
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
95class EnumKeyedStrategyMixin(Generic[_EnumT]):
96 """Mixin for AutoRegisterMeta ABC families keyed by enum member values.
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 """
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
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)
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())
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])
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.
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())
156class NominalTypeKeyedStrategyMixin(RegisteredStrategyTypesMixin[_TypeStrategyT]):
157 """Mixin for strategies selected by nominal runtime value types.
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 """
164 value_type: ClassVar[NominalTypeMember | None] = None
165 value_type_label: ClassVar[str | None] = None
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)
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]())
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)
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)
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 )
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
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)
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)
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 )
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__}"
275class NominalTypeStrategyFamilyMixin(NominalTypeKeyedStrategyMixin):
276 """AutoRegisterMeta declaration surface for nominal-type strategy roots."""
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
285class MostDerivedContextStrategyMeta(AutoRegisterMeta):
286 """Create one registry for each most-derived context strategy family."""
288 REGISTRY_KEY = "strategy_key"
289 FAMILY_ROOT_MARKER = "__most_derived_context_strategy_template__"
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 )
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.
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 """
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"
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)
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 )
403 @classmethod
404 def _error_subject(cls, explicit_subject: str | None) -> str:
405 return explicit_subject or cls.__name__
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__
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()
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)
430 @abstractmethod
431 def matches(self, context: _ContextT) -> bool:
432 """Return whether this registered strategy owns ``context``."""
435class AlwaysMatchesContextMixin(Generic[_ContextT]):
436 """Mixin for terminal context strategies whose match predicate is unconditional."""
438 def matches(self, context: _ContextT) -> bool:
439 del context
440 return True
443class RegisteredLeafClassSpec(ABC, metaclass=AutoRegisterMeta):
444 """Nominal declaration for generated AutoRegisterMeta leaf classes."""
446 __registry_family__ = RegistryFamily("declaration_key")
447 __key_extractor__ = staticmethod(extract_key_from_class_name)
449 declaration_key: ClassVar[str | None] = None
450 class_name: str
451 base_type: type[object]
453 @abstractmethod
454 def class_attributes(self) -> Mapping[str, object]:
455 """Return semantic class attributes for the generated leaf."""
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
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
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
501@dataclass(frozen=True, slots=True)
502class GeneratedLeafClassSpec(RegisteredLeafClassSpec):
503 """Concrete generated-leaf declaration with explicit class and base identity."""
505 class_name: str
506 base_type: type[object]
507 attributes: Mapping[str, object] = field(default_factory=dict, kw_only=True)
509 def class_attributes(self) -> Mapping[str, object]:
510 """Return the declared class attributes for this generated leaf."""
511 return self.attributes