infinity-data 1.0.0__py3-none-any.whl

infinity_data/semantic/registry/__init__.py

@@ -0,0 +1,168 @@
+"""约束注册表：内置约束 + 用户自定义（模板即约束）。
+
+- 表驱动：每个约束登记 ``(name, fn, min_args, max_args, description)``
+- 内置约束按类别拆分子模块：types / general / dict_constraints / logic，
+  注册表在此组装（单注册表 = 唯一执行入口）
+- ``executor`` 回调支持嵌套约束：``each`` / ``not`` / ``any`` / ``one`` /
+  ``all`` / ``when`` / ``field`` / 模板约束
+- M5 将在 :class:`ConstraintEntry` 上追加 json_schema 生成回调，
+  实现「模板即约束 → JSON Schema」的单注册表复用
+"""
+
+from __future__ import annotations
+
+from infinity_data.semantic.builder.models import ResolvedConstraint, StdValue
+from infinity_data.semantic.registry._core import (
+    ConstraintEntry,
+    ConstraintFn,
+    ConstraintResult,
+    Executor,
+    describe,
+    fail_result,
+    ok_result,
+)
+from infinity_data.semantic.registry.dict_constraints import _check_field, _check_has
+from infinity_data.semantic.registry.general import (
+    _check_each,
+    _check_email,
+    _check_eq,
+    _check_hostname,
+    _check_in,
+    _check_ip,
+    _check_ip4,
+    _check_ip6,
+    _check_negative,
+    _check_nonnegative,
+    _check_positive,
+    _check_range,
+    _check_regex,
+    _check_size,
+    _check_unique,
+    _check_url,
+    _check_uuid,
+)
+from infinity_data.semantic.registry.logic import (
+    _check_all,
+    _check_any,
+    _check_not,
+    _check_one,
+    _check_when,
+)
+from infinity_data.semantic.registry.types import (
+    _check_bool,
+    _check_dict,
+    _check_float,
+    _check_int,
+    _check_list,
+    _check_nullable,
+    _check_object,
+    _check_str,
+)
+from infinity_data.tokenizer.models.raw_tokens import SourceRange
+
+__all__ = [
+    'ConstraintRegistry',
+    'ConstraintResult',
+    'ConstraintEntry',
+    'ConstraintFn',
+    'Executor',
+    'ok_result',
+    'fail_result',
+    'describe',
+]
+
+
+class ConstraintRegistry:
+    """约束注册表：内置约束 + 用户自定义（模板即约束）。"""
+
+    def __init__(self) -> None:
+        self._entries: dict[str, ConstraintEntry] = {}
+        self._register_builtins()
+
+    def register(
+        self,
+        name: str,
+        fn: ConstraintFn,
+        *,
+        min_args: int = 0,
+        max_args: int | None = None,
+        description: str = '',
+    ) -> None:
+        self._entries[name] = ConstraintEntry(
+            name=name,
+            fn=fn,
+            min_args=min_args,
+            max_args=max_args,
+            description=description,
+        )
+
+    def lookup(self, name: str) -> ConstraintEntry | None:
+        return self._entries.get(name)
+
+    @property
+    def names(self) -> list[str]:
+        return list(self._entries)
+
+    def apply(
+        self,
+        constraint: ResolvedConstraint,
+        value: StdValue | None,
+        source: SourceRange | None,
+        path: str,
+        executor: Executor,
+    ) -> ConstraintResult:
+        """按名称执行约束（含参数个数校验）。"""
+        entry = self._entries.get(constraint.name)
+        if entry is None:
+            return fail_result('constraint.unknown', {'name': constraint.name}, source, path)
+        n = len(constraint.args)
+        if n < entry.min_args or (entry.max_args is not None and n > entry.max_args):
+            expected = str(entry.min_args) if entry.max_args is None else f'{entry.min_args}~{entry.max_args}'
+            return fail_result(
+                'constraint.arg_count', {'name': constraint.name, 'expected': expected, 'given': n}, source, path
+            )
+        return entry.fn(value, source, path, constraint.args, executor)
+
+    def _register_builtins(self) -> None:
+        """注册 neo_desg.md §1.2 全部内置约束。"""
+        # ── 类型约束 ──────────────────────────────
+        self.register('object', _check_object, description='通用超类型，总是通过')
+        self.register('?', _check_nullable, description='纯可空类型：noexist 或 null')
+        self.register('int', _check_int, description='有符号整数')
+        self.register('float', _check_float, description='十进制浮点（只接受 float，不含 int 提升）')
+        self.register('str', _check_str, description='utf-8 字符串')
+        self.register('bool', _check_bool, description='布尔值')
+        self.register('list', _check_list, description='数组')
+        self.register('dict', _check_dict, description='字典')
+
+        # ── 一般约束 ──────────────────────────────
+        self.register('range', _check_range, min_args=1, max_args=2, description='数值范围 range(ge[, le])，可省略一端')
+        self.register('size', _check_size, min_args=1, max_args=2, description='集合大小或字符串长度 size(ge[, le])')
+        self.register('each', _check_each, min_args=1, max_args=1, description='每个元素均满足 each(constraint)')
+        self.register('in', _check_in, min_args=1, description='值在给定选项中 in(choice, ...)')
+        self.register('ip', _check_ip, description='IPv4 或 IPv6 地址')
+        self.register('ip4', _check_ip4, description='IPv4 地址')
+        self.register('ip6', _check_ip6, description='IPv6 地址')
+        self.register('regex', _check_regex, min_args=1, max_args=1, description='正则全匹配 regex("re")')
+        self.register('email', _check_email, description='邮箱格式')
+        self.register('url', _check_url, description='URL 格式')
+        self.register('uuid', _check_uuid, description='UUID 格式')
+        self.register('hostname', _check_hostname, description='主机名格式')
+        self.register('positive', _check_positive, description='正数 (> 0)')
+        self.register('negative', _check_negative, description='负数 (< 0)')
+        self.register('nonnegative', _check_nonnegative, description='非负数 (>= 0)')
+        self.register('eq', _check_eq, min_args=1, max_args=1, description='等于指定值 eq(value)')
+        self.register('unique', _check_unique, description='集合元素不重复')
+
+        # ── 字典约束 ──────────────────────────────
+        self.register('has', _check_has, min_args=1, max_args=1, description='包含指定键 has(key)')
+        self.register('field', _check_field, min_args=2, max_args=2, description='字段约束 field(name, constraint)')
+
+        # ── 逻辑约束 ──────────────────────────────
+        self.register('not', _check_not, min_args=1, max_args=1, description='内部约束不满足则满足')
+        self.register('any', _check_any, min_args=1, description='任意子约束满足')
+        self.register('one', _check_one, min_args=1, description='恰好一个子约束满足')
+        self.register('all', _check_all, min_args=1, description='全部子约束满足')
+        self.register(
+            'when', _check_when, min_args=2, max_args=2, description='条件满足时要求另一约束满足 when(cond, req)'
+        )

