infinity-data 1.0.0__py3-none-any.whl

infinity_data/__init__.py

@@ -0,0 +1,41 @@
+"""InfinityData —— 声明式配置语言（.infd/.inft）的 Python 编译器库。
+
+编译流水线：RawTokenizer → FinalTokenizer → Parser → AstBuilder → Executor → Converter
+
+用法::
+
+    from infinity_data import load, safe_load, SandboxConfig, Schema
+
+    result = safe_load("app.infd")
+    if result.has_errors:
+        for d in result.diagnostics:
+            print(d.location, d.message)
+    else:
+        print(result.value)
+"""
+
+from infinity_data.infra.diagnostics import Diagnostic, Severity
+from infinity_data.pipeline import (
+    CompilationResult,
+    check,
+    compile_document,
+    compile_source,
+    load,
+    safe_load,
+)
+from infinity_data.sandbox import SandboxConfig, SandboxError, Schema, SchemaError
+
+__all__ = [
+    'compile_source',
+    'load',
+    'safe_load',
+    'check',
+    'compile_document',
+    'CompilationResult',
+    'SandboxConfig',
+    'SandboxError',
+    'Schema',
+    'SchemaError',
+    'Diagnostic',
+    'Severity',
+]

infinity_data/emit/__init__.py

@@ -0,0 +1,9 @@
+"""产物发射层：StdAst → 宿主表示（Python dict / list / 标量）。
+
+语义分析（semantic/）负责"值是否正确"，本层负责"产物长什么样"。
+M4 的 JSON/YAML/TOML 转换、M5 的 JSON Schema 生成均在此层扩展。
+"""
+
+from infinity_data.emit.converter import reduce_array, reduce_object, reduce_value
+
+__all__ = ['reduce_array', 'reduce_object', 'reduce_value']

infinity_data/emit/converter.py

