mopr 0.0.70__tar.gz → 0.0.71.dev10__tar.gz

{mopr-0.0.70 → mopr-0.0.71.dev10}/AGENTS.md

@@ -92,6 +92,8 @@ mopr 同一语义的多语言实现遵循固定的**角色与演进顺序**，
   - `encoding/csv.h` → `MOPR_ENCODING_CSV_H`；`encoding/charsets.h` → `MOPR_ENCODING_CHARSETS_H`；
   - `distributed/id/hlc.h` → `MOPR_DISTRIBUTED_ID_HLC_H`；`base/strings.h` → `MOPR_BASE_STRINGS_H`。
 - 守卫宏与 `#pragma once` 并存；`#endif` 行以注释回写宏名（如 `#endif // MOPR_ENCODING_CSV_H`）。
+- **平台宏一律走 `base/feature_detection.h`**：C++ 侧**禁止**裸写 `_WIN32` / `__linux__` / `__APPLE__` / `_MSC_VER` / `__clang__` / `__aarch64__` / `_M_X64` 等编译器与平台原生宏，改用该头带 `MOPR_` 前缀的检测宏（`MOPR_OS_IS_WINDOWS` / `MOPR_OS_IS_LINUX` / `MOPR_OS_IS_APPLE` / `MOPR_COMPILER_IS_MSVC` / `MOPR_COMPILER_IS_CLANG` / `MOPR_COMPILER_IS_GNU_LIKE` / `MOPR_CPU_IS_X86_64` / `MOPR_CPU_IS_ARM_64` / `MOPR_ENDIAN_LITTLE` 等）。`base/feature_detection.h` 是全仓**唯一**允许裸写原生宏的文件（它必须，否则无从检测）；编译期能定的放这里，运行期收敛（函数包装）放 `base/platform.h`。理由：无前缀的 `OS_IS_*` / `TARGET_*` / `FORCE_INLINE` 与 Boost、Qt 等第三方存在撞名风险，且未定义宏在 `#if` 中静默求值为 0——拼错不报错、只会静默走错分支。
+  - 替换既有裸宏须逐处确认语义等价，**不可机械替换**：`defined(__GNUC__) && !defined(_MSC_VER)`（GNU 扩展属性是否可用）**不能**写成 `MOPR_COMPILER_IS_GCC`（会漏掉 clang，且在 clang-cl 下语义相反），应写 `MOPR_COMPILER_IS_GNU_LIKE`；只判 `MOPR_CPU_IS_ARM_64` 而漏掉编译器判断，会让 MSVC ARM64 误入 GNU 内联汇编分支。
 - 新增公共头文件一律遵循上述规则。既有不合规处按模块逐个收敛（`runtime::*` → `mopr::runtime::*`、`base/filesystem.h` 的 `filesystem` → `mopr::base::filesystem`、`base/except.h` 的 `quant1x` → `mopr::base`、`base/mmap.h` 的全局 `file_mmap` / `mmap_open` / `mmap_flush` / `mmap_close` → `mopr::base` 内的 `MmapHandle` / `mmap_open` / `mmap_flush` / `mmap_close`），不做一次性大范围改名。
 - **公开符号命名跨语言一致**（同一语义在各语言同名，便于跨语言对照与回溯）：
   - **snake_case 优先（铁律）**：只要目标语言允许小写蛇形，公开函数名就**必须**用 snake_case，**不得**用驼峰（lowerCamel / PascalCase）。此处"跨语言一致"指**语义名一致**，不是字形一致——**禁止**拿"要与某语言同名"当作 Python / C++ 保留驼峰的理由：
@@ -107,7 +109,7 @@ mopr 同一语义的多语言实现遵循固定的**角色与演进顺序**，
   - **句柄操作遵循语言惯例**：Python / Rust / Go 用句柄方法（`flush` / `close`、`Flush` / `Close`），C++ 句柄是 POD，用同名自由函数（`mmap_flush` / `mmap_close`）与之一一对应。
   - **同一语义可同时提供「公开 API + RAII 类」两层**：第一层为跨平台公开 API（如 `mmap_open` / `mmap_flush` / `mmap_close` + 句柄），资源由调用方显式管理；第二层为跨语言同名的 RAII 类（如 `MappedMemory`：`MappedMemory.open` 打开，析构 / `Drop` / `with` / `defer` 自动释放）。两层共用同一实现、语义必须一致，区别仅在释放时机；模块文档须给出两层对照表（示例见 `base/mmap.md`「1. 分层与命名」）。
   - **RAII 类名不得与模块名重复**：类名不叫 `mmap` / `Mmap`（与模块名、包名重复，且易被误读为句柄），统一用其语义名（如 `MappedMemory`），并跨语言同名；句柄另用 `XxxHandle`（如 `MmapHandle`，四语言同名，C++ 亦为 `struct MmapHandle`）。