infinity_data/semantic/registry/_core.py

@@ -0,0 +1,212 @@
+"""约束核心类型与共享辅助（注册表包的内部基础层）。
+
+- 执行结果 / 嵌套回调协议 / 登记项
+- 人类可读描述与数值、嵌套参数辅助
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from decimal import Decimal, InvalidOperation
+from typing import Any, Protocol, cast
+
+from infinity_data.infra.diagnostics import Diagnostic, Severity
+from infinity_data.semantic.builder.models import (
+    ResolvedConstraint,
+    StdArray,
+    StdField,
+    StdLiteral,
+    StdObject,
+    StdValue,
+)
+from infinity_data.tokenizer.models.raw_tokens import SourceRange
+
+# ═══════════════════════════════════════════════════════════
+# 基础类型
+# ═══════════════════════════════════════════════════════════
+
+
+@dataclass
+class ConstraintResult:
+    """约束执行结果（只校验，不转换值）。"""
+
+    ok: bool
+    diagnostics: list[Diagnostic] = field(default_factory=list[Diagnostic])
+
+
+class Executor(Protocol):
+    """嵌套约束执行回调（由 ConstraintExecutor 提供）。"""
+
+    def __call__(
+        self,
+        constraint: ResolvedConstraint,
+        value: StdValue | None,
+        source: SourceRange | None,
+        path: str,
+    ) -> ConstraintResult: ...
+
+
+ConstraintFn = Callable[
+    [StdValue | None, SourceRange | None, str, list[Any], Executor],
+    ConstraintResult,
+]
+
+
+@dataclass
+class ConstraintEntry:
+    """约束登记项。"""
+
+    name: str
+    fn: ConstraintFn
+    min_args: int = 0
+    max_args: int | None = None
+    description: str = ''
+
+
+def ok_result() -> ConstraintResult:
+    """构造通过结果。"""
+    return ConstraintResult(ok=True)
+
+
+def fail_result(
+    code: str,
+    params: Mapping[str, Any],
+    source: SourceRange | None,
+    path: str,
+) -> ConstraintResult:
+    """构造结构化失败结果（code + params，message 由注册表渲染）。"""
+    return ConstraintResult(
+        ok=False,
+        diagnostics=[
+            Diagnostic(severity=Severity.ERROR, code=code, params=dict(params), source=source, path=path),
+        ],
+    )
+
+
+# ═══════════════════════════════════════════════════════════
+# 共享辅助
+# ═══════════════════════════════════════════════════════════
+
+
+def describe(val: StdValue | None) -> str:
+    """人类可读的值描述。"""
+    if val is None:
+        return '无值'
+    if isinstance(val, StdLiteral):
+        return f'{val.kind}({val.value!r})'
+    if isinstance(val, StdArray):
+        return f'list[{len(val.elements)}]'
+    return f'dict[{len(val.fields)}]'
+
+
+def as_number(val: StdValue | None) -> Decimal | None:
+    """字面量 → 数值（int/float kind 才有效）。"""
+    if isinstance(val, StdLiteral) and val.kind in ('int', 'float'):
+        v = val.value
+        if isinstance(v, int):
+            return Decimal(v)
+        if isinstance(v, Decimal):
+            return v
+    return None
+
+
+def as_str(val: StdValue | None) -> str | None:
+    """字面量 → 字符串（str kind 才有效）。"""
+    if isinstance(val, StdLiteral) and val.kind == 'str':
+        v = val.value
+        return v if isinstance(v, str) else None
+    return None
+
+
+def as_decimal_arg(a: Any) -> Decimal | None:
+    """约束参数 → Decimal（int / Decimal 才有效；NaN 视为无效参数）。"""
+    if isinstance(a, bool):
+        return None
+    if isinstance(a, int):
+        return Decimal(a)
+    if isinstance(a, Decimal):
+        # Decimal 比较遇 NaN 会抛 InvalidOperation（默认 trap），此处拒绝 NaN 参数
+        return None if a.is_nan() else a
+    return None
+
+
+def safe_equal(a: Any, b: Any) -> bool:
+    """安全相等比较：Decimal NaN 参与比较会抛 InvalidOperation，视为不相等。"""
+    try:
+        return bool(a == b)
+    except InvalidOperation:
+        return False
+
+
+def std_equal(a: StdValue | None, b: StdValue | None) -> bool:
+    """StdValue 结构相等（直接工作在 Std 节点上，不经 Python 降维）。
+
+    语义：
+    - 字面量：kind 相同且值相等；int/float 数值交叉相等（eq(42) 对 float 42 成立）
+    - bool 与 int 不相等（避免 Python ``True == 1`` 陷阱）
+    - NaN 与任何值不相等（IEEE 754）
+    - 数组：等长且逐元素相等
+    - 对象：等字段集且逐字段值相等（与字段顺序无关）
+    """
+    if a is None or b is None:
+        return a is b
+    if isinstance(a, StdLiteral) and isinstance(b, StdLiteral):
+        if a.kind == b.kind:
+            return safe_equal(a.value, b.value)
+        if {a.kind, b.kind} == {'int', 'float'}:
+            na = as_number(a)
+            nb = as_number(b)
+            if na is not None and nb is not None:
+                return safe_equal(na, nb)
+        return False
+    if isinstance(a, StdArray) and isinstance(b, StdArray):
+        if len(a.elements) != len(b.elements):
+            return False
+        return all(std_equal(x, y) for x, y in zip(a.elements, b.elements))
+    if isinstance(a, StdObject) and isinstance(b, StdObject):
+        if len(a.fields) != len(b.fields):
+            return False
+        for f in a.fields:
+            other = b.get(f.name)
+            if other is None or not std_equal(f.value, other.value):
+                return False
+        return True
+    return False
+
+
+def as_std_value(v: Any) -> StdValue:
+    """约束参数（Python 值）→ StdValue（与值同构后比较）。"""
+    if v is None:
+        return StdLiteral(kind='null', value=None)
+    if isinstance(v, bool):
+        return StdLiteral(kind='bool', value=v)
+    if isinstance(v, int):
+        return StdLiteral(kind='int', value=v)
+    if isinstance(v, Decimal):
+        return StdLiteral(kind='float', value=v)
+    if isinstance(v, str):
+        return StdLiteral(kind='str', value=v)
+    if isinstance(v, (list, tuple)):
+        items = cast(list[Any], v)
+        return StdArray(elements=[as_std_value(e) for e in items])
+    if isinstance(v, dict):
+        mapping = cast(dict[Any, Any], v)
+        return StdObject(fields=[StdField(name=str(k), value=as_std_value(e)) for k, e in mapping.items()])
+    return StdLiteral(kind='str', value=str(v))
+
+
+def as_spec(arg: Any) -> ResolvedConstraint | None:
+    """嵌套参数 → 约束规格（ResolvedConstraint 或裸名字符串）。"""
+    if isinstance(arg, ResolvedConstraint):
+        return arg
+    if isinstance(arg, str):
+        return ResolvedConstraint(name=arg)  # pyright: ignore[reportCallIssue]
+    return None
+
+
+def spec_name(arg: Any) -> str:
+    """取参数的约束名（has/field 的第一个参数是裸名字）。"""
+    if isinstance(arg, ResolvedConstraint):
+        return arg.name
+    return str(arg)

infinity_data/semantic/registry/dict_constraints.py

@@ -0,0 +1,56 @@
+"""内置字典约束：has / field。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from infinity_data.semantic.builder.models import StdObject
+from infinity_data.semantic.registry._core import (
+    ConstraintResult,
+    Executor,
+    fail_result,
+    ok_result,
+)
+from infinity_data.semantic.registry._core import (
+    as_spec as _as_spec,
+)
+from infinity_data.semantic.registry._core import (
+    spec_name as _spec_name,
+)
+from infinity_data.tokenizer.models.raw_tokens import SourceRange
+
+__all__ = ['_check_has', '_check_field']
+
+
+def _check_has(
+    val: Any,
+    source: SourceRange | None,
+    path: str,
+    args: list[Any],
+    executor: Executor,
+) -> ConstraintResult:
+    if not isinstance(val, StdObject):
+        return fail_result('constraint.has_only', {}, source, path)
+    key = _spec_name(args[0])
+    if val.get(key) is not None:
+        return ok_result()
+    return fail_result('constraint.has_missing', {'key': key}, source, path)
+
+
+def _check_field(
+    val: Any,
+    source: SourceRange | None,
+    path: str,
+    args: list[Any],
+    executor: Executor,
+) -> ConstraintResult:
+    if not isinstance(val, StdObject):
+        return fail_result('constraint.field_only', {}, source, path)
+    name = _spec_name(args[0])
+    spec = _as_spec(args[1])
+    if spec is None:
+        return fail_result('constraint.field_need', {}, source, path)
+    f = val.get(name)
+    if f is None:
+        return fail_result('constraint.field_missing', {'field': name}, source, path)
+    return executor(spec, f.value, source, f'{path}.{name}')