@@ -0,0 +1,55 @@
+"""降维器：StdAst → 纯 Python 值（dict / list / 标量）。
+
+- ``noexist`` 字段不出现在输出中
+- ``null`` 字段保留键（值为 None），``keep_null=False`` 时跳过
+- 浮点保持 :class:`decimal.Decimal`（无限精度）；NaN / ±Infinity 以 Decimal 表示，
+  JSON/YAML 序列化时的特殊编码由 M4 转换层负责
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from infinity_data.semantic.builder.models import StdArray, StdLiteral, StdObject, StdValue
+
+
+def reduce_object(obj: StdObject, *, keep_null: bool = True) -> dict[str, Any]:
+    """将 StdObject 降维为 Python dict。"""
+    result: dict[str, Any] = {}
+    for f in obj.fields:
+        if f.value is None or f.is_noexist:
+            continue
+        if f.is_null:
+            if keep_null:
+                result[f.name] = None
+            continue
+        result[f.name] = reduce_value(f.value, keep_null=keep_null)
+    return result
+
+
+def reduce_array(arr: StdArray, *, keep_null: bool = True) -> list[Any]:
+    """将 StdArray 降维为 Python list。"""
+    return [reduce_value(v, keep_null=keep_null) for v in arr.elements]
+
+
+def reduce_value(val: StdValue, *, keep_null: bool = True) -> Any:
+    """将任意 StdValue 降维为 Python 原生值。"""
+    match val:
+        case StdLiteral():
+            return _reduce_literal(val)
+        case StdArray():
+            return reduce_array(val, keep_null=keep_null)
+        case StdObject():
+            return reduce_object(val, keep_null=keep_null)
+    raise TypeError(f'未知 StdValue 类型: {type(val)}')
+
+
+# ── 内部 ────────────────────────────────────────────────
+
+
+def _reduce_literal(lit: StdLiteral) -> Any:
+    match lit.kind:
+        case 'null' | 'noexist':
+            return None
+        case _:
+            return lit.value

infinity_data/frontend.py

@@ -0,0 +1,37 @@
+"""前端流水线：源码 File → RawAst Document + 前端诊断（容错收集）。
+
+供 :mod:`pipeline`（主文件）与 :mod:`semantic.resolver`（外部模板文件）共用，
+消除两处重复的 RawTokenizer → FinalTokenizer → Parser 组装。
+"""
+
+from infinity_data.infra.diagnostics import DiagnosticCollector
+from infinity_data.infra.file import File
+from infinity_data.parser import Document
+from infinity_data.parser.parser import Parser
+from infinity_data.tokenizer.finalizer import FinalTokenizer
+from infinity_data.tokenizer.tokenizer import RawTokenizer
+
+__all__ = ['parse_source']
+
+
+def parse_source(
+    file: File,
+    collector: DiagnosticCollector | None = None,
+) -> tuple[Document, DiagnosticCollector]:
+    """词法 + 语法分析，返回 RawAst Document 与生效收集器。
+
+    容错：词法/语法错误经 :class:`DiagnosticCollector` 收集而非抛出。
+    传入 ``collector`` 时三阶段（RawTokenizer / FinalTokenizer / Parser）全程
+    复用同一收集器并**原样返回**（非副本）；缺省时内部新建并返回。
+    返回值第二元素为生效收集器，可直接查询 errors / warnings / has_errors。
+    """
+    if collector is None:
+        collector = DiagnosticCollector()
+
+    raw_tokens = RawTokenizer(file=file, error_collector=collector)
+    tokens = FinalTokenizer(raw_tokens, error_collector=collector)
+    parser = Parser(tokens, error_collector=collector)
+    doc = parser.parse()
+
+    # 词法/语法错误统一为 Diagnostic（纯数据，直接聚合）
+    return doc, collector

infinity_data/infra/__init__.py

@@ -0,0 +1,4 @@
+from infinity_data.infra.diagnostics import Diagnostic, DiagnosticCollector, Severity
+from infinity_data.infra.ll1_stream import LL1Stream
+
+__all__ = ['Diagnostic', 'DiagnosticCollector', 'Severity', 'LL1Stream']

infinity_data/infra/diagnostics.py

@@ -0,0 +1,212 @@
+"""统一诊断模型（所有阶段共用）与容错收集器。
+
+- :class:`Severity` / :class:`Diagnostic`：稳定错误码 + 结构化参数 + 渲染消息。
+  词法/语法/语义阶段统一使用；沙盒异常（见 :mod:`infinity_data.sandbox.errors`）
+  经 ``check()`` 边界转换为 Diagnostic。
+- :class:`DiagnosticCollector`：前端容错收集器（词法/语法错误作为 Diagnostic
+  收集，从不抛异常）。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Mapping
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from infinity_data.infra.location import SourceRange, format_location
+
+__all__ = [
+    'DEFAULT_LANG',
+    'Severity',
+    'Diagnostic',
+    'DiagnosticDefine',
+    'diagnostic_define',
+    'register_diagnostic_define',
+    'render_message',
+    'DiagnosticCollector',
+]
+
+DEFAULT_LANG = 'zh'
+"""默认渲染语言。"""
+
+
+class Severity(Enum):
+    """诊断严重级别。"""
+
+    ERROR = 'error'
+    WARNING = 'warning'
+    INFO = 'info'
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """统一诊断：稳定错误码 + 结构化参数 + 渲染消息。
+
+    - ``code``：稳定错误码（如 ``"template.undefined"``），测试/工具据此匹配
+    - ``params``：结构化参数；``message`` 为派生属性，由注册表按语言渲染
+    - ``lang``：渲染语言（None = 默认语言）；模板缺失时回退默认语言
+    """
+
+    severity: Severity
+    code: str
+    params: Mapping[str, Any] = field(default_factory=dict[str, Any])
+    source: SourceRange | None = None
+    path: str = ''
+    lang: str | None = None
+
+    @property
+    def location(self) -> str:
+        return format_location(self.source)
+
+    @property
+    def message(self) -> str:
+        """按错误码 + 参数 + 语言渲染的人类可读消息。"""
+        return render_message(
+            self.code, self.params, location=self.location, path=self.path, lang=self.lang or DEFAULT_LANG
+        )
+
+    def sort_key(self) -> tuple[str, int, int]:
+        """按源码位置排序。"""
+        if self.source is None:
+            return ('\uffff', 0, 0)
+        s = self.source.start
+        return (self.source.file.name, s.line, s.col)
+
+
+@dataclass(frozen=True)
+class DiagnosticDefine:
+    """诊断定义：稳定错误码 + 语言模板。
+
+    - ``code``：稳定错误码（如 ``"template.undefined"``）
+    - ``template``：默认语言（``DEFAULT_LANG``）模板
+    - ``translations``：其他语言模板（语言码 → 模板），缺失时回退默认模板
+    """
+
+    code: str
+    template: str
+    translations: Mapping[str, str] = field(default_factory=dict[str, str])
+
+    def template_for(self, lang: str = DEFAULT_LANG) -> str:
+        """取指定语言的模板；缺失回退默认模板。"""
+        if lang == DEFAULT_LANG:
+            return self.template
+        return self.translations.get(lang, self.template)
+
+
+_DIAGNOSTIC_DEFINE_REGISTRY: dict[str, DiagnosticDefine] = {}
+"""诊断定义注册表（code → 定义）。"""
+
+
+def diagnostic_define(code: str, template: str, **translations: str) -> DiagnosticDefine:
+    """构造诊断定义（``translations`` 为其他语言模板，如 ``en=...``）。"""
+    return DiagnosticDefine(code=code, template=template, translations=translations)
+
+
+def register_diagnostic_define(*defines: DiagnosticDefine) -> None:
+    """注册诊断定义（重复 code 后者覆盖）。"""
+    for d in defines:
+        _DIAGNOSTIC_DEFINE_REGISTRY[d.code] = d
+
+
+def registered_diagnostic_defines() -> Mapping[str, DiagnosticDefine]:
+    """已注册定义表（只读视图）。"""
+    return _DIAGNOSTIC_DEFINE_REGISTRY
+
+
+def render_message(
+    code: str,
+    params: Mapping[str, Any],
+    *,
+    location: str = '<unknown>',
+    path: str = '',
+    lang: str = DEFAULT_LANG,
+) -> str:
+    """按错误码 + 参数 + 语言渲染消息；未知错误码原样返回错误码本身。"""
+    d = _DIAGNOSTIC_DEFINE_REGISTRY.get(code)
+    if d is None:
+        return code
+    template = d.template_for(lang)
+    context: dict[str, Any] = {
+        'location': location,
+        'path': path,
+        'path_prefix': f'{path}: ' if path else '',
+        **params,
+    }
+    try:
+        return template.format(**context)
+    except (KeyError, IndexError, ValueError, AttributeError):
+        return code
+
+
+class DiagnosticCollector:
+    """诊断收集器：收集 :class:`Diagnostic`（词法/语法/语义阶段容错收集）。
+
+    词法/语法/语义阶段不抛异常：错误以 Diagnostic 形式收集，边界处直接聚合。
+    只读查询按 severity 分离：``errors`` / ``warnings`` / ``diagnostics``，
+    ``has_errors`` 仅当含 ERROR 级别时成立（warning 不算错误）。
+
+    用法::
+
+        collector = DiagnosticCollector()
+        tokenizer = RawTokenizer(file, error_collector=collector)
+        ...
+        for err in collector:
+            print(err.code)
+    """
+
+    def __init__(self) -> None:
+        self._errors: list[Diagnostic] = []
+
+    # ── 写入 ──────────────────────────────────────────
+
+    def add(self, error: Diagnostic) -> None:
+        """添加一个诊断。"""
+        self._errors.append(error)
+
+    def extend(self, errors: Iterable[Diagnostic]) -> None:
+        """批量添加诊断。"""
+        self._errors.extend(errors)
+
+    # ── 只读查询（severity 感知：warning 与 error 语义分离） ──
+
+    @property
+    def diagnostics(self) -> list[Diagnostic]:
+        """全部诊断的副本（含 ERROR / WARNING）。"""
+        return self._errors.copy()
+
+    @property
+    def errors(self) -> list[Diagnostic]:
+        """仅 ERROR 级别诊断的副本（warning 不算错误）。"""
+        return [d for d in self._errors if d.severity is Severity.ERROR]
+
+    @property
+    def warnings(self) -> list[Diagnostic]:
+        """仅 WARNING 级别诊断的副本。"""
+        return [d for d in self._errors if d.severity is Severity.WARNING]
+
+    @property
+    def has_errors(self) -> bool:
+        """是否含 ERROR 级别诊断（与 :class:`CompilationResult` 的 has_errors 语义一致）。"""
+        return any(d.severity is Severity.ERROR for d in self._errors)
+
+    @property
+    def has_warnings(self) -> bool:
+        """是否含 WARNING 级别诊断。"""
+        return any(d.severity is Severity.WARNING for d in self._errors)
+
+    # ── 容器协议 ──────────────────────────────────────
+
+    def __iter__(self) -> Iterator[Diagnostic]:
+        """迭代所有已收集的诊断。"""
+        return iter(self._errors)
+
+    def __len__(self) -> int:
+        """已收集诊断数量（容器协议）。
+
+        空收集器为 falsy（``bool(collector)`` = 是否收集到任何诊断，含 warning；
+        区别于 ``has_errors`` 的"是否含 ERROR"）——
+        因此缺省构造**不可用 ``error_collector or DiagnosticCollector()``**：
+        空收集器会被 `or` 判定为假而静默替换，丢弃调用方传入的收集器。
+        """
+        return len(self._errors)

