Merge pull request #7050 from DDSRem-Dev/codex-comment-migration

docs: 统一全项目中文注释和结构化契约说明

tests/test_plugin_config_command.py

@@ -1,3 +1,7 @@
+"""
+验证插件配置命令的输入校验与保存行为。
+"""
+
 from contextlib import nullcontext
 
 from app.application.plugin.config import PluginConfigCommand, PluginPurgeScope
@@ -13,7 +17,9 @@ def _command(
     is_clone: bool = False,
     purge_invalid_empty_host=None,
 ) -> PluginConfigCommand:
-    """构造记录端口调用顺序的插件配置用例。"""
+    """
+    构造记录端口调用顺序的插件配置用例。
+    """
     return PluginConfigCommand(
         save_config=lambda plugin_id, config, force: (
             calls.append(("save", plugin_id, config, force)) or save_result
@@ -48,7 +54,9 @@ def _command(
 
 
 def test_update_stops_before_runtime_side_effects_when_save_fails() -> None:
-    """配置持久化失败时不得初始化插件或刷新宿主注册。"""
+    """
+    配置持久化失败时不得初始化插件或刷新宿主注册。
+    """
     calls: list[tuple] = []
 
     result = _command(calls, save_result=False).update("DemoPlugin", {"enabled": True})
@@ -59,7 +67,9 @@ def test_update_stops_before_runtime_side_effects_when_save_fails() -> None:
 
 
 def test_update_refreshes_runtime_only_after_config_is_saved() -> None:
-    """配置保存成功后按初始化、注册刷新顺序生效。"""
+    """
+    配置保存成功后按初始化、注册刷新顺序生效。
+    """
     calls: list[tuple] = []
 
     result = _command(calls).update("DemoPlugin", {"enabled": True})
@@ -73,7 +83,9 @@ def test_update_refreshes_runtime_only_after_config_is_saved() -> None:
 
 
 def test_reset_preserves_compensation_cleanup_and_reload_order() -> None:
-    """重置必须先让插件补偿，再停止、清理并重建运行态和注册。"""
+    """
+    重置必须先让插件补偿，再停止、清理并重建运行态和注册。
+    """
     calls: list[tuple] = []
 
     result = _command(calls).reset("DemoPlugin")
@@ -90,7 +102,9 @@ def test_reset_preserves_compensation_cleanup_and_reload_order() -> None:
 
 
 def test_sealed_config_command_rejects_before_first_side_effect() -> None:
-    """配置事务在 admission 封口后返回失败，且不得先发布 reset 事件。"""
+    """
+    配置事务在 admission 封口后返回失败，且不得先发布 reset 事件。
+    """
     calls: list[tuple] = []
     admission = PluginMutationAdmission()
     admission.seal()
@@ -109,7 +123,9 @@ def test_sealed_config_command_rejects_before_first_side_effect() -> None:
 
 
 def test_purge_refuses_an_empty_scope() -> None:
-    """一项都没勾选时直接拒绝，不做「那就全清吧」这种猜测。"""
+    """
+    一项都没勾选时直接拒绝，不做「那就全清吧」这种猜测。
+    """
     calls: list[tuple] = []
 
     result = _command(calls).purge("DemoPluginWork", PluginPurgeScope())
@@ -120,7 +136,9 @@ def test_purge_refuses_an_empty_scope() -> None:
 
 
 def test_purge_only_touches_the_selected_scopes() -> None:
-    """逐项执行且互不代劳：没勾的范围一个字节都不能动。"""
+    """
+    逐项执行且互不代劳：没勾的范围一个字节都不能动。
+    """
     calls: list[tuple] = []
 
     result = _command(calls).purge(
@@ -137,7 +155,9 @@ def test_purge_only_touches_the_selected_scopes() -> None:
 
 
 def test_purge_destroys_the_database_before_removing_its_directory() -> None:
-    """库文件就落在该目录下，不先销毁句柄直接删目录会留下被占用的文件。"""
+    """
+    库文件就落在该目录下，不先销毁句柄直接删目录会留下被占用的文件。
+    """
     calls: list[tuple] = []
 
     result = _command(calls).purge(
@@ -156,7 +176,9 @@ def test_purge_destroys_the_database_before_removing_its_directory() -> None:
 
 
 def test_purge_removes_the_row_for_a_clone_but_keeps_it_for_a_host() -> None:
-    """分身的存在由那一行表达，清理即消失；本体的行要留着，它还说着「应当装载」。"""
+    """
+    分身的存在由那一行表达，清理即消失；本体的行要留着，它还说着「应当装载」。
+    """
     clone_calls: list[tuple] = []
     clone = _command(clone_calls, is_clone=True).purge(
         "DemoPluginWork", PluginPurgeScope(config=True)
@@ -174,7 +196,9 @@ def test_purge_removes_the_row_for_a_clone_but_keeps_it_for_a_host() -> None:
 
 
 def test_purge_reports_a_missing_directory_as_not_purged() -> None:
-    """目录本就不存在时不谎报清理过它。"""
+    """
+    目录本就不存在时不谎报清理过它。
+    """
     calls: list[tuple] = []
 
     result = _command(calls, directory_existed=False).purge(
@@ -186,7 +210,9 @@ def test_purge_reports_a_missing_directory_as_not_purged() -> None:
 
 
 def test_purge_stops_the_instance_before_deleting_anything() -> None:
-    """删除必须晚于停止：仍在跑的实例会一边被删一边把数据写回来。"""
+    """
+    删除必须晚于停止：仍在跑的实例会一边被删一边把数据写回来。
+    """
     calls: list[tuple] = []
 
     _command(calls).purge(
@@ -198,7 +224,9 @@ def test_purge_stops_the_instance_before_deleting_anything() -> None:
 
 
 def test_sealed_purge_is_rejected_before_any_deletion() -> None:
-    """停机封口期间拒绝清理，且一步删除都不做。"""
+    """
+    停机封口期间拒绝清理，且一步删除都不做。
+    """
     calls: list[tuple] = []
     admission = PluginMutationAdmission()
     admission.seal()
@@ -213,7 +241,9 @@ def test_sealed_purge_is_rejected_before_any_deletion() -> None:
 
 
 def test_invalid_empty_host_purge_only_calls_database_port() -> None:
-    """非法残留只走专用端口，不停止实例或进入常规配置与文件删除路径。"""
+    """
+    非法残留只走专用端口，不停止实例或进入常规配置与文件删除路径。
+    """
     calls: list[tuple] = []
     command = _command(
         calls,
@@ -226,7 +256,9 @@ def test_invalid_empty_host_purge_only_calls_database_port() -> None:
 
 
 def test_invalid_host_purge_preserves_rows_with_settings() -> None:
-    """专用端口拒绝非空记录时返回失败，不继续清配置或删除文件。"""
+    """
+    专用端口拒绝非空记录时返回失败，不继续清配置或删除文件。
+    """
     calls: list[tuple] = []
     result = _command(calls, purge_invalid_empty_host=lambda _pid: False).purge(
         "Emby角色中文化", PluginPurgeScope(config=True),
@@ -237,10 +269,14 @@ def test_invalid_host_purge_preserves_rows_with_settings() -> None:
 
 
 def test_invalid_host_purge_rejects_other_scopes_and_shutdown() -> None:
-    """其它删除范围与停机封口都不得进入残留清理端口。"""
+    """
+    其它删除范围与停机封口都不得进入残留清理端口。
+    """
     calls: list[tuple] = []
     def purge(instance_id: str) -> bool:
-        """记录不应到达的残留清理调用。"""
+        """
+        记录不应到达的残留清理调用。
+        """
         calls.append(("empty_host", instance_id))
         return True
     command = _command(calls, purge_invalid_empty_host=purge)