FovesConfig 0.1.2__tar.gz → 0.3.0__tar.gz

fovesconfig-0.3.0/FovesConfig/loader.py

@@ -0,0 +1,111 @@
+import os
+import shutil
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Type
+
+from pydantic import BaseModel
+
+# 落盘重试：Windows 上目标文件正被别的进程读时 os.replace 会抛 PermissionError，
+# 并发读压力下实测 81% 的写入都要重试，所以这里必须等，不能失败就走。
+_WRITE_ATTEMPTS = 100  # 最大写入重试次数
+_WRITE_RETRY_DELAY = 0.005  # 重试延时
+_WRITE_WARN_EVERY = 10  # 每 10 次重试警告
+# 读取重试：读者也可能正好撞上别人 replace 的瞬间。
+_READ_ATTEMPTS = 6  # 最大重试
+_READ_RETRY_DELAY = 0.005  # 重试延时
+
+
+def _default_file_mode() -> int:
+    """按当前 umask 算出新建文件该有的权限位（mkstemp 建出来的是 0600，太紧）。"""
+    umask = os.umask(0)
+    os.umask(umask)
+    return 0o666 & ~umask
+
+
+def _atomic_write_text(path: Path, text: str) -> None:
+    """先写同目录临时文件再 os.replace 顶掉目标：读者要么看到旧内容，要么看到新内容。"""
+    fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=path.name + ".", suffix=".tmp")
+    tmp = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as file:
+            file.write(text)
+            file.flush()
+            os.fsync(file.fileno())
+        # 换了新 inode 会丢掉原文件的权限位，这里对齐回去。
+        try:
+            if path.exists():
+                shutil.copymode(path, tmp)
+            else:
+                os.chmod(tmp, _default_file_mode())
+        except OSError:
+            pass
+        last_error: PermissionError | None = None
+        for attempt in range(1, _WRITE_ATTEMPTS + 1):
+            try:
+                os.replace(tmp, path)
+                return
+            except PermissionError as error:
+                last_error = error
+                if attempt % _WRITE_WARN_EVERY == 0:
+                    print(
+                        f'[FovesConfig] 写入 {path} 第 {attempt} 次重试未成功（文件被占用？）：{error}',
+                        file=sys.stderr,
+                    )
+                time.sleep(_WRITE_RETRY_DELAY)
+        raise last_error or RuntimeError(f'写入 {path} 失败')
+    except BaseException:
+        try:
+            tmp.unlink()
+        except OSError:
+            pass
+        raise
+
+
+def _read_text(path: Path) -> str:
+    """读取文本，撞上别人正在替换文件的瞬间就稍等重试。"""
+    last_error: PermissionError | None = None
+    for _ in range(_READ_ATTEMPTS):
+        try:
+            return path.read_text("UTF8")
+        except PermissionError as error:
+            last_error = error
+            time.sleep(_READ_RETRY_DELAY)
+    raise last_error or RuntimeError(f'读取 {path} 失败')
+
+
+class ConfigLoader[T: BaseModel]:
+    def __init__(self, path: str|Path, model: Type[T]):
+        self.path = Path(path)
+        self.model_cls = model
+    
+    def _read(self):
+        if self.path.exists():
+            self.model = self.model_cls.model_validate_json(_read_text(self.path))
+        else:
+            self.model = self.model_cls()
+
+    def _write(self):
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        _atomic_write_text(
+            self.path,
+            self.model.model_dump_json(indent=2, ensure_ascii=False),
+        )
+        
+    def readonly(self) -> T:
+        self._read()
+        return self.model
+    
+    def overwrite(self, model: T) -> T:
+        self.model = model
+        self._write()
+        return self.model
+
+    def __enter__(self) -> T:
+        self._read()
+        return self.model
+
+    def __exit__(self, exc_type, exc, tb):
+        self._write()

