infinity-data 2.2.1__tar.gz → 3.2.0__tar.gz

infinity_data-3.2.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: infinity-data
+Version: 3.2.0
+Summary: InfinityData：声明式配置语言（.infd/.inft）的 Python 编译器库
+Author: infinity_system: yin_bailiang
+License: MIT
+Project-URL: Repository, https://github.com/yinbailiang/infinity_data
+Project-URL: Documentation, https://github.com/yinbailiang/infinity_data#readme
+Keywords: config,configuration,declarative,dsl,compiler,infinity-data
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: tool
+Requires-Dist: pyyaml; extra == "tool"
+Requires-Dist: tomli-w; extra == "tool"
+Dynamic: license-file
+
+# InfinityData
+
+声明式配置语言（`.infd` / `.inft`）的 Python 编译器库。
+
+- **编译优先**：`.infd` 是源码，JSON/YAML/TOML 是构建产物
+- **模板即约束**：模板定义自动注册为约束校验器
+- **零信任默认**：库默认 `deny_all` 沙盒，显式开放而非事后限制
+- **结构化错误**：稳定错误码 + 结构化参数 + 多语言渲染
+
+## 快速使用
+
+```bash
+uv add infinity_data        # 或 pip install infinity-data
+```
+
+```python
+from infinity_data import load, safe_load, SandboxConfig, Schema
+
+result = load('app.infd')              # 默认零信任
+if result.has_errors:
+    for d in result.diagnostics:
+        print(d.location, d.code, d.message)
+else:
+    print(result.value)                # 降维后的 dict
+```
+
+## 文档导航
+
+| 文档 | 内容 |
+|---|---|
+| [neo_desg.md](./neo_desg.md) | 语言基础设计（语法 / 类型 / 模板 / 约束） |
+| [extra_desg.md](./extra_desg.md) | 库 API / CLI / 生态设计 |
+| [impl_desg.md](./impl_desg.md) | 编译器实现层的取舍与假设 |
+
+## 官方工具
+
+随库内置两个命令行工具（`infd-lsp` 语言服务器 + `infd-cov` 配置转换器），
+零依赖手写 JSON-RPC / emitter，直接消费编译器的公开 API
+（`compile_source` / `parse_source` / `RawTokenizer` / emit / semantic）。
+工具的**可选运行依赖**（PyYAML / tomli-w）由 `tool` extra 提供，一次装齐：
+
+```bash
+uv add 'infinity_data[tool]'   # 可选：!file 的 yaml 导入 + infd-cov -f toml 输出
+```
+
+### 配置转换（infd-cov）
+
+编译 `.infd` / `.inft` → 各种配置格式（YAML / JSON / TOML）：
+
+```bash
+infd-cov app.infd                          # → YAML（stdout，零依赖 emitter）
+infd-cov app.infd out.json -f json         # → JSON 文件
+infd-cov app.infd -f toml                  # → TOML（需 tomli-w，见 tool extra）
+infd-cov app.infd --extract web.spec       # → 点分路径提取
+cat a.infd | infd-cov -f json              # stdin → stdout
+```
+
+- `--format`：`yaml`（默认，零依赖手写 emitter）/ `json` / `toml`
+- `--extract PATH`：点分路径（如 `web.spec.selector`）；空 = 整树
+- `--severity LEVEL`：拒绝阈值（`error`/`warning`/`info`/`debug`/`none`，默认 `error`）
+- `#env: NAME "VALUE"` 声明的变量在当前进程缺失时自动注入虚拟值
+- 演示文件：`examples/app.infd`（干净配置）/ `examples/demo.infd`（含故意错误）
+
+### 语言服务器（LSP）
+
+`infd-lsp`：零依赖手写 JSON-RPC 2.0 over stdio 语言服务器。
+
+```bash
+infd-lsp          # 作为任意 LSP 客户端的后端
+# 或
+python -m infinity_data.tools.lsp
+```
+
+#### 已实现的能力
+
+| 能力 | 说明 |
+|---|---|
+| 诊断 | `didOpen`/`didChange`/`didSave` → `publishDiagnostics`（精确位置 + 稳定错误码 + 中文消息；UTF-16 对齐） |
+| 补全 | 命名空间（`$` 触发）+ 内置约束名 + 当前文件可见模板名 + 模板字段（含必填/可选）+ 语言关键字 |
+| 悬停 | 约束描述、**编译产物预览**（字段/子字段/模板参数，jsonpath 投影）、**被实例化的模板**（模板骨架提示在前 + 实例预览在后）、**`$` 变量值**（定义点与调用点）、模板结构骨架（必填/可选 + description 元数据） |
+| 文档大纲 | `documentSymbol`：模板定义（Class）+ 顶层字段（Property） |
+| 跳转定义 | `definition`：模板调用 / `!from` 导入 / `$` 引用（含跨文件） |
+| 语义令牌 | `semanticTokens`：直接用 `RawTokenizer` 分词（UTF-16 单元对齐；跨行多行字符串按行拆分） |
+| 虚拟环境变量 | 扫描 `#env: NAME "VALUE"` 注释，进程未设置时自动注入虚拟值，避免 `env_not_set` 中止编译 |
+
+#### 在 VS Code 中使用
+
+在项目 `.vscode/settings.json` 里用任意支持自定义 LSP 的扩展（如 `lspConfig`）配置：
+
+```json
+{
+  "lspConfig.servers": [
+    { "language": "infd", "cmd": ["infd-lsp"] },
+    { "language": "inft", "cmd": ["infd-lsp"] }
+  ]
+}
+```
+
+打开 `.infd` / `.inft` 文件即可获得：诊断波浪线 + 语法高亮（semantic tokens）+ 补全 + 悬停 + 大纲 + 跳转定义。
+
+#### 端到端演示
+
+```bash
+uv run python examples/lsp_demo.py   # 自动起服务器 + 走一遍握手 + 打印结果
+```
+
+演示文件在 `examples/demo.infd`（故意含若干错误，展示诊断 / 补全 / 悬停 / 高亮）。
+
+### 虚拟环境变量（`#env` 注释）
+
+`.infd` / `.inft` 里可以用**特殊注释**声明环境变量名和虚拟值，工具（LSP / `infd-cov`）
+在当前进程缺失该变量时自动注入，避免 `env_not_set` 中止编译、吞掉同文件其他诊断：
+
+```infd
+#env: DEEPSEEK_API_KEY "sk-virtual-key"
+!env import DEEPSEEK_API_KEY as ds_key
+```
+
+- 语法：`#env: NAME "VALUE"` —— **变量名在前、虚拟值在后**
+- 真实环境变量优先：进程里已设置时用真实值，只有缺失时才用注释里的虚拟值兜底
+- 动机：`infinity_data` 沙盒在 env 未授权/未设置时会中止编译；用 `#env` 声明兜底后，
+  编辑器/CLI 始终能看到全部诊断（如约束违反、未定义模板）
+
+## 开发
+
+```bash
+uv run pytest -q      # 测试
+uv run ruff check src tests   # lint
+uv run pyright        # 类型检查（strict）
+uv run python test.py # 错误报告演示
+```

