chronaxis.core.types

源码基线：8904c2f744951857659abd40aaa3535d57faf53c

1"""定义信号类型、时间坐标、三值条件和质量原因，供模型及计算层共用。23模型接收明确的枚举成员；质量原因以固定的整数位保存，允许组合已知位，4拒绝未知位。Truth区分条件成立、不成立和无法确定三种结果，禁止直接转为5Python布尔值。SignalDType声明值类型，TimeType区分相对坐标与UTC绝对坐标。6本模块只依赖标准库，不读取数据或文件，不持有会话状态；SourceType当前7只描述内存输入。8"""910# 严格位边界防止未知质量位被误认为已校验策略。11from enum import Enum, FlagBoundary, IntFlag121314class Truth(Enum):15    """保存条件成立、不成立或无法确定的三种结果。1617    TRUE和FALSE表示已有充分证据；UNKNOWN表示缺失、过期或无法有效求值。18    成员不可变，任何成员都禁止隐式转为Python布尔值，调用者须明确处理三种结果。19    """2021    TRUE = "true"  # 已知且条件成立。22    FALSE = "false"  # 已知且条件不成立。23    UNKNOWN = "unknown"  # 缺失、过期或无法有效求值。2425    def __bool__(self) -> bool:26        """阻止三个枚举成员被Python统一当作True。2728        参数: 无额外参数；当前三值结果。29        返回: 无正常返回；须显式比较Truth成员。30        异常: TypeError；三值逻辑尚未由普通Python bool表达。31        """32        # 对TRUE/FALSE也统一拒绝，避免逻辑分支误用枚举默认真值。33        raise TypeError("Truth不能隐式转bool，请显式处理TRUE/FALSE/UNKNOWN")343536class QualityFlag(IntFlag, boundary=FlagBoundary.STRICT):37    """用固定整数位保存样本无效或质量受限的原因。3839    多个原因可以组合；基础策略拒绝所有非零位。NONE表示没有记录原因，40    仍需结合valid判断有效性。最高位为256，数组至少需要16位保存全部标志；41    构造时拒绝负值和未知位。42    """4344    NONE = 0  # 没有已记录原因，不证明来源能力完整。45    MISSING = 1  # 缺少所需观测。46    STALE = 2  # 观测超过有效期。47    DECODE_ERROR = 4  # 来源解析或解码失败。48    NONFINITE = 8  # 数值NaN或无穷。49    OUT_OF_RANGE = 16  # 超过明确业务范围。50    ESTIMATED = 32  # 显式估计值，首版基础策略也禁止。51    OVERFLOW = 64  # 定宽运算上溢或下溢，回绕结果不能作为有效值。52    PRECISION_LOSS = 128  # 不能精确表示的数值转换。53    DOMAIN_ERROR = 256  # 除零等值域错误。5455    @classmethod56    def _missing_(cls, value):57        """检查候选质量位值，再由标准库构造合法的位组合。5859        参数:60            value: 没有对应单一成员的候选位值；合法组合必须是非负整数。61        返回:62            QualityFlag或None: 合法组合由IntFlag构造；其他输入遵循标准库协议。63        异常:64            ValueError: 候选值为负数、包含未知位或不能构造为合法质量值。65        """66        # STRICT仍会归一化负值；须在该标准库过程之前显式拒绝。67        if isinstance(value, int) and value < 0:68            # -512不能被隐藏为NONE，非法原因不进入有效模型。69            raise ValueError("quality mask必须非负")70        # 非负已知组合沿用标准位构造，未知正位由STRICT拒绝。71        return super()._missing_(value)727374# 普通信号的基础策略固定拒绝全部九种非零质量位；不通过计划身份元组传递策略。75BASE_FORBIDDEN_QUALITY = int(QualityFlag(511))7677# 仅供已通过模型/输入边界检查的内部位合并使用。固定512项，不随会话增长；78# 外部整数仍必须调用QualityFlag，不能用tuple索引的负数语义接受非法位。79_QUALITY_BY_MASK = tuple(QualityFlag(mask) for mask in range(BASE_FORBIDDEN_QUALITY + 1))808182class SignalDType(Enum):83    """声明信号值的逻辑类型，供模型和数值运算检查使用。8485    整数明确分为int64和uint64，浮点使用float64。bool独立于整数，enum使用86    显式标签域；类型不会根据Python继承关系或NumPy自动类型提升推断。87    """8889    INT64 = "int64"  # 有符号64位整数。90    UINT64 = "uint64"  # 无符号64位整数。91    FLOAT64 = "float64"  # 有限双精度浮点，不隐式转大整数。92    BOOL = "bool"  # 明确布尔值，不按任意数值的Python真值判断。93    ENUM = "enum"  # 显式枚举标签，不参与一般数值运算。949596class TimeType(Enum):97    """区分相对来源坐标和UTC绝对坐标，保留显式起点依据。9899    不读取机器时区，不自动把相对0当作UTC epoch。100    """101102    RELATIVE = "relative"  # 需要来源声明origin。103    ABSOLUTE = "absolute"  # 已规范化UTC epoch纳秒。104105106class SourceType(Enum):107    """标明当前内存模型接受的数据来源种类。108109    MEMORY表示调用者直接提供已转换为纳秒的内存行。本枚举没有可变注册表，110    不会因为声明一个外部来源名称就自动读取或解码该来源。111    """112113    MEMORY = "memory"  # 已声明纳秒的内存行，不执行旧读写或解码。114