infinity_data/infra/file.py

@@ -0,0 +1,83 @@
+"""源码来源抽象：磁盘文件与内存源码统一为 :class:`File`。
+
+编译入口（``load`` / ``compile_source``）与模板导入链（``!from``）都消费 File：
+
+- ``name``：诊断显示名（``file:line:col`` 中的 file）
+- ``root_path``：相对导入解析基准（所在目录）
+- ``read()``：源码内容
+- ``chars()``：逐字符迭代流（词法分析输入）
+- ``identity``：唯一身份（磁盘 = resolve 后绝对路径；内存 = ``路径:mem:内容hash``）；模板身份（TemplateKey）基于它，含来源路径
+- ``content_hash()``：内容 sha256 前缀（MemFile 身份的一部分 / 内容校验）
+"""
+
+import hashlib
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+__all__ = ['File', 'DiskFile', 'MemFile']
+
+
+@dataclass(frozen=True)
+class File:
+    """源码来源基类。"""
+
+    name: str
+    root_path: Path
+
+    def read(self) -> str:
+        """读取源码内容。"""
+        raise NotImplementedError
+
+    def chars(self) -> Iterable[str]:
+        """逐字符迭代流（词法分析输入）。"""
+        return iter(self.read())
+
+    @property
+    def identity(self) -> str:
+        """唯一身份（循环导入防护 / 模板身份（TemplateKey）基础，含来源路径）。"""
+        raise NotImplementedError
+
+    def content_hash(self) -> str:
+        """内容 sha256 前缀（MemFile 身份的一部分；内容校验，非模板身份本身）。"""
+        return hashlib.sha256(self.read().encode('utf-8')).hexdigest()[:12]
+
+
+@dataclass(frozen=True)
+class DiskFile(File):
+    """磁盘文件。path 为单一事实来源；name/root_path 由构造方从它派生。"""
+
+    @property
+    def path(self) -> Path:
+        return Path(self.name)
+
+    def read(self) -> str:
+        return self.path.read_text(encoding='utf-8')
+
+    @property
+    def identity(self) -> str:
+        return str(self.path.resolve())
+
+    @classmethod
+    def from_fullpath(cls, fullpath: str | Path) -> 'DiskFile':
+        """从完整路径构造（与调用点一致的规范化入口）。"""
+        p = Path(fullpath)
+        return cls(name=str(p), root_path=p.parent)
+
+
+@dataclass(frozen=True)
+class MemFile(File):
+    """内存源码（测试/嵌入式场景）。身份 = 根路径:mem:内容hash（含路径）。"""
+
+    content: str
+
+    def read(self) -> str:
+        return self.content
+
+    def chars(self) -> Iterable[str]:
+        """逐字符迭代流（O(1) 构造，直连内容）。"""
+        return iter(self.content)
+
+    @property
+    def identity(self) -> str:
+        return str(self.root_path.resolve()) + ':mem:' + self.content_hash()

