qq_lib.core.field_coupling

  1# Released under MIT License.
  2# Copyright (c) 2025-2026 Ladislav Bartos and Robert Vacha Lab
  3
  4"""
  5Utilities for defining and enforcing coupled fields in dataclasses.
  6
  7This module provides `FieldCoupling` for specifying dominance-ordered
  8relationships among multiple fields, and the `@coupled_fields` decorator for
  9automatically enforcing these rules in a dataclass's `__post_init__`.
 10"""
 11
 12from typing import Any, Protocol
 13
 14
 15class FieldCoupling:
 16    """
 17    Represents a coupling among multiple fields, ordered by dominance.
 18
 19    The earlier a field appears in `fields`, the more dominant it is.
 20    If multiple fields have values in an instance, only the most dominant
 21    one is preserved; all others are set to None.
 22    """
 23
 24    def __init__(self, *fields: str):
 25        if len(fields) < 2:
 26            raise ValueError("FieldCoupling requires at least two fields")
 27        self.fields = list(fields)
 28
 29    def contains(self, field_name: str) -> bool:
 30        """Return True if the field participates in this coupling."""
 31        return field_name in self.fields
 32
 33    def get_fields(self) -> tuple[str, ...]:
 34        """Return all coupled fields as a tuple."""
 35        return tuple(self.fields)
 36
 37    def has_value(self, instance: Any) -> bool:
 38        """Return True if any of the coupled fields has a non-None value."""
 39        return any(getattr(instance, field) is not None for field in self.fields)
 40
 41    def get_most_dominant_set_field(self, instance: Any) -> str | None:
 42        """
 43        Return the name of the most dominant field that has a non-None value,
 44        or None if none of them do.
 45        """
 46        for field in self.fields:
 47            if getattr(instance, field) is not None:
 48                return field
 49
 50        return None
 51
 52    def enforce(self, instance: Any):
 53        """
 54        Enforce dominance rules: only the most dominant field that is set
 55        keeps its value; others are reset to None.
 56        """
 57        dominant_set_field = self.get_most_dominant_set_field(instance)
 58        if dominant_set_field is None:
 59            return
 60
 61        for field in self.fields:
 62            if field != dominant_set_field:
 63                setattr(instance, field, None)
 64
 65
 66def coupled_fields(*couplings: FieldCoupling):
 67    """
 68    Class decorator that enforces multi-field coupling rules in __post_init__.
 69    """
 70
 71    def decorator(cls):
 72        cls._field_couplings = couplings
 73        original_post_init = getattr(cls, "__post_init__", None)
 74
 75        def __post_init__(self):
 76            for coupling in self._field_couplings:
 77                coupling.enforce(self)
 78
 79            if original_post_init:
 80                original_post_init(self)
 81
 82        @staticmethod
 83        def get_coupling_for_field(field_name: str) -> FieldCoupling | None:
 84            for coupling in cls._field_couplings:
 85                if coupling.contains(field_name):
 86                    return coupling
 87
 88            return None
 89
 90        cls.__post_init__ = __post_init__
 91        cls.get_coupling_for_field = get_coupling_for_field
 92        return cls
 93
 94    return decorator
 95
 96
 97class HasCouplingMethods(Protocol):
 98    """Protocol for classes decorated with @coupled_fields."""
 99
100    _field_couplings: tuple[FieldCoupling, ...]
101
102    @staticmethod
103    def get_coupling_for_field(field_name: str) -> FieldCoupling | None:
104        """Return the FieldCoupling that contains the given field name, or None."""
105        ...