FovesConfig 0.1.1__tar.gz → 0.1.2__tar.gz

{fovesconfig-0.1.1 → fovesconfig-0.1.2}/FovesConfig/loader.py

@@ -13,17 +13,25 @@ class ConfigLoader[T: BaseModel]:
         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.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",
-        )
+        self._write()

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: FovesConfig
-Version: 0.1.1
+Version: 0.1.2
 Summary: 四叶的配置管理工具 — 基于 Pydantic 的配置加载器，上下文管理器自动读写
 Project-URL: Repository, https://github.com/Foves7017/FovesLib
 Author: Foves7017
@@ -78,10 +78,27 @@ cfg = loader.readonly()
 print(cfg.host)
 ```
 
+### 覆盖写入
+
+不想进上下文、只想把一份新配置整体写回去时，用 `overwrite()`：调用即落盘，并把这个实例返回给你。
+一个典型用法（也是我创建这个方法的原因）就是在配置初始化时创建文件。
+
+```Python
+loader = ConfigLoader("config.json", AppConfig)
+cfg = loader.overwrite(AppConfig(port=9090))
+```
+
+- **写入时机**：调用时立刻写，不需要等 `with` 块退出；父目录不存在会自动递归创建。
+- **不会先读取**：所以磁盘上是坏掉的 JSON 也能被直接覆盖。
+- **不做校验**：入参必须是你在 `ConfigLoader` 上声明的那个模型实例。传 `dict`、`None` 之类会直接抛 `AttributeError`（它只会去调 `model_dump_json`）；传成别的模型也会被原样写出去。
+- **和 `readonly()` 的关系**：`readonly()` 每次调用都会重新从磁盘读取，因此**以磁盘上最后一次写入的内容为准**。`overwrite()` 之后再 `readonly()`，拿到的是重新反序列化出来的新对象，不是你传进去的那个引用。
+
 ### 读写行为
 
 - **读取**：进入上下文管理器时，若文件存在则 `model_validate_json` 反序列化，否则用 `model_cls()` 构造默认实例。
 - **写入**：退出上下文管理器时自动创建父目录，以 `indent=2`、`ensure_ascii=False` 写出 JSON。
+- **写入实现**：落盘逻辑集中在内部的 `_write()`，上下文退出和 `overwrite()` 共用同一套行为，两者格式完全一致。
+- **异常路径**：`__exit__` 不会吞掉异常，也不会因为异常就跳过写入——块内抛异常时配置依然会写回磁盘。
 
 ### 其他
 如果你发现自己需要手动调用 save() 或 exit()，请先考虑是否应该使用上下文管理器。大多数修改配置的场景都更适合：
@@ -91,4 +108,6 @@ with ConfigLoader(...) as config:
     ...
 ```
 
-而不是手动管理配置对象的生命周期。
+而不是手动管理配置对象的生命周期。
+
+如果确实需要“不进上下文也要写盘”的场景（例如程序启动时生成一份默认配置、或把外部来源的配置整体落盘），直接用 `overwrite()` 就够了，不必自己造 `save()` / `exit()`。

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

@@ -46,10 +46,27 @@ cfg = loader.readonly()
 print(cfg.host)
 ```
 
+### 覆盖写入
+
+不想进上下文、只想把一份新配置整体写回去时，用 `overwrite()`：调用即落盘，并把这个实例返回给你。
+一个典型用法（也是我创建这个方法的原因）就是在配置初始化时创建文件。
+
+```Python
+loader = ConfigLoader("config.json", AppConfig)
+cfg = loader.overwrite(AppConfig(port=9090))
+```
+
+- **写入时机**：调用时立刻写，不需要等 `with` 块退出；父目录不存在会自动递归创建。
+- **不会先读取**：所以磁盘上是坏掉的 JSON 也能被直接覆盖。
+- **不做校验**：入参必须是你在 `ConfigLoader` 上声明的那个模型实例。传 `dict`、`None` 之类会直接抛 `AttributeError`（它只会去调 `model_dump_json`）；传成别的模型也会被原样写出去。
+- **和 `readonly()` 的关系**：`readonly()` 每次调用都会重新从磁盘读取，因此**以磁盘上最后一次写入的内容为准**。`overwrite()` 之后再 `readonly()`，拿到的是重新反序列化出来的新对象，不是你传进去的那个引用。
+
 ### 读写行为
 
 - **读取**：进入上下文管理器时，若文件存在则 `model_validate_json` 反序列化，否则用 `model_cls()` 构造默认实例。
 - **写入**：退出上下文管理器时自动创建父目录，以 `indent=2`、`ensure_ascii=False` 写出 JSON。
+- **写入实现**：落盘逻辑集中在内部的 `_write()`，上下文退出和 `overwrite()` 共用同一套行为，两者格式完全一致。
+- **异常路径**：`__exit__` 不会吞掉异常，也不会因为异常就跳过写入——块内抛异常时配置依然会写回磁盘。
 
 ### 其他
 如果你发现自己需要手动调用 save() 或 exit()，请先考虑是否应该使用上下文管理器。大多数修改配置的场景都更适合：
@@ -59,4 +76,6 @@ with ConfigLoader(...) as config:
     ...
 ```
 
-而不是手动管理配置对象的生命周期。
+而不是手动管理配置对象的生命周期。
+
+如果确实需要“不进上下文也要写盘”的场景（例如程序启动时生成一份默认配置、或把外部来源的配置整体落盘），直接用 `overwrite()` 就够了，不必自己造 `save()` / `exit()`。

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

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