infinity_data/infra/ll1_stream.py

@@ -0,0 +1,71 @@
+"""泛型 LL(1) 流包装器 —— 对任意 Iterable[T] 提供单元素预读能力。"""
+
+from collections.abc import Iterable, Iterator
+from typing import Generic, TypeVar
+
+
+class UnSetType:
+    def __repr__(self) -> str:
+        return 'UnSet'
+
+
+UnSet = UnSetType()
+
+
+class NoNextType:
+    def __repr__(self) -> str:
+        return 'NoNext'
+
+
+NoNext = NoNextType()
+
+
+T = TypeVar('T')
+
+
+class LL1Stream(Generic[T]):
+    """泛型 LL(1) 流：对任意 Iterable[T] 提供单元素预读"""
+
+    def __init__(self, source: Iterable[T]) -> None:
+        self._iter: Iterator[T] | None = None
+        self._next: T | NoNextType | UnSetType = UnSet
+        self._source: Iterable[T] = source
+
+    def peek(self) -> T | NoNextType:
+        """返回当前预读元素，首次访问时自动懒初始化。"""
+        self._ensure_buf()
+        assert not isinstance(self._next, UnSetType)
+        return self._next
+
+    def eof(self) -> bool:
+        """是否已到达末尾（首次访问时自动懒初始化）。"""
+        self._ensure_buf()
+        return isinstance(self._next, NoNextType)
+
+    def advance(self) -> T:
+        """消费当前元素，步进并预读下一个。"""
+        self._ensure_buf()
+        item = self._next
+        if isinstance(item, NoNextType):
+            raise IndexError('无法在 EOF 之后继续推进流')
+        self._pre_read()
+        assert not isinstance(item, UnSetType)
+        self._on_advance(item)
+        return item
+
+    def _ensure_buf(self) -> None:
+        """懒初始化：首次访问时创建迭代器并预读第一个元素。"""
+        if self._iter is None:
+            self._iter = iter(self._source)
+        if self._next is UnSet:
+            self._pre_read()
+
+    def _pre_read(self) -> None:
+        """从 _iter 预读下一个元素到 _next。"""
+        assert self._iter is not None
+        try:
+            self._next = next(self._iter)
+        except StopIteration:
+            self._next = NoNext
+
+    def _on_advance(self, item: T) -> None: ...