infinity_data-3.2.0/README.md

@@ -0,0 +1,131 @@
+# InfinityData
+
+声明式配置语言（`.infd` / `.inft`）的 Python 编译器库。
+
+- **编译优先**：`.infd` 是源码，JSON/YAML/TOML 是构建产物
+- **模板即约束**：模板定义自动注册为约束校验器
+- **零信任默认**：库默认 `deny_all` 沙盒，显式开放而非事后限制
+- **结构化错误**：稳定错误码 + 结构化参数 + 多语言渲染
+
+## 快速使用
+
+```bash
+uv add infinity_data        # 或 pip install infinity-data
+```
+
+```python
+from infinity_data import load, safe_load, SandboxConfig, Schema
+
+result = load('app.infd')              # 默认零信任
+if result.has_errors:
+    for d in result.diagnostics:
+        print(d.location, d.code, d.message)
+else:
+    print(result.value)                # 降维后的 dict
+```
+
+## 文档导航
+
+| 文档 | 内容 |
+|---|---|
+| [neo_desg.md](./neo_desg.md) | 语言基础设计（语法 / 类型 / 模板 / 约束） |
+| [extra_desg.md](./extra_desg.md) | 库 API / CLI / 生态设计 |
+| [impl_desg.md](./impl_desg.md) | 编译器实现层的取舍与假设 |
+
+## 官方工具
+
+随库内置两个命令行工具（`infd-lsp` 语言服务器 + `infd-cov` 配置转换器），
+零依赖手写 JSON-RPC / emitter，直接消费编译器的公开 API
+（`compile_source` / `parse_source` / `RawTokenizer` / emit / semantic）。
+工具的**可选运行依赖**（PyYAML / tomli-w）由 `tool` extra 提供，一次装齐：
+
+```bash
+uv add 'infinity_data[tool]'   # 可选：!file 的 yaml 导入 + infd-cov -f toml 输出
+```
+
+### 配置转换（infd-cov）
+
+编译 `.infd` / `.inft` → 各种配置格式（YAML / JSON / TOML）：
+
+```bash
+infd-cov app.infd                          # → YAML（stdout，零依赖 emitter）
+infd-cov app.infd out.json -f json         # → JSON 文件
+infd-cov app.infd -f toml                  # → TOML（需 tomli-w，见 tool extra）
+infd-cov app.infd --extract web.spec       # → 点分路径提取
+cat a.infd | infd-cov -f json              # stdin → stdout
+```
+
+- `--format`：`yaml`（默认，零依赖手写 emitter）/ `json` / `toml`
+- `--extract PATH`：点分路径（如 `web.spec.selector`）；空 = 整树
+- `--severity LEVEL`：拒绝阈值（`error`/`warning`/`info`/`debug`/`none`，默认 `error`）
+- `#env: NAME "VALUE"` 声明的变量在当前进程缺失时自动注入虚拟值
+- 演示文件：`examples/app.infd`（干净配置）/ `examples/demo.infd`（含故意错误）
+
+### 语言服务器（LSP）
+
+`infd-lsp`：零依赖手写 JSON-RPC 2.0 over stdio 语言服务器。
+
+```bash
+infd-lsp          # 作为任意 LSP 客户端的后端
+# 或
+python -m infinity_data.tools.lsp
+```
+
+#### 已实现的能力
+
+| 能力 | 说明 |
+|---|---|
+| 诊断 | `didOpen`/`didChange`/`didSave` → `publishDiagnostics`（精确位置 + 稳定错误码 + 中文消息；UTF-16 对齐） |
+| 补全 | 命名空间（`$` 触发）+ 内置约束名 + 当前文件可见模板名 + 模板字段（含必填/可选）+ 语言关键字 |
+| 悬停 | 约束描述、**编译产物预览**（字段/子字段/模板参数，jsonpath 投影）、**被实例化的模板**（模板骨架提示在前 + 实例预览在后）、**`$` 变量值**（定义点与调用点）、模板结构骨架（必填/可选 + description 元数据） |
+| 文档大纲 | `documentSymbol`：模板定义（Class）+ 顶层字段（Property） |
+| 跳转定义 | `definition`：模板调用 / `!from` 导入 / `$` 引用（含跨文件） |
+| 语义令牌 | `semanticTokens`：直接用 `RawTokenizer` 分词（UTF-16 单元对齐；跨行多行字符串按行拆分） |
+| 虚拟环境变量 | 扫描 `#env: NAME "VALUE"` 注释，进程未设置时自动注入虚拟值，避免 `env_not_set` 中止编译 |
+
+#### 在 VS Code 中使用
+
+在项目 `.vscode/settings.json` 里用任意支持自定义 LSP 的扩展（如 `lspConfig`）配置：
+
+```json
+{
+  "lspConfig.servers": [
+    { "language": "infd", "cmd": ["infd-lsp"] },
+    { "language": "inft", "cmd": ["infd-lsp"] }
+  ]
+}
+```
+
+打开 `.infd` / `.inft` 文件即可获得：诊断波浪线 + 语法高亮（semantic tokens）+ 补全 + 悬停 + 大纲 + 跳转定义。
+
+#### 端到端演示
+
+```bash
+uv run python examples/lsp_demo.py   # 自动起服务器 + 走一遍握手 + 打印结果
+```
+
+演示文件在 `examples/demo.infd`（故意含若干错误，展示诊断 / 补全 / 悬停 / 高亮）。
+
+### 虚拟环境变量（`#env` 注释）
+
+`.infd` / `.inft` 里可以用**特殊注释**声明环境变量名和虚拟值，工具（LSP / `infd-cov`）
+在当前进程缺失该变量时自动注入，避免 `env_not_set` 中止编译、吞掉同文件其他诊断：
+
+```infd
+#env: DEEPSEEK_API_KEY "sk-virtual-key"
+!env import DEEPSEEK_API_KEY as ds_key
+```
+
+- 语法：`#env: NAME "VALUE"` —— **变量名在前、虚拟值在后**
+- 真实环境变量优先：进程里已设置时用真实值，只有缺失时才用注释里的虚拟值兜底
+- 动机：`infinity_data` 沙盒在 env 未授权/未设置时会中止编译；用 `#env` 声明兜底后，
+  编辑器/CLI 始终能看到全部诊断（如约束违反、未定义模板）
+
+## 开发
+
+```bash
+uv run pytest -q      # 测试
+uv run ruff check src tests   # lint
+uv run pyright        # 类型检查（strict）
+uv run python test.py # 错误报告演示
+```

