perceptkit 0.2.6__tar.gz → 0.2.7__tar.gz

{perceptkit-0.2.6 → perceptkit-0.2.7}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 变更记录
 
+## 0.2.7 — 2026-09-02
+
+- **跳过原因带上稳定的 `code`（`SkippedSignal`）。** 0.2.6 的清理计划里，
+  跳过理由只有一句中文 —— 这个包的注释都是中文，但**宿主的运维界面不一定是**，
+  直接印进一个英文报告里就成了半中半英。一个库不该替宿主决定报告用什么语言：
+  `code` 稳定、机器可读，文案归宿主。`SkippedSignal` 仍然能按 `(signal, detail)`
+  解包，老调用方不用改。
+  （0.2.6 发出去之后接 io 时当场撞到的 —— 那份英文运维报告里蹦出中文。）
+
 ## 0.2.6 — 2026-09-02
 
 外部审查那份清单里剩下的两条（P0-1 / P0-6 的可做部分）。

{perceptkit-0.2.6 → perceptkit-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: perceptkit
-Version: 0.2.6
+Version: 0.2.7
 Summary: 从设备信号判断:有没有发生值得留意的事、值不值得叫醒一次 agent、以及该怎么把此刻的状况讲给它听。不采集数据、不选数据库、不调模型 —— 存储由宿主实现 StoragePort，编排在包内。
 License: 
                                          Apache License

{perceptkit-0.2.6 → perceptkit-0.2.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "perceptkit"
-version = "0.2.6"
+version = "0.2.7"
 description = "从设备信号判断:有没有发生值得留意的事、值不值得叫醒一次 agent、以及该怎么把此刻的状况讲给它听。不采集数据、不选数据库、不调模型 —— 存储由宿主实现 StoragePort，编排在包内。"
 readme = "README.md"
 requires-python = ">=3.10"

{perceptkit-0.2.6 → perceptkit-0.2.7}/src/perceptkit/kit.py

@@ -190,7 +190,8 @@ class PerceptionKit:
             ],
             # 故意不删的也要列出来 —— 一份只说"删了 0 条"的报告，读不出
             # 「是没到期，还是规则写错了」。
-            "skipped": [{"signal": k, "why": why} for k, why in plan.skipped],
+            "skipped": [{"signal": s.signal, "code": s.code, "detail": s.detail}
+                        for s in plan.skipped],
             "removed": removed,
         }
 

{perceptkit-0.2.6 → perceptkit-0.2.7}/src/perceptkit/retention.py

@@ -93,6 +93,33 @@ class RetentionAction:
     before: _dt.date
 
 
+@dataclass(frozen=True)
+class SkippedSignal:
+    """故意不清的一个信号，以及为什么。
+
+    ``code`` 是稳定的机器可读标识，``detail`` 是给人看的一句话。
+    **宿主的运维界面该用 code 自己渲染** —— 一个库不该替宿主决定报告用什么
+    语言。这里的 detail 是中文（这个包的注释都是中文），直接印进一个英文
+    运维报告里就成了半中半英。
+    """
+
+    signal: str
+    code: str
+    detail: str
+
+    def __iter__(self):
+        """还能按 ``(signal, detail)` 解包 —— 老调用方不用一次全改。"""
+        return iter((self.signal, self.detail))
+
+
+#: 稳定的跳过原因。宿主按这个渲染自己的文案。
+SKIP_NO_HISTORY = "no_history"
+SKIP_DETAILS_PERMANENT = "details_permanent"
+SKIP_DETAILS_UNDECLARED = "details_undeclared"
+SKIP_AGGREGATES_PERMANENT = "aggregates_permanent"
+SKIP_AGGREGATES_UNDECLARED = "aggregates_undeclared"
+
+
 @dataclass
 class RetentionPlan:
     """要删什么，以及**故意不删什么、为什么**。
@@ -103,8 +130,7 @@ class RetentionPlan:
     """
 
     actions: list[RetentionAction] = _field(default_factory=list)