{fovesconfig-0.1.2 → fovesconfig-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: FovesConfig
-Version: 0.1.2
+Version: 0.3.0
 Summary: 四叶的配置管理工具 — 基于 Pydantic 的配置加载器，上下文管理器自动读写
 Project-URL: Repository, https://github.com/Foves7017/FovesLib
 Author: Foves7017
@@ -97,9 +97,27 @@ cfg = loader.overwrite(AppConfig(port=9090))
 
 - **读取**：进入上下文管理器时，若文件存在则 `model_validate_json` 反序列化，否则用 `model_cls()` 构造默认实例。
 - **写入**：退出上下文管理器时自动创建父目录，以 `indent=2`、`ensure_ascii=False` 写出 JSON。
-- **写入实现**：落盘逻辑集中在内部的 `_write()`，上下文退出和 `overwrite()` 共用同一套行为，两者格式完全一致。
+- **写入实现**：落盘逻辑集中在内部的 `_write()`，上下文退出和 `overwrite()` 共用同一套行为，两者格式完全一致。它写的是「同目录临时文件 → `os.replace`」，细节见下面的「并发与原子写」。
 - **异常路径**：`__exit__` 不会吞掉异常，也不会因为异常就跳过写入——块内抛异常时配置依然会写回磁盘。
 
+### 并发与原子写
+
+写入不是「打开目标文件直接覆盖」，而是「先写同目录的临时文件，再 `os.replace` 顶掉目标」。所以另一个进程或线程在这个瞬间去读，要么读到旧内容，要么读到新内容，不会读到半截 JSON。
+
+代价是 Windows 上 `os.replace` 撞上别人正打开着目标文件时会抛 `PermissionError`，因此读写都带短重试：
+
+| | 每次间隔 | 上限 | 最坏耗时 |
+|---|---|---|---|
+| 写入（`os.replace`） | 5 ms | 100 次 | ~500 ms |
+| 读取（`read_text`） | 5 ms | 6 次 | ~30 ms |
+
+- 写入每满 10 次还没成功，会往 **`sys.stderr`** 打一条警告：
+  `[FovesConfig] 写入 config.json 第 30 次重试未成功（文件被占用？）：[WinError 5] ...`
+  故意不写 stdout——stdio 型 MCP 服务的 stdout 是协议通道，多打一行就会把协议打坏。
+- 100 次全失败会抛出原始 `PermissionError`，同时删掉临时文件，不会留下半截目标文件。
+- 临时文件形如 `config.json.a1b2c3.tmp`，与目标同目录（同目录才能保证 `os.replace` 是原子的）。进程被强杀时可能留下一个孤儿临时文件，不影响读取，可手动删。
+- 这套重试只解决「读到半截」。多个进程同时改同一份配置时，后写的会覆盖先写的，`ConfigLoader` **不提供跨进程锁。**
+
 ### 其他
 如果你发现自己需要手动调用 save() 或 exit()，请先考虑是否应该使用上下文管理器。大多数修改配置的场景都更适合：
 

{fovesconfig-0.1.2 → fovesconfig-0.3.0}/README.md

@@ -65,9 +65,27 @@ cfg = loader.overwrite(AppConfig(port=9090))
 
 - **读取**：进入上下文管理器时，若文件存在则 `model_validate_json` 反序列化，否则用 `model_cls()` 构造默认实例。
 - **写入**：退出上下文管理器时自动创建父目录，以 `indent=2`、`ensure_ascii=False` 写出 JSON。
-- **写入实现**：落盘逻辑集中在内部的 `_write()`，上下文退出和 `overwrite()` 共用同一套行为，两者格式完全一致。
+- **写入实现**：落盘逻辑集中在内部的 `_write()`，上下文退出和 `overwrite()` 共用同一套行为，两者格式完全一致。它写的是「同目录临时文件 → `os.replace`」，细节见下面的「并发与原子写」。
 - **异常路径**：`__exit__` 不会吞掉异常，也不会因为异常就跳过写入——块内抛异常时配置依然会写回磁盘。
 
+### 并发与原子写
+
+写入不是「打开目标文件直接覆盖」，而是「先写同目录的临时文件，再 `os.replace` 顶掉目标」。所以另一个进程或线程在这个瞬间去读，要么读到旧内容，要么读到新内容，不会读到半截 JSON。
+
+代价是 Windows 上 `os.replace` 撞上别人正打开着目标文件时会抛 `PermissionError`，因此读写都带短重试：
+
+| | 每次间隔 | 上限 | 最坏耗时 |
+|---|---|---|---|
+| 写入（`os.replace`） | 5 ms | 100 次 | ~500 ms |
+| 读取（`read_text`） | 5 ms | 6 次 | ~30 ms |
+
+- 写入每满 10 次还没成功，会往 **`sys.stderr`** 打一条警告：
+  `[FovesConfig] 写入 config.json 第 30 次重试未成功（文件被占用？）：[WinError 5] ...`
+  故意不写 stdout——stdio 型 MCP 服务的 stdout 是协议通道，多打一行就会把协议打坏。
+- 100 次全失败会抛出原始 `PermissionError`，同时删掉临时文件，不会留下半截目标文件。
+- 临时文件形如 `config.json.a1b2c3.tmp`，与目标同目录（同目录才能保证 `os.replace` 是原子的）。进程被强杀时可能留下一个孤儿临时文件，不影响读取，可手动删。
+- 这套重试只解决「读到半截」。多个进程同时改同一份配置时，后写的会覆盖先写的，`ConfigLoader` **不提供跨进程锁。**
+
 ### 其他
 如果你发现自己需要手动调用 save() 或 exit()，请先考虑是否应该使用上下文管理器。大多数修改配置的场景都更适合：
 

{fovesconfig-0.1.2 → fovesconfig-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "FovesConfig"
-version = "0.1.2"
+version = "0.3.0"
 description = "四叶的配置管理工具 — 基于 Pydantic 的配置加载器，上下文管理器自动读写"
 readme = "README.md"
 license = {file = "LICENSE"}

fovesconfig-0.1.2/FovesConfig/loader.py

@@ -1,37 +0,0 @@
-from typing import Type
-from pathlib import Path
-from pydantic import BaseModel
-
-class ConfigLoader[T: BaseModel]:
-    def __init__(self, path: str|Path, model: Type[T]):
-        self.path = Path(path)
-        self.model_cls = model
-    
-    def _read(self):
-        if self.path.exists():
-            self.model = self.model_cls.model_validate_json(self.path.read_text("UTF8"))
-        else:
-            self.model = self.model_cls()
-
-    def _write(self):
-        self.path.parent.mkdir(parents=True, exist_ok=True)
-        self.path.write_text(
-            self.model.model_dump_json(indent=2, ensure_ascii=False),
-            encoding="utf-8",
-        )
-        
-    def readonly(self) -> T:
-        self._read()
-        return self.model
-    
-    def overwrite(self, model: T) -> T:
-        self.model = model
-        self._write()
-        return self.model
-
-    def __enter__(self) -> T:
-        self._read()
-        return self.model
-
-    def __exit__(self, exc_type, exc, tb):
-        self._write()