-- 已知遗留（需按模块逐一评估，勿批量替换）：`base/common.h` 的全局 typedef 与常量（`i8` / `u8` / … 为标量别名、非结构体 typedef，不适用 `mopr_` 前缀约定），`base/format.h` 的全局探测模板与 `std::vector` 的 `operator<<`（依赖 ADL / 非限定查找，移入命名空间会导致使用方找不到），`tests/` 下 `*_test_types` 等测试辅助命名空间。
+- 已知遗留（需按模块逐一评估，勿批量替换）：`base/types.h` 的跨语言标量别名（`i8` / `u8` / … 为逐字符对齐 Rust 原生整型名而保留，是标量别名、非结构体 typedef，不适用 `mopr_` 前缀约定；由原 `base/common.h` 的全局 typedef 收敛而来，仅用于有 `.rs` 对照实现的模块，勿把现有 `int64_t` 批量改写为 `i64`），`base/format.h` 的全局探测模板与 `std::vector` 的 `operator<<`（依赖 ADL / 非限定查找，移入命名空间会导致使用方找不到），`tests/` 下 `*_test_types` 等测试辅助命名空间。
 
 ## 测试规范
 

{mopr-0.0.70/mopr.egg-info → mopr-0.0.71.dev10}/PKG-INFO

@@ -1,159 +1,159 @@
-Metadata-Version: 2.4
-Name: mopr
-Version: 0.0.70
-Summary: Monorepo Optimal Portable Runtime
-Author: Quant1X
-Author-email: Quant1X <wangfengxy@sina.cn>
-License-Expression: AGPL-3.0-only
-Project-URL: Homepage, https://github.com/quant1x/mopr
-Keywords: monorepo,portable-runtime,benchmark,performance
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: loguru>=0.7.3
-Requires-Dist: python-dotenv>=1.0.0
-Requires-Dist: pandas>=2.1.0
-Requires-Dist: apscheduler~=3.11.3
-Requires-Dist: PyYAML>=6.0
-Requires-Dist: requests>=2.32.0
-Dynamic: license-file
-
-# MOPR
-
-> **单仓最优可移植运行时**
-> *Monorepo Optimal Portable Runtime*
->
-> 统一规范，基准驱动，**性能第一，正确与稳定是隐含前提**。
->
-> 读作 *M-O-P-R*（或 *mopr*，/mɑpr/）。
-
----
-
-## 项目简介
-
-MOPR 是在统一规范约束下，以多轮基准测试为验证手段，从所有异构实现中筛选并维护性能最优运行时解的项目。它不是“基础库”，也不是“标准实现”——它的定位是**标杆实现**：为同一份规范下的其他实现提供可量化的性能参照与验证基准。
-
-### 核心概念
-
-| 概念 | 定义 | 职责 |
-| --- | --- | --- |
-| Spec | 规范 | 定义行为契约与接口边界，划定实现必须遵守的范围 |
-| Benchmark | 基准测试 | 以多轮、多维度的量化测试验证实现，产出排名依据 |
-| MOPR | 标杆实现 | 满足 Spec 与 Benchmark 验证的前提下，性能最优的实现 |
-
-## 设计原则
-
-### 1. 性能第一，正确与稳定是隐含前提
-
-性能是优化方向与排名依据的第一优先级。正确性与稳定性并非与性能并列的取舍维度，而是参与性能排名的前置条件：不满足正确性与稳定性验证的实现，不具备参与性能排名的资格。
-
-每一轮基准测试同时覆盖三个维度：
-
-- **正确性**：输出是否符合 Spec 定义的行为契约
-- **稳定性**：长时间运行、压力与边界条件下是否可靠
-- **性能**：在前两者满足的前提下，是否达到最优
-
-正确性与稳定性作为过滤条件，性能作为排序依据。
-
-### 2. Spec 统一，实现自由
-
-Spec 定义行为契约与接口边界。同一份规范下允许存在多种异构实现，MOPR 是其中经过多轮基准测试反复验证、在目标平台上始终正确且性能最优的实现，作为其他实现的对标基准。
-
-### 3. 基准测试是设计驱动力
-
-每个设计决策都必须回答一个问题：**该改动是否提升性能？** 其成立前提是不得破坏正确性与稳定性——若基准数据改善但正确性或稳定性测试失败，则该改动不成立。
-
-### 4. 可移植性不等于性能下限
-
-MOPR 在不同平台上分别追求该平台能达到的最高性能，而非让所有平台退化为同一套低性能通用实现。平台相关的极致优化是核心策略，但每份平台实现都必须先通过正确性与稳定性验证。
-
-## 基准测试体系
-
-基准测试套件按验证目标分为四类：
-
-| 目录 | 类型 | 验证目标 |
-| --- | --- | --- |
-| `benchmark/micro/` | 微基准 | 吞吐、延迟、内存占用 |
-| `benchmark/macro/` | 场景基准 | 端到端性能 |
-| `benchmark/stability/` | 稳定性测试 | 长时间运行、压力、边界条件 |
-| `benchmark/regression/` | 回归检测 | 性能劣化监测 |
-
-只有通过正确性与稳定性验证的实现，其性能数据才纳入排名与对照。
-
-## 项目结构
-
-```
-mopr/
-├── spec/           # 规范定义
-│   ├── api.md      # 接口契约
-│   └── behavior.md # 行为语义
-├── base/           # 基础组件：cache / mem / mmap / cron / timestamp ...
-├── runtime/        # 运行时：ringbuffer / scheduler / once ...
-├── distributed/    # 分布式：id（HLC / 生成器 / 状态存储）
-├── encoding/       # 编码：csv / charsets / json / base64 / barcode ...
-├── storage/        # 存储抽象
-├── security/       # 安全：auth / audit / compliance
-├── machine/        # 机器标识
-├── log/            # 日志
-├── finance/        # 金融：forex / exchange
-├── benchmark/      # 基准测试套件
-│   ├── micro/      # 微基准：吞吐、延迟、内存
-│   ├── macro/      # 场景基准：端到端性能
-│   ├── stability/  # 稳定性：长时间运行、压力、边界
-│   └── regression/ # 性能回归检测
-├── tests/          # 跨语言测试用例
-├── docs/           # 设计决策记录
-│   └── proposals/  # 提案（RFC）：跨语言语义 / 契约变更的决策过程
-└── tools/          # 辅助工具（许可审计、许可证头）
-```
-
-**仓库根即实现根**：不设 `src/` 层，功能模块目录直接平铺在仓库根，同一功能的多语言实现共处同一目录、同名不同后缀（如 `base/mmap.py` / `base/mmap.h` / `base/mmap.rs` / `base/mmap/mmap.go`；各语言入口 `main.cpp` / `main.rs` 同样平铺在根）。
-
-- **与 Go 的 package 对齐**：Go 的包边界以目录划分，功能模块目录因此与 Go 的 `package` 一一对应（`distributed/id` 即 `package id`）；C++ 命名空间第二级（`distributed/id/hlc.h` → `mopr::distributed::id`）、Python 子模块路径、Rust `mod` 路径均取自同一目录路径，保证同一功能在各语言的模块语义相同。
-- **平台无关核心与平台极致优化就地组织**：核心语义落在各模块的公共实现中，平台相关优化留在同一模块内，按文件名后缀（`_posix` / `_windows` / `_unsupported`）或条件编译区分，不另设 `core/` / `platform/` 目录。
-
-这些约定只服务一件事：**让同一语义在各语言占据同一位置**——看到 `mmap.py`，顺手就能看到 `mmap.h` / `mmap.rs` / `mmap/mmap.go`，跨语言对照不必先找路径。完整论证（层级为何由语言工具链决定、按语言分目录为何是反例、对 AI 的友好之处）见 [docs/directory-layout-rationale.md](docs/directory-layout-rationale.md)。
-
-## 语言与版本要求
-
-MOPR 是单仓多语言库（monolibrary），同一份规范下将来会有多种语言实现。各语言的版本基线由本项目独立维护，不要求与同系列 `quant1x` 仓库同步：
-
-| 语言 | 最低版本 | 推荐版本 |
-| --- | --- | --- |
-| Python | 3.12+ | 3.12.x |
-| C++ | C++20 | GCC 13+ / Clang 17+ / MSVC 14.3+ |
-| Rust | 1.98.1+ | 1.98.1+（2024 edition） |
-| Go | 1.27+ | 1.27.x |
-| Java | 8+ | JDK 8 及以上（见 `pom.xml` 的 `java.version`） |
-
-- 当前仓库实现以 **C++20 + MSVC v143（Visual Studio 2022）+ CMake（≥3.25）/ Conan 2** 为主，构建细节见 [BUILDING.md](BUILDING.md)。
-- 后续新增 Python / Rust / Go / Java 实现时，须遵循上表最低版本基线，不得使用低于基线的语言特性与 API；版本表变更由本项目独立评估。
-
-## 快速开始
-
-当前 C++ 工程（CMake + Conan 2）的构建与编译步骤见 [BUILDING.md](BUILDING.md)。
-
-```text
-// TODO: 基准运行示例，待接口定义完成后补充
-```
-
-## 项目状态与路线图
-
-🚧 早期阶段 — Spec 正在起草中，实现尚未稳定。
-
-当前推进顺序：
-
-1. 起草 Spec：确定 `spec/api.md`（接口契约）与 `spec/behavior.md`（行为语义）
-2. 搭建基准测试套件与验证流程
-3. 基于平台无关核心实现首个基准实现
-4. 开展平台相关优化，并逐平台完成正确性、稳定性与性能验证
-
-## License / 协议
-
-本项目采用 **GNU Affero General Public License v3**（[AGPL-3.0](LICENSE) / SPDX: `AGPL-3.0-only`）授权。
-
-- 允许自由使用、复制、修改与再分发，但派生作品必须同样以 AGPLv3 发布（强 Copyleft）。
-- 通过网络提供服务的修改版本（含远程交互）须按第 13 条向用户开放对应源码。
-- 完整条款见根目录 [LICENSE](LICENSE) 文件。
-
-Copyright (C) 2026 Quant1X <wangfengxy@sina.cn>
+Metadata-Version: 2.4
+Name: mopr
+Version: 0.0.71.dev10
+Summary: Monorepo Optimal Portable Runtime
+Author: Quant1X
+Author-email: Quant1X <wangfengxy@sina.cn>
+License-Expression: AGPL-3.0-only
+Project-URL: Homepage, https://github.com/quant1x/mopr
+Keywords: monorepo,portable-runtime,benchmark,performance
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pandas>=2.1.0
+Requires-Dist: apscheduler~=3.11.3
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: requests>=2.32.0
+Dynamic: license-file
+
+# MOPR
+
+> **单仓最优可移植运行时**
+> *Monorepo Optimal Portable Runtime*
+>
+> 统一规范，基准驱动，**性能第一，正确与稳定是隐含前提**。
+>
+> 读作 *M-O-P-R*（或 *mopr*，/mɑpr/）。
+
+---
+
+## 项目简介
+
+MOPR 是在统一规范约束下，以多轮基准测试为验证手段，从所有异构实现中筛选并维护性能最优运行时解的项目。它不是“基础库”，也不是“标准实现”——它的定位是**标杆实现**：为同一份规范下的其他实现提供可量化的性能参照与验证基准。
+
+### 核心概念
+
+| 概念 | 定义 | 职责 |
+| --- | --- | --- |
+| Spec | 规范 | 定义行为契约与接口边界，划定实现必须遵守的范围 |
+| Benchmark | 基准测试 | 以多轮、多维度的量化测试验证实现，产出排名依据 |
+| MOPR | 标杆实现 | 满足 Spec 与 Benchmark 验证的前提下，性能最优的实现 |
+
+## 设计原则
+
+### 1. 性能第一，正确与稳定是隐含前提
+
+性能是优化方向与排名依据的第一优先级。正确性与稳定性并非与性能并列的取舍维度，而是参与性能排名的前置条件：不满足正确性与稳定性验证的实现，不具备参与性能排名的资格。
+
+每一轮基准测试同时覆盖三个维度：
+
+- **正确性**：输出是否符合 Spec 定义的行为契约
+- **稳定性**：长时间运行、压力与边界条件下是否可靠
+- **性能**：在前两者满足的前提下，是否达到最优
+
+正确性与稳定性作为过滤条件，性能作为排序依据。
+
+### 2. Spec 统一，实现自由
+
+Spec 定义行为契约与接口边界。同一份规范下允许存在多种异构实现，MOPR 是其中经过多轮基准测试反复验证、在目标平台上始终正确且性能最优的实现，作为其他实现的对标基准。
+
+### 3. 基准测试是设计驱动力
+
+每个设计决策都必须回答一个问题：**该改动是否提升性能？** 其成立前提是不得破坏正确性与稳定性——若基准数据改善但正确性或稳定性测试失败，则该改动不成立。
+
+### 4. 可移植性不等于性能下限
+
+MOPR 在不同平台上分别追求该平台能达到的最高性能，而非让所有平台退化为同一套低性能通用实现。平台相关的极致优化是核心策略，但每份平台实现都必须先通过正确性与稳定性验证。
+
+## 基准测试体系
+
+基准测试套件按验证目标分为四类：
+
+| 目录 | 类型 | 验证目标 |
+| --- | --- | --- |
+| `benchmark/micro/` | 微基准 | 吞吐、延迟、内存占用 |
+| `benchmark/macro/` | 场景基准 | 端到端性能 |
+| `benchmark/stability/` | 稳定性测试 | 长时间运行、压力、边界条件 |
+| `benchmark/regression/` | 回归检测 | 性能劣化监测 |
+
+只有通过正确性与稳定性验证的实现，其性能数据才纳入排名与对照。
+
+## 项目结构
+
+```
+mopr/
+├── spec/           # 规范定义
+│   ├── api.md      # 接口契约
+│   └── behavior.md # 行为语义
+├── base/           # 基础组件：cache / mem / mmap / cron / timestamp ...
+├── runtime/        # 运行时：ringbuffer / scheduler / once ...
+├── distributed/    # 分布式：id（HLC / 生成器 / 状态存储）
+├── encoding/       # 编码：csv / charsets / json / base64 / barcode ...
+├── storage/        # 存储抽象
+├── security/       # 安全：auth / audit / compliance
+├── machine/        # 机器标识
+├── log/            # 日志
+├── finance/        # 金融：forex / exchange
+├── benchmark/      # 基准测试套件
+│   ├── micro/      # 微基准：吞吐、延迟、内存
+│   ├── macro/      # 场景基准：端到端性能
+│   ├── stability/  # 稳定性：长时间运行、压力、边界
+│   └── regression/ # 性能回归检测
+├── tests/          # 跨语言测试用例
+├── docs/           # 设计决策记录
+│   └── proposals/  # 提案（RFC）：跨语言语义 / 契约变更的决策过程
+└── tools/          # 辅助工具（许可审计、许可证头）
+```
+
+**仓库根即实现根**：不设 `src/` 层，功能模块目录直接平铺在仓库根，同一功能的多语言实现共处同一目录、同名不同后缀（如 `base/mmap.py` / `base/mmap.h` / `base/mmap.rs` / `base/mmap/mmap.go`；各语言入口 `main.cpp` / `main.rs` 同样平铺在根）。
+
+- **与 Go 的 package 对齐**：Go 的包边界以目录划分，功能模块目录因此与 Go 的 `package` 一一对应（`distributed/id` 即 `package id`）；C++ 命名空间第二级（`distributed/id/hlc.h` → `mopr::distributed::id`）、Python 子模块路径、Rust `mod` 路径均取自同一目录路径，保证同一功能在各语言的模块语义相同。
+- **平台无关核心与平台极致优化就地组织**：核心语义落在各模块的公共实现中，平台相关优化留在同一模块内，按文件名后缀（`_posix` / `_windows` / `_unsupported`）或条件编译区分，不另设 `core/` / `platform/` 目录。
+
+这些约定只服务一件事：**让同一语义在各语言占据同一位置**——看到 `mmap.py`，顺手就能看到 `mmap.h` / `mmap.rs` / `mmap/mmap.go`，跨语言对照不必先找路径。完整论证（层级为何由语言工具链决定、按语言分目录为何是反例、对 AI 的友好之处）见 [docs/directory-layout-rationale.md](docs/directory-layout-rationale.md)。
+
+## 语言与版本要求
+
+MOPR 是单仓多语言库（monolibrary），同一份规范下将来会有多种语言实现。各语言的版本基线由本项目独立维护，不要求与同系列 `quant1x` 仓库同步：
+
+| 语言 | 最低版本 | 推荐版本 |
+| --- | --- | --- |
+| Python | 3.12+ | 3.12.x |
+| C++ | C++20 | GCC 13+ / Clang 17+ / MSVC 14.3+ |
+| Rust | 1.98.1+ | 1.98.1+（2024 edition） |
+| Go | 1.27+ | 1.27.x |
+| Java | 8+ | JDK 8 及以上（见 `pom.xml` 的 `java.version`） |
+
+- 当前仓库实现以 **C++20 + MSVC v143（Visual Studio 2022）+ CMake（≥3.25）/ Conan 2** 为主，构建细节见 [BUILDING.md](BUILDING.md)。
+- 后续新增 Python / Rust / Go / Java 实现时，须遵循上表最低版本基线，不得使用低于基线的语言特性与 API；版本表变更由本项目独立评估。
+
+## 快速开始
+
+当前 C++ 工程（CMake + Conan 2）的构建与编译步骤见 [BUILDING.md](BUILDING.md)。
+
+```text
+// TODO: 基准运行示例，待接口定义完成后补充
+```
+
+## 项目状态与路线图
+
+🚧 早期阶段 — Spec 正在起草中，实现尚未稳定。
+
+当前推进顺序：
+
+1. 起草 Spec：确定 `spec/api.md`（接口契约）与 `spec/behavior.md`（行为语义）
+2. 搭建基准测试套件与验证流程
+3. 基于平台无关核心实现首个基准实现
+4. 开展平台相关优化，并逐平台完成正确性、稳定性与性能验证
+
+## License / 协议
+
+本项目采用 **GNU Affero General Public License v3**（[AGPL-3.0](LICENSE) / SPDX: `AGPL-3.0-only`）授权。
+
+- 允许自由使用、复制、修改与再分发，但派生作品必须同样以 AGPLv3 发布（强 Copyleft）。
+- 通过网络提供服务的修改版本（含远程交互）须按第 13 条向用户开放对应源码。
+- 完整条款见根目录 [LICENSE](LICENSE) 文件。
+
+Copyright (C) 2026 Quant1X <wangfengxy@sina.cn>