infinity_data/infra/location.py

@@ -0,0 +1,80 @@
+"""源码位置类型（所有阶段共用）。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from infinity_data.infra.file import File
+
+__all__ = ['SourceInfo', 'SourceRange', 'format_location']
+
+
+def format_location(source: SourceRange | None) -> str:
+    """格式化源码位置（无位置时为 ``<unknown>``）。
+
+    - 零宽 range（start == end）→ ``file:line:col``
+    - 非零宽 range → ``file:line:col-line:col``（起止区间）
+
+    :class:`Diagnostic` 与沙盒异常共用，消除重复的格式化逻辑。
+    """
+    if source is None:
+        return '<unknown>'
+    s = source.start
+    base = f'{source.file.name}:{s.line}:{s.col}'
+    if s == source.end:
+        return base
+    e = source.end
+    return f'{base}-{e.line}:{e.col}'
+
+
+class _UnknownFile(File):
+    """无源码来源的占位（仅 :meth:`SourceRange.empty` 使用，位置域私有概念）。"""
+
+    def read(self) -> str:
+        return ''
+
+    @property
+    def identity(self) -> str:
+        return '<unknown>'
+
+    def content_hash(self) -> str:
+        return '<unknown>'
+
+
+_UNKNOWN_FILE = _UnknownFile(name='<unknown>', root_path=Path())
+
+
+@dataclass
+class SourceInfo:
+    """源码位置信息（纯位置，不含来源）。"""
+
+    line: int
+    col: int
+    index: int
+
+
+@dataclass
+class SourceRange:
+    """源码位置范围（区间）：来源文件 + 起止位置。
+
+    词法阶段使用零宽 range（start == end）。
+    """
+
+    file: File
+    start: SourceInfo
+    end: SourceInfo
+
+    @classmethod
+    def empty(cls) -> SourceRange:
+        """无来源占位（错误恢复、合成 token）。"""
+        return cls(
+            file=_UNKNOWN_FILE,
+            start=SourceInfo(line=0, col=0, index=0),
+            end=SourceInfo(line=0, col=0, index=0),
+        )
+
+    @classmethod
+    def at(cls, file: File, pos: SourceInfo) -> SourceRange:
+        """单点位置 → 零宽 range（词法阶段错误定位用）。"""
+        return cls(file=file, start=pos, end=pos)

infinity_data/infra/path.py

@@ -0,0 +1,46 @@
+"""跨平台路径通行：语言内 POSIX 路径 ↔ 当前平台原生路径。
+
+语言约定（见 neo_desg.md 3.2）：
+- 语言内**只允许** POSIX 风格路径（``/`` 分割），Windows 盘符写作 ``/c/...``（小写单字母）
+- 访问文件系统时按当前平台**自动映射**，同一份 .infd 在 linux/windows/mac 均可用
+
+函数：
+- :func:`posix_to_native`：语言内 POSIX 路径 → 原生 :class:`Path`（Windows 上盘符映射）
+- :func:`native_to_posix`：原生路径 → 语言内 POSIX 形式（glob 白名单匹配用）
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path, PurePosixPath, PureWindowsPath
+
+__all__ = ['posix_to_native', 'native_to_posix']
+
+
+def posix_to_native(path: str, *, platform: str | None = None) -> Path:
+    """语言内 POSIX 路径 → 当前平台原生 Path。
+
+    - POSIX（linux/mac）：原样使用
+    - Windows：``/c/foo/bar`` → ``C:/foo/bar``（盘符转大写）；相对路径由 pathlib 转换分隔符
+    - ``platform`` 可注入（默认 ``sys.platform``），便于跨平台单测
+    """
+    if (platform or sys.platform).lower().startswith('win'):
+        pure = PurePosixPath(path)
+        if pure.is_absolute() and len(pure.parts) >= 2 and len(pure.parts[1]) == 1 and pure.parts[1].isalpha():
+            drive = pure.parts[1].upper() + ':'
+            rest = PurePosixPath(*pure.parts[2:]).as_posix()
+            return Path(f'{drive}/{rest}')
+    return Path(path)
+
+
+def native_to_posix(path: Path) -> str:
+    """原生路径 → 语言内 POSIX 形式（``/`` 分割；Windows 盘符转 ``/c/`` 小写）。
+
+    glob 白名单按语言内 POSIX 形式匹配，保证跨平台一致。
+    """
+    win = PureWindowsPath(path)
+    if win.drive:
+        drive_letter = win.drive[0].lower()
+        rest = PurePosixPath(*win.parts[1:]).as_posix()
+        return f'/{drive_letter}/{rest}'
+    return path.as_posix()