{infinity_data-2.2.1 → infinity_data-3.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "infinity-data"
-version = "2.2.1"
+version = "3.2.0"
 description = "InfinityData：声明式配置语言（.infd/.inft）的 Python 编译器库"
 readme = "README.md"
 license = { text = "MIT" }
@@ -28,16 +28,33 @@ classifiers = [
 requires-python = ">=3.12"
 dependencies = []
 
+[project.scripts]
+infd-lsp = "infinity_data.tools.lsp.__main__:main"
+infd-cov = "infinity_data.tools.cov.__main__:main"
+
+[project.optional-dependencies]
+# 工具 extra：infd-lsp / infd-cov 的可选运行依赖（uv add 'infinity_data[tool]'）
+tool = [
+    "pyyaml",    # !file 的 yaml/yml 格式导入（LSP / 编译器）
+    "tomli-w",   # infd-cov -f toml 输出
+]
+
 [project.urls]
 Repository = "https://github.com/yinbailiang/infinity_data"
 Documentation = "https://github.com/yinbailiang/infinity_data#readme"
 
 [dependency-groups]
+# 工具组：cli/lsp 工具的可选运行依赖（测试/开发组保证安装，测试可依赖它们存在）
+tool = [
+    "tomli-w",   # infd-cov -f toml 输出
+    "pyyaml",    # !file 的 yaml/yml 格式导入（LSP / 编译器）
+]
 # 测试组：仅运行测试所需（CI test job 只装这组，更快）
 test = [
     "pyyaml",
     "pytest>=8.0",
     "pytest-cov>=5.0",
+    { include-group = "tool" },
 ]
 # 开发组：lint/类型/钩子 + 测试组（本地开发与 CI pre-commit job 装这组）
 dev = [
@@ -95,6 +112,6 @@ venvPath = "."
 venv = ".venv"
 
 [tool.interrogate]
-fail-under = 70
+fail-under = 60
 # 测试函数名自解释，docstring 可选；产品代码（src）不豁免
 ignore-regex = ["^test_"]

infinity_data-3.2.0/src/infinity_data/emit/__init__.py

@@ -0,0 +1,38 @@
+"""产物发射层：Python / std → 输出格式（JSON / YAML / TOML）。
+
+与 semantic 层边界：
+- **内部表示（忠实双向）** → :mod:`infinity_data.semantic.std` 的
+  ``python_to_std`` / ``std_to_python``（path → PurePosixPath、float → Decimal、
+  noexist → :data:`~infinity_data.semantic.std.NOEXIST` 哨兵）
+- **本层（emit，有损投影）** → :func:`to_json` / :func:`to_yaml` / :func:`to_toml`，
+  按 :class:`EmitConfig` 控制 Decimal 编码与 noexist 标记；:func:`project_output`
+  为纯 Python 值的轻量投影；:func:`restore_python` 反向**尝试还原**加载的原始
+  dict 为 :data:`~infinity_data.semantic.std.StdPythonValue`；:func:`yaml_dump`
+  为零依赖 YAML block emitter（覆盖配置常用值，不依赖 PyYAML）
+
+**emit 不应被流水线内部使用**——内部表示一律走 semantic 的忠实转换。
+"""
+
+from infinity_data.emit.config import EmitConfig
+from infinity_data.emit.converter import (
+    dump_to_json,
+    load_from_json,
+    project_output,
+    restore_python,
+    to_json,
+    to_toml,
+    to_yaml,
+)
+from infinity_data.emit.plain_yaml import yaml_dump
+
+__all__ = [
+    'EmitConfig',
+    'dump_to_json',
+    'load_from_json',
+    'project_output',
+    'restore_python',
+    'to_json',
+    'to_toml',
+    'to_yaml',
+    'yaml_dump',
+]

infinity_data-3.2.0/src/infinity_data/emit/config.py

@@ -0,0 +1,37 @@
+"""输出转换配置（emit 层）：控制 std/python → 输出格式的有损投影语义。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ['EmitConfig']
+
+
+@dataclass(frozen=True)
+class EmitConfig:
+    """emit 层输出转换配置。
+
+    转换语义：
+    - ``full_float``：``float`` 值（:class:`decimal.Decimal`）以自描述标记
+      ``{"__type__": "decimal", "num": "<十进制字符串>"}`` 编码（无损）；False 时
+      有限值转普通 JSON 数字，NaN / ±Infinity 无法用 JSON 数字表达 → 仍以标记编码
+    - ``full_path``：路径值（:class:`PurePosixPath`）以自描述标记
+      ``{"__type__": "path", "path": "<POSIX 字符串>"}`` 编码（可辨识「这是路径」）；
+      False 时投影为普通 POSIX 字符串
+    - ``keep_noexist``：``noexist`` 字段保留为 ``{"__type__": "noexist"}`` 标记
+      （依赖 :data:`~infinity_data.semantic.std.NOEXIST` 哨兵保留三态）；默认丢弃
+      （键不出现，§1.6）
+
+    序列化选项：
+    - ``indent`` / ``sort_keys`` / ``ensure_ascii``：JSON 缩进 / 排序 / ASCII 转义
+    """
+
+    # ── 转换语义 ──────────────────────────────────────
+    full_float: bool = False
+    full_path: bool = False
+    keep_noexist: bool = False
+
+    # ── 序列化选项 ────────────────────────────────────
+    indent: int | None = 2
+    sort_keys: bool = False
+    ensure_ascii: bool = False

infinity_data-3.2.0/src/infinity_data/emit/converter.py

@@ -0,0 +1,258 @@
+"""产物发射层：Python / std → 输出格式（JSON / YAML / TOML）。
+
+职责边界（与 semantic 层严格分离）：
+
+- **内部表示**（忠实双向，语义最小丢失）：:func:`~infinity_data.semantic.std.python_to_std`
+  与 :func:`~infinity_data.semantic.std.std_to_python`——path 保持
+  :class:`PurePosixPath`、float 保持 :class:`decimal.Decimal`、noexist 经
+  :data:`~infinity_data.semantic.std.NOEXIST` 哨兵保留三态。
+  流水线内部（如 :class:`~infinity_data.pipeline.CompilationResult.value`）一律走该层。
+- **本层（emit）**：做**有损投影**供输出格式消费，无需担心完整性——
+  path → POSIX 字符串；Decimal 的 NaN / ±Infinity 等特殊编码由本层按
+  :class:`EmitConfig` 决定（``full_float`` 标记编码）。
+
+入口：
+- :func:`to_json` / :func:`to_yaml` / :func:`to_toml`：输出文本（接受 std 或 Python 值）
+- :func:`project_output`：纯 Python 值的轻量有损投影（path → 字符串）
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+from decimal import Decimal, InvalidOperation
+from pathlib import PurePath, PurePosixPath
+from typing import Any, cast
+
+from infinity_data.emit.config import EmitConfig
+from infinity_data.semantic.std import NOEXIST, StdPythonValue, is_std_value, std_to_python
+
+__all__ = [
+    'dump_to_json',
+    'load_from_json',
+    'project_output',
+    'restore_python',
+    'to_json',
+    'to_yaml',
+    'to_toml',
+]
+
+# ── 自描述标记（输出格式无法原生表达的值的编码） ──────
+
+
+def _decimal_marker(dec: Any) -> dict[str, str]:
+    """Decimal 自描述标记：``{"__type__": "decimal", "num": "<十进制字符串>"}``。"""
+    return {'__type__': 'decimal', 'num': str(dec)}
+
+
+def _path_marker(s: str) -> dict[str, str]:
+    """路径自描述标记：``{"__type__": "path", "path": "<POSIX 字符串>"}``。"""
+    return {'__type__': 'path', 'path': s}
+
+
+def _noexist_marker() -> dict[str, str]:
+    """noexist 自描述标记：``{"__type__": "noexist"}``。"""
+    return {'__type__': 'noexist'}
+
+
+# ── 标记还原（反向：加载的原始 dict → StdPythonValue） ────
+
+
+def _restore_marker(value: dict[Any, Any]) -> Any | None:
+    """若 dict 是 emit 自描述标记则还原为 Python 值，否则 None（非标记）。
+
+    仅识别 emit 层产出的**精确标记形状**；结构不符（额外键 / 负载非字符串 /
+    数值无法解析）一律视为普通 dict（返回 None，尽力而为）。
+    """
+    typ = value.get('__type__')
+    if typ == 'decimal':
+        if set(value) == {'__type__', 'num'} and isinstance(value.get('num'), str):
+            try:
+                return Decimal(value['num'])
+            except (InvalidOperation, ValueError, TypeError):
+                return None
+        return None
+    if typ == 'path':
+        if set(value) == {'__type__', 'path'} and isinstance(value.get('path'), str):
+            return PurePosixPath(value['path'])
+        return None
+    if typ == 'noexist':
+        if set(value) == {'__type__'}:
+            return NOEXIST
+        return None
+    return None
+
+
+def restore_python(value: Any) -> StdPythonValue:
+    """从加载的原始 dict（含可选 emit 自描述标记）**尝试**还原为 StdPythonValue。
+
+    - ``{"__type__": "decimal", "num": "..."}`` → :class:`decimal.Decimal`
+    - ``{"__type__": "path", "path": "..."}`` → :class:`PurePosixPath`
+    - ``{"__type__": "noexist"}`` → :data:`NOEXIST`
+    - 普通 ``float`` → :class:`decimal.Decimal`（忠实形式，与
+      :func:`~infinity_data.semantic.std.python_to_std` 规范一致）
+    - int / bool / str / None 原样；dict / list 递归
+    - 识别不了的形状（含疑似标记但结构不符）按普通 dict / list 保留（尽力而为）
+
+    配合 :func:`to_json` 等 + ``EmitConfig(full_float=True, full_path=True,
+    keep_noexist=True)`` 可实现「std → 输出文本 → 加载 → StdPythonValue」
+    无损闭环（再经 :func:`~infinity_data.semantic.std.python_to_std` 回 std）。
+    """
+    if isinstance(value, dict):
+        obj = cast(dict[Any, Any], value)
+        marker = _restore_marker(obj)
+        if marker is not None:
+            return marker
+        return {str(k): restore_python(v) for k, v in obj.items()}
+    if isinstance(value, list):
+        arr = cast(list[Any], value)
+        return [restore_python(v) for v in arr]
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return Decimal(str(value))
+    return value
+
+
+# ── 序列化核心 ──────────────────────────────────────
+
+
+def _to_serializable(value: Any, config: EmitConfig) -> Any:
+    """std 或 Python 值 → 可序列化结构（按 config 做有损投影）。"""
+    if is_std_value(value):
+        # std 输入：忠实转 Python（noexist 按需保留为 NOEXIST 哨兵），再投影
+        py = std_to_python(value, keep_noexist=config.keep_noexist)
+        return _serializable(py, config)
+    # Python 输入（如 CompilationResult.value）：直接投影
+    return _serializable(value, config)
+
+
+def _serializable(value: Any, config: EmitConfig) -> Any:
+    """Python 值 → 可序列化结构（递归有损投影）。
+
+    - :data:`NOEXIST` 哨兵 → ``{"__type__": "noexist"}``
+    - :class:`PurePath` → POSIX 字符串
+    - :class:`decimal.Decimal` → 按 ``full_float`` 编码（有限值默认 JSON 数字）
+    - dict / list 递归；其余（int / bool / str / None 等）原样
+    """
+    if value is NOEXIST:
+        return _noexist_marker()
+    if isinstance(value, PurePath):
+        s = value.as_posix()
+        return _path_marker(s) if config.full_path else s
+    if isinstance(value, dict):
+        obj = cast(dict[Any, Any], value)
+        return {k: _serializable(v, config) for k, v in obj.items()}
+    if isinstance(value, list):
+        arr = cast(list[Any], value)
+        return [_serializable(v, config) for v in arr]
+    if isinstance(value, Decimal):
+        return _decimal_serializable(value, config)
+    return value
+
+
+def _decimal_serializable(dec: Any, config: EmitConfig) -> Any:
+    """Decimal → 可序列化形式。
+
+    - ``full_float`` → 自描述标记（无损）
+    - 否则：有限值 → JSON 数字（整值转 int，避免 ``1.0``；溢出回退标记）；
+      NaN / ±Infinity 无法用 JSON 数字表达 → 自描述标记
+    """
+    if config.full_float:
+        return _decimal_marker(dec)
+    if dec.is_nan() or dec.is_infinite():
+        return _decimal_marker(dec)
+    try:
+        if dec == dec.to_integral_value():
+            return int(dec)
+        return float(dec)
+    except (OverflowError, ValueError):
+        return _decimal_marker(dec)
+
+
+# ── 输出入口 ────────────────────────────────────────
+
+
+def to_json(value: Any, *, config: EmitConfig | None = None) -> str:
+    """std 或 Python 值 → JSON 文本。
+
+    ``value`` 可为 :class:`~infinity_data.semantic.std.StdValue`（如
+    ``CompilationResult.document.root``，支持完整选项）或 Python 值
+    （如 ``CompilationResult.value``，noexist 信息已在转换时丢失）。
+    """
+    cfg = config or EmitConfig()
+    data = _to_serializable(value, cfg)
+    return json.dumps(data, indent=cfg.indent, sort_keys=cfg.sort_keys, ensure_ascii=cfg.ensure_ascii)
+
+
+def to_yaml(value: Any, *, config: EmitConfig | None = None) -> str:
+    """std 或 Python 值 → YAML 文本（需安装 PyYAML）。"""
+    cfg = config or EmitConfig()
+    data = _to_serializable(value, cfg)
+    try:
+        yaml = importlib.import_module('yaml')
+    except ImportError as exc:  # pragma: no cover - 依赖缺失路径
+        raise ImportError('to_yaml 需要 PyYAML（pip install pyyaml）') from exc
+    return yaml.safe_dump(data, allow_unicode=not cfg.ensure_ascii, sort_keys=cfg.sort_keys)
+
+
+def to_toml(value: Any, *, config: EmitConfig | None = None) -> str:
+    """std 或 Python 值 → TOML 文本（需安装 tomli-w）。"""
+    cfg = config or EmitConfig()
+    data = _to_serializable(value, cfg)
+    try:
+        tomli_w = importlib.import_module('tomli_w')
+    except ImportError as exc:  # pragma: no cover - 依赖缺失路径
+        raise NotImplementedError('to_toml 需要 tomli-w（pip install tomli-w）；当前未安装') from exc
+    return tomli_w.dumps(data)
+
+
+# ── 便捷自由函数（默认尝试保留一切语义） ────────────
+
+
+def dump_to_json(value: Any, *, config: EmitConfig | None = None) -> str:
+    """std / Python 值 → JSON 文本（便捷入口，**默认保留一切语义**）。
+
+    默认等价 ``EmitConfig(full_float=True, full_path=True, keep_noexist=True)``——
+    Decimal / PurePosixPath / noexist 以 ``{"__type__": ...}`` 标记编码；
+    传入 ``config`` 可覆盖（关闭标记、改缩进等，见 :class:`EmitConfig`）。
+
+    与 :func:`load_from_json` 配对可实现「std → JSON → StdPythonValue」无损闭环。
+    """
+    cfg = config or EmitConfig(full_float=True, full_path=True, keep_noexist=True)
+    return to_json(value, config=cfg)
+
+
+def load_from_json(text: str) -> StdPythonValue:
+    """JSON 文本 → StdPythonValue（便捷入口，**默认尝试还原全部语义**）。
+
+    解析后经 :func:`restore_python`：``{"__type__": ...}`` 标记还原为
+    Decimal / PurePosixPath / NOEXIST，普通 float 归一到 Decimal；
+    识别不了的形状原样保留（尽力而为）。
+    """
+    return restore_python(json.loads(text))
+
+
+# ── 轻量有损投影（纯 Python 值） ─────────────────────
+
+
+def project_output(value: Any) -> Any:
+    """Python 值 → 输出友好投影（递归，有损，无配置）。
+
+    - :class:`PurePath`（含 :class:`PurePosixPath`）→ POSIX 字符串
+    - dict / list 递归投影；其余（int / Decimal / bool / str / None 等）原样保留
+
+    完整选项（Decimal 编码 / noexist 标记）请用 :func:`to_json` 等带
+    :class:`EmitConfig` 的入口。
+    """
+    if isinstance(value, PurePath):
+        return value.as_posix()
+    if isinstance(value, dict):
+        obj = cast(dict[Any, Any], value)
+        return {k: project_output(v) for k, v in obj.items()}
+    if isinstance(value, list):
+        arr = cast(list[Any], value)
+        return [project_output(v) for v in arr]
+    return value