{mopr-0.0.70 → mopr-0.0.71.dev10}/base/__init__.py

@@ -11,7 +11,7 @@ base 各单文件模块的公共函数与类型经 __init__ 直接导出, 业务
 """
 
 # 模块对象保留为包属性; environment 依赖 filesystem, 故 filesystem 在前
-from . import cron, crc32, dataclass_utils, environment, filesystem, mmap, region, strings, time, timestamp
+from . import cron, crc32, dataclass_utils, environment, filesystem, language, mmap, region, strings, time, timestamp
 
 # cron
 from .cron import CronExpr, make_cron, make_cron_for_region, resolve_timezone
@@ -23,6 +23,15 @@ from .dataclass_utils import get_field_names
 from .filesystem import expand_user, homedir, mkdirs, touch, update_file_mtime
 # environment
 from .environment import app_entry, env, getuser, read_dotenv
+# language (region 依赖它, 故在其前)
+from .language import (
+    DEFAULT_LANGUAGE,
+    Language,
+    language_chain,
+    language_code,
+    language_parent,
+    parse_language,
+)
 # mmap (MappedMemory / MmapHandle 名称过于通用, 连同两层 API 一并保留在 mopr.base.mmap 内)
 from .mmap import MmapError, mmap_open
 # time
@@ -43,6 +52,7 @@ from .time import (
     market_fiscal_year_start_month,
     market_reporting_frequency,
     to_rfc1123,
+    utc_offset_text,
 )
 # timestamp
 from .timestamp import Timestamp
@@ -64,10 +74,14 @@ __all__ = [
     "expand_user", "homedir", "mkdirs", "touch", "update_file_mtime",
     # environment
     "app_entry", "env", "getuser", "read_dotenv",
+    # language
+    "DEFAULT_LANGUAGE", "Language", "language_chain", "language_code",
+    "language_parent", "parse_language",
     # mmap
     "MmapError", "mmap_open",
     # time
     "from_rfc1123", "get_quarter_by_date", "get_timezone_offset_standard", "to_rfc1123",
+    "utc_offset_text",
     # time (财报周期)
     "DEFAULT_FISCAL_YEAR_START_MONTH",
     "DISCLOSURE_DEADLINE_DAYS_BY_MARKET",

mopr-0.0.71.dev10/base/language.md

@@ -0,0 +1,172 @@
+# language：跨语言语种组件（i18n 查询键）
+
+`base/language.md` 是本仓库 `base/` 下 language 多语言实现的对齐说明与 API 对照。
+
+language 收敛**语种（BCP 47 语言标签，含地区变体子标签）**，是 base 多语言模型的第一层（L1）。它解决一个具体问题：**需要多语言文字的入口，该以什么为查询键**。
+
+> **一等公民**：本组件与 `region` / `time` / `strings` 同等待遇 —— Python（spec）、C++（生产）、Rust / Go（扩展）**各有实现与单测**，Java 随 `base.Region` 一并跟进；不因"只是给 display_name 打个底"而只留 Python 一份。
+
+> **为何叫 `language` 而不叫 `i18n`**：`i18n`（internationalization）是**工程领域**名，指"让产品支持多语言"的整套能力 —— 消息目录、复数规则、日期/数字/货币格式化、排序、双向文字等；本组件只收敛其中的**语种标签**这一个值类型（外加它的解析与父子回退链），即 i18n 的**查询键 / 入参**，而非 i18n 本身。把值类型改叫 `i18n` 会占住地名：将来真要落消息目录与格式化时，`base/i18n` 往哪放？同类的自证反例是 `Region.language` —— 它返回"该地官方语言"，改叫 `Region.i18n` 显然不通。故本组件保持 `language`（与 BCP 47 的 *language tag* 同义、与 `region` / `time` / `cron` 同族），在文档中标明它是 **i18n 体系的第一层（L1）**；完整 i18n 设施将来另立模块，本组件作为其依赖与查询键被调用（见 §5.2）。
+
+各语言遵循仓库固定的**语言角色与演进顺序**（见根 `AGENTS.md`「语言角色与演进顺序」）：
+
+1. **Python 为 spec**：先行实现，确定语义、枚举成员与默认行为，是本组件的语义参照；
+2. **C++ 为生产实现**：Python spec 确定后落地（header-only）；
+3. **Rust / Go 为扩展**：随后跟进，与 spec 保持 API/语义对齐。
+
+**对齐原则**：以 Python（spec）为准绳——成员集、码值与解析/回退语义完全一致。本文档按 `python → c++ → rust → go` 顺序描述语言，对照表列序与此一致。
+
+## 1. 定位与文件清单
+
+| 角色 | 语言 | 文件 | 类型 | 说明 |
+| --- | --- | --- | --- | --- |
+| spec | Python | `base/language.py` | `class Language(Enum)`（`@unique`） | 先行定语义；含 `parse_language` / `language_code` |
+| 生产 | C++ | `base/language.h` | `enum class Language : uint8_t` | header-only（`inline` 函数），`mopr::base` |
+| 扩展 | Rust | `base/language.rs` | `enum Language` | 纯 `std`（无外部依赖），含单测 |
+| 扩展 | Go | `base/language.go` | `type Language string` + 常量 | 与 `region.go` 同包 |
+
+> **当前状态：Python / C++ / Rust / Go 已落地（四语言逐值对齐），Java 待跟进**（见 §5.1）。
+
+## 2. 为何语种独立于地区（Region）
+
+**地区与语种是正交的两件事**，拿地区推定语种必然出错：
+
+| 反例 | 说明 |
+| --- | --- |
+| 一地区多官方语言 | `HK` 中英、`DJ` 阿法——单个地区码无法表达"读者要哪一种" |
+| 一语言跨多地区 | `fr` 同属 `UEMOA` / `DJ` / `FR` / `CA`——**"法语区"在 `Region` 里没有单一成员可传** |
+| 属地 ≠ 界面语言 | 读者在法语区、软件界面是英文（真实常见）——按属地推定会给出读者看不懂的文字 |
+| 语种变体无对应地区 | 本库登记 `zh-TW` 而**没有** `Region.TW` —— 语种按**读者**分片，不按地区分片；若只有地区能表达语种，就会迫使后人为了语种去补地区，把两个维度重新焊死 |
+
+结论：**i18n 的查询键是 `Language`，不是 `Region`**。二者的分工是：
+
+| 概念 | 定位 | 谁持有 | 用途 |
+| --- | --- | --- | --- |
+| `Language` | i18n **查询键**（读者要哪种文字） | 调用方显式传入 | 严格口径：`display_name(Language.FR)` |
+| `Region.language` | 地区的**属性**（该地官方文件第一语言） | `base.Region` | 推定口径：仅当"只知属地、不知语种"时用 |
+
+`Region.language` **不是**被废除，而是**降级为推定入口**：它的返回值是 `Language`（类型化、非空），但用它取文字等于替读者做了选择，文档必须标注为推定。`base/region.md` §2 的官方语言口径（双语地区取官方文件第一语言）保持不变，只是值的类型从字符串码升级为 `Language` 成员。
+
+## 3. 取词回退链（i18n fallback）
+
+需要文字的入口（现为 `finance.exchange` 的 `Institution.display_name`）一律按**固定回退链**取词，四语言同一实现、同一顺序。
+
+回退的**方向是 BCP 47 截断（具体到泛）**，由 `language_chain(l)` 给出候选序列（含自身、不含 `UNKNOWN`）：
+
+| 目标语种 | 候选序列 | 说明 |
+| --- | --- | --- |
+| `ZH_TW` | `zh-TW` → `zh` | 地区变体无独立登记 → 回落到通用中文 |
+| `ZH_HK` | `zh-HK` → `zh` | 同上 |
+| `EN` | `en` | 命中即止 |
+| `FR` | `fr` | 无登记 → 交由取词入口的终档 `EN` |
+| `UNKNOWN` | （空） | 不进回退链，直接取 `DEFAULT_LANGUAGE` |
+
+取词入口遍历候选序列，逐档判定：
+
+1. **候选有登记名称** → 用它（如 `ZH` → `official_name`、`EN` → `english_name`）。繁体地区变体 `zh-HK` / `zh-TW` 现阶段无独立登记，沿链回落到 `ZH`，给**简体**中文名 —— 降级但不错给：繁体读者读简体中文名远好过读英文名；
+2. **候选未登记** → 回落到**该机构法域的官方语言**原名 `native_name`（⏳ 待登记，见 §5.3）；
+3. **序列走完仍未命中** → 回落到 `EN`（英文是唯一要求全机构必填的语种）。
+
+> 回退链的原则：**可以降级，不可错给**。宁可给英文（读者普遍能读），不可返回中文形态——中文名对法语读者与英文读者同样无意义。回退是**显式且可预测**的，禁止"查不到就给个大概"。
+
+`EN` 之所以是终点而非 `ZH`：本库主语境是中文，但英文名是唯一**全机构必填**的名称（见 `finance/exchange/README.md` §5.1），覆盖面确定；中文名是本库的主语境但并非跨语种通用。
+
+## 4. 成员集与取值
+
+成员**按需登记**，不做 ISO 639-1 / BCP 47 全量表；新增语种必须有消费方（某地区的 `Region.language`、某机构的登记名称，或明确的读者侧需求）。
+
+| 成员（码） | 语种 | 父标签 | 登记依据 |
+| --- | --- | --- | --- |
+| `ZH`（`zh`） | 中文（本库主语境与默认语种；简体形态） | — | `Region.CN`；回退链中 `zh-HK` / `zh-TW` 的落点 |
+| `ZH_HK`（`zh-HK`） | 香港中文（繁体 + 港式用词） | `ZH` | `Region.HK` |
+| `ZH_TW`（`zh-TW`） | 台湾中文（繁体 + 台澎金马用词） | `ZH` | **读者侧** —— 本库无 `Region.TW`，语种登记不依赖地区 |
+| `EN`（`en`） | 英文 | — | `Region.US` / `UK` / `EU` / `SG` / `GH`；**回退链终点** |
+| `FR`（`fr`） | 法文 | — | `Region.UEMOA` / `Region.DJ` |
+| `JA`（`ja`） | 日文 | — | `Region.JP` |
+| `UNKNOWN`（`""`） | 未知 / 无语种可依 | — | `Region.GLB` / `Region.UNKNOWN` 的 `language`；码为**空串**（非 ISO 639 的 `und`，本库只需"有没有语种"这一个判断） |
+
+> **为何登记 `zh-HK` / `zh-TW` 而不只分繁简**："繁体中文"不是一种文字 —— 港台同用繁体字却**用词不同**（港：巴士 / 的士 / 按揭；台：公车 / 计程车 / 房贷）。只按正字法分（`zh-Hant`）会把港台合并，与 §2 第 1 类错（一地区多语言被压缩）是同一个毛病。故本层**登记到地区子标签**，正字法由标签隐含（`zh-HK` / `zh-TW` 均隐含 Hant），不单独登记 `zh-Hant` 成员 —— 那是 `Locale` 第二层的事（见 §5.2）。
+>
+> `zh-TW` 现在**没有**对应的 `Region` 成员，这是刻意的：语种按读者分片，不按地区分片。不要为了"对称"去补 `Region.TW`（补地区要连带货币 `TWD`、时区 `Asia/Taipei` 与外汇源，是独立议题）。
+
+## 4.1 API 对照
+
+| 语义 | Python | C++ | Rust | Go |
+| --- | --- | --- | --- | --- |
+| 语种码（BCP 47） | `language_code(l)` | `language_code(Language)` | `l.code()` / `Display` | `l.Code()` |
+| 解析（宽容，未知→`UNKNOWN`） | `parse_language(s)` | `parse_language(std::string_view)` | `parse_language(&str)` | `ParseLanguage(s)` |
+| 是否未知 | `l.is_unknown`（property） | `language_is_unknown(l)` | `l.is_unknown()` | `l.IsUnknown()` |
+| 父标签（去掉最右子标签） | `language_parent(l)` | `language_parent(Language)` | `l.parent()` | `l.Parent()` |
+| 回退链候选序列 | `language_chain(l)` → `tuple` | `language_chain(Language)` → `vector` | `l.chain()` → `Vec` | `l.Chain()` → `[]Language` |
+| 默认语种常量 | `DEFAULT_LANGUAGE`（`Language.ZH`） | `kDefaultLanguage` | `DEFAULT_LANGUAGE` | `DefaultLanguage` |
+
+**解析宽容度**：四语言一律**宽容**，未知码返回 `Language.UNKNOWN`、不抛异常——语种来自用户设置 / 系统 locale / 配置，属不可信输入，解析失败应降级到默认语种而非中断调用方。这与 `base/region.md` §5.1 记录的 `Region` 解析宽容度差异（C++ 宽容、Rust/Go 报错）**不同**，是本组件显式选定的新口径，勿照搬 `Region`。
+
+**解析按 BCP 47 lookup（RFC 4647 §3.4）**：先匹配**最具体**的整串，失配则逐级去掉最右子标签重试，命中第一个已登记者即止。
+
+**接受的输入形态**（四语言一致，单元测试逐条锁定）：
+
+| 输入 | 结果 | 说明 |
+| --- | --- | --- |
+| `"fr"` / `"FR"` / `" fr "` | `Language.FR` | 忽略大小写与首尾空白 |
+| `"zh-HK"` / `"ZH-hk"` / `"zh_TW"` | `Language.ZH_HK` / `ZH_HK` / `ZH_TW` | **整串命中**：地区变体不退化成语言子标签；下划线视同连字符 |
+| `"zh-Hant-HK"` / `"zh-Hant"` | `Language.ZH` | 逐级截断：`zh-Hant` 未登记 → 落到 `zh` |
+| `"fr-FR"` / `"en_US"` / `"ja-JP"` | `Language.FR` / `EN` / `JA` | 同上，逐级截断 |
+| `""` / `None` / `"xx"` / `"-"` | `Language.UNKNOWN` | 宽容降级 |
+
+> 解析**不**推断地区语义：`fr-FR` 里的 `FR` 不会被读成 `Region`。已登记的地区变体（`zh-HK` / `zh-TW`）是**成员**而非推断结果 —— 它们是按需登记的查询键，不是"由地区推出来的语言"。
+
+## 5. 待办（TODO）
+
+### 5.1 跨语言跟进（Python / C++ / Rust / Go 已落地）
+
+| 语言 | 实现 | 单测 | 状态 |
+| --- | --- | --- | --- |
+| Python（spec） | `base/language.py` | `base/language_test.py`（unittest，7 用例） | ✅ |
+| C++（生产） | `base/language.h`（header-only） | `tests/base/language_test.cpp`（gtest） | ✅ |
+| Rust（扩展） | `base/language.rs` | 同文件内联 `#[cfg(test)]`（5 用例） | ✅ |
+| Go（扩展） | `base/language.go` | `base/language_test.go`（6 用例） | ✅ |
+| Java | — | — | ⏳ 随 `base.Region` 一并落地 |
+
+- [x] 四语言各自的成员集（7 个）、码值、解析形态表、父标签与回退链**逐值比对**一致；
+- [x] `base.Region.language` 四语言同步落地（C++ `region_language(r)` / Rust `r.language()` / Go `r.Language()`），返回 `Language` 而非字符串码（见 `base/region.md` §8.2）；
+- [ ] Java：`base/Language.java` + `Region.language()` 返回 `Language`（待 `base.Region` 落地时一并实现）。
+
+### 5.2 第二层 `Locale`（BCP 47，⏳ 未立项）
+
+第一层已覆盖**语种 + 地区变体**（`zh-HK` / `zh-TW`），第二层要补的是**正字法与格式**，与前者不是一回事：
+
+| 维度 | 归哪层 | 现状 |
+| --- | --- | --- |
+| 语言（`zh` / `en` / `fr` / `ja`） | L1 `Language` | ✅ 已落地 |
+| 地区变体（`zh-HK` / `zh-TW`） | L1 `Language` | ✅ 已落地（用词差异） |
+| 正字法（`zh-Hans` / `zh-Hant`） | L2 `Locale` | ⏳ 待触发 |
+| 数字 / 日期 / 货币格式 | L2 `Locale` | ⏳ 待触发 |
+
+**触发条件**（满足任一才立项，不因"完整"而提前铺）：
+
+- 需要按**正字法**取词（同一机构名的简繁两种写法要分别登记）；
+- 需要区分**同一语种的地区格式**（`en-US` / `en-GB` 的日期与数字格式）；
+- 需要 `script` 子标签单独参与取词（即"繁体但不分港台"这一档）。
+
+立项前**不引入**：`display_name` 的入参只有 `Language` 一种（外加 `Region` 推定重载），不引入三态参数。`parse_language` 已能吃下完整 locale 串（`zh-Hant-HK` → `ZH`），且 `zh-HK` / `zh-TW` **整串命中**，故现在传 locale 字符串也不会报错，未登记的部分按 lookup 逐级忽略 —— 这是有意的平滑过渡。
+
+### 5.3 语言自身的展示名（⏳ 未登记）
+
+`english_name`（Chinese / French）与 `native_name`（中文 / Français）暂不登记：当前无消费方（无语言选择器）。待出现"需要把语种本身显示给用户"的场景时补，届时按 §4 的按需登记原则一并加自检。
+
+## 6. 验证
+
+| 语言 | 命令 | 覆盖 |
+| --- | --- | --- |
+| Python | `python -m mopr.base.language_test`（需在仓库根的父目录运行，或把仓库根加入 `PYTHONPATH`，见根 `AGENTS.md`） | 成员集恰为 7、码值逐值、解析形态表、`parent` / `chain`、`UNKNOWN` 非空串兜底、默认语种 |
+| C++ | `cmake --build --preset <配置> --target mopr_tests` 后运行（gtest） | 与 Python **同一张成员表与解析形态表** |
+| Rust | `cargo test --lib base::language` | 同上 |
+| Go | `go test ./base/ -run Language -v` | 同上 |
+
+交互冒烟（四语言同解）：
+
+- `parse_language("zh-TW")` → `ZH_TW`、`parse_language("zh-Hant-HK")` → `ZH`、`parse_language("xx")` → `UNKNOWN`；
+- `language_chain(ZH_TW)` → `ZH_TW, ZH`；`language_chain(UNKNOWN)` → 空（取默认语种）。
+
+跨语言一致性：以 7 个码（`zh` / `zh-HK` / `zh-TW` / `en` / `fr` / `ja` / `""`）在各语言做"码 → Language → 码"回环断言比对，并比对 §4.1 的解析形态表与父子链。