-    #: ``(信号, 为什么跳过)``
-    skipped: list[tuple[str, str]] = _field(default_factory=list)
+    skipped: list[SkippedSignal] = _field(default_factory=list)
 
 
 def plan_retention(
@@ -128,13 +154,13 @@ def plan_retention(
     for key in sorted(signals):
         sig = signals[key]
         if not sig.stores_history:
-            plan.skipped.append((key, "不进历史表，没东西可清"))
+            plan.skipped.append(SkippedSignal(key, SKIP_NO_HISTORY, "不进历史表，没东西可清"))
             continue
 
         if sig.history_retention_days == PERMANENT:
-            plan.skipped.append((key, "明细永久保存"))
+            plan.skipped.append(SkippedSignal(key, SKIP_DETAILS_PERMANENT, "明细永久保存"))
         elif sig.history_retention_days is None:
-            plan.skipped.append((key, "没声明明细保留期 —— 跳过，不替它猜一个"))
+            plan.skipped.append(SkippedSignal(key, SKIP_DETAILS_UNDECLARED, "没声明明细保留期 —— 跳过，不替它猜一个"))
         else:
             plan.actions.append(RetentionAction(
                 key, "observations",
@@ -142,9 +168,9 @@ def plan_retention(
 
         agg_days = sig.effective_aggregate_retention_days
         if agg_days == PERMANENT:
-            plan.skipped.append((key, "日聚合永久保存"))
+            plan.skipped.append(SkippedSignal(key, SKIP_AGGREGATES_PERMANENT, "日聚合永久保存"))
         elif agg_days is None:
-            plan.skipped.append((key, "没声明聚合保留期 —— 跳过，不替它猜一个"))
+            plan.skipped.append(SkippedSignal(key, SKIP_AGGREGATES_UNDECLARED, "没声明聚合保留期 —— 跳过，不替它猜一个"))
         else:
             plan.actions.append(RetentionAction(
                 key, "aggregates",

{perceptkit-0.2.6 → perceptkit-0.2.7}/tests/test_retention_entry.py

@@ -42,7 +42,8 @@ def test_details_and_aggregates_get_their_own_cutoffs():
     # 明细 7 天要清，聚合永久不许出现在动作里。
     assert [a.kind for a in photo] == ["observations"]
     assert photo[0].before == (NOW - timedelta(days=7)).date()
-    assert ("photo_library_added", "日聚合永久保存") in plan.skipped
+    assert any(sk.signal == "photo_library_added"
+               and sk.code == "aggregates_permanent" for sk in plan.skipped)
 
 
 def test_permanent_never_appears_as_something_to_delete():
@@ -62,14 +63,31 @@ def test_a_signal_with_no_declared_retention_is_skipped_not_defaulted():
                   history_retention_days=None, aggregate_retention_days=None)
     plan = plan_retention({"audio_route": sig}, now=NOW)
     assert plan.actions == []
-    assert all("不替它猜" in why for _, why in plan.skipped)
+    assert all(sk.code.endswith("undeclared") for sk in plan.skipped)
 
 
 def test_the_plan_says_why_it_skipped_things():
     """只说"删了 0 条"的报告，读不出「是没到期，还是规则写错了」。"""
     plan = _plan()
     assert plan.skipped
-    assert all(why.strip() for _, why in plan.skipped)
+    assert all(sk.detail.strip() for sk in plan.skipped)
+
+
+def test_skip_reasons_carry_a_stable_code_for_the_host_to_render():
+    """理由的**文字**是中文（这个包的注释都是中文）。宿主的运维界面不一定是。
+
+    直接把 detail 印进一个英文报告里就成了半中半英 —— 一个库不该替宿主
+    决定报告用什么语言。code 是稳定的，文案归宿主。
+    """
+    from perceptkit.retention import (
+        SKIP_AGGREGATES_PERMANENT, SKIP_DETAILS_PERMANENT, SKIP_NO_HISTORY,
+        SKIP_DETAILS_UNDECLARED, SKIP_AGGREGATES_UNDECLARED,
+    )
+    known = {SKIP_NO_HISTORY, SKIP_DETAILS_PERMANENT, SKIP_DETAILS_UNDECLARED,
+             SKIP_AGGREGATES_PERMANENT, SKIP_AGGREGATES_UNDECLARED}
+    plan = _plan()
+    assert {sk.code for sk in plan.skipped} <= known
+    assert all(sk.code for sk in plan.skipped)
 
 
 def test_a_dry_run_removes_nothing():

{perceptkit-0.2.6 → perceptkit-0.2.7}/uv.lock

@@ -43,7 +43,7 @@ wheels = [
 
 [[package]]
 name = "perceptkit"
-version = "0.2.6"
+version = "0.2.7"
 source = { editable = "." }
 
 [package.optional-dependencies]