storepy 3.2.0__tar.gz → 3.4.0__tar.gz

{storepy-3.2.0 → storepy-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: storepy
-Version: 3.2.0
+Version: 3.4.0
 Summary: Multi-backend data layer for Python asyncio (MongoDB, MySQL, SQLite, PostgreSQL): pure JSON schemas, GQL tree queries compiled to a single native query, GROUP BY/HAVING aggregation, computed columns, soft-delete and role-based access control
 Author-email: leo <coen_ddt@qq.com>
 License-Expression: MIT

{storepy-3.2.0 → storepy-3.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "storepy"
-version = "3.2.0"
+version = "3.4.0"
 description = "Multi-backend data layer for Python asyncio (MongoDB, MySQL, SQLite, PostgreSQL): pure JSON schemas, GQL tree queries compiled to a single native query, GROUP BY/HAVING aggregation, computed columns, soft-delete and role-based access control"
 readme = "README.md"
 requires-python = ">=3.10"

{storepy-3.2.0 → storepy-3.4.0}/src/py_store/__init__.py

@@ -26,6 +26,7 @@ from pymongo.errors import PyMongoError
 
 from . import (
     ask,
+    cache,
     crud,
     datasource,
     ddl,
@@ -250,6 +251,19 @@ class Store:
         """注入进程级 ns 标签（tenant/env），供落库事件附加（进程级隔离下天然单 ns）"""
         feedback.set_meta({'tenant': tenant, 'env': env})
 
+    async def flushFeedback(self):
+        """等待全部在途 __feedback 落库完成（graceful shutdown 前调用；对齐 node store.flushFeedback）"""
+        await feedback.flush()
+
+    # ── 缓存状态注记（B6；见 cache.py）──
+    def setCacheStatus(self, fn):
+        """注册缓存状态 provider：`x-cache` 注记位唯一取值来源；未注册恒 BYPASS"""
+        return cache.set_cache_status(fn)
+
+    def cacheStatus(self, ctx: dict | None = None) -> str:
+        """当前响应的缓存状态注记（恒为 HIT|MISS|BYPASS 之一）"""
+        return cache.cache_status(permission.get_context() if ctx is None else ctx)
+
     # ── 工作流编排（首批：线性 + when 守卫 + fail-fast；见 workflow.py 与设计文档）──
     def registerWorkflow(self, defn: dict, ctx: dict | None = None) -> dict:
         """注册工作流定义（可选 ``ctx`` 过定义层门禁；默认 Open。白名单外显式 Err 含 WORKFLOW_UNSUPPORTED）"""
@@ -307,6 +321,10 @@ class Store:
     ensure_builtins = ensureBuiltins
     enable_feedback_table = enableFeedbackTable
     set_feedback_meta = setFeedbackMeta
+    flush_feedback = flushFeedback
+    # 缓存状态注记（蛇形别名与上方驼峰同实现）
+    set_cache_status = setCacheStatus
+    cache_status = cacheStatus
 
     # ── 其余 API 显式绑定（staticmethod：避免实例化后 self 注入）──
     # Schema 管理
@@ -450,3 +468,17 @@ async def init(connections):
     await _create_indexes_if_needed()
 
     return store
+
+
+def __getattr__(name: str):
+    """惰性暴露框架统一入口 ``create_app``。
+
+    放在模块级 ``__getattr__``（PEP 562）而非顶部 ``from .bootstrap import create_app``，
+    以规避包内循环导入；因此无模块级导入，兼容 ruff E402 / I001。
+    """
+    if name == "create_app":
+        from .bootstrap import create_app
+
+        return create_app
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+

storepy-3.4.0/src/py_store/bootstrap.py

@@ -0,0 +1,19 @@
+"""框架统一入口（Python）：init → 逐条 register；协议面由接入方另行挂载。
+
+注意：``init`` / ``store`` 用函数内惰性导入——``__init__.py`` 末尾导入本模块，
+若此处顶层 ``from . import init, store`` 会在包尚未完成初始化时取到未定义名，
+故延迟到调用期解析。
+"""
+
+from typing import Any, Iterable
+
+
+async def create_app(*, datasource: Any, schemas: Iterable[dict] = (), ctx: Any = None):
+    from . import init, store  # 延迟导入，规避包内循环导入
+
+    if datasource is None:
+        raise ValueError("ERR_BOOTSTRAP:缺 datasource")
+    await init(datasource)
+    for defn in schemas:
+        store.register(defn, ctx)
+    return {"store": store}

storepy-3.4.0/src/py_store/cache.py

@@ -0,0 +1,36 @@
+"""缓存状态注记（B6）—— 协议层 `x-cache` 响应头的唯一取值来源。
+
+本轮只落**注记位**：不实现任何实际缓存。无 provider（默认）恒返回 'BYPASS'
+（响应未经过缓存）——注记必须为真，禁把无缓存谎报为 HIT/MISS。
+provider 由接入方在实现缓存时经 set_cache_status 注入，签名 (ctx) -> 'HIT'|'MISS'|'BYPASS'。
+"""
+
+from .feedback import emit
+
+_VALUES = ('HIT', 'MISS', 'BYPASS')
+_provider = None
+
+
+def set_cache_status(fn):
+    """注册缓存状态 provider；传 None / 非可调用恢复默认（恒 BYPASS）"""
+    global _provider
+    _provider = fn if callable(fn) else None
+
+
+def cache_status(ctx=None):
+    """取当前响应的缓存状态注记（恒为 HIT|MISS|BYPASS 之一；非法/异常 → BYPASS + 反馈留痕）"""
+    if _provider is None:
+        return 'BYPASS'
+    try:
+        v = _provider(ctx)
+    except Exception as e:  # 异常回落 BYPASS 且必须留痕（禁静默）
+        emit({'type': 'cache_status_failed', 'code': 'cacheStatusFailed', 'layer': 'host',
+              'message': f'缓存状态 provider 抛错: {e}',
+              'hint': '检查 set_cache_status 注入的 provider；本轮注记位不实现缓存，异常即回落 BYPASS'})
+        return 'BYPASS'
+    if v not in _VALUES:
+        emit({'type': 'cache_status_invalid', 'code': 'cacheStatusInvalid', 'layer': 'host',
+              'message': f'缓存状态取值非法: {v!r}（值域 HIT|MISS|BYPASS）',
+              'hint': 'provider 返回值必须为 HIT/MISS/BYPASS 之一；非法值回落 BYPASS'})
+        return 'BYPASS'
+    return v

{storepy-3.2.0 → storepy-3.4.0}/src/py_store/feedback.py

@@ -25,6 +25,9 @@ _meta = {'tenant': '', 'env': ''}
 # 落库失败累计计数（进程级；>0 表示有事件未入表——可观测，不静默）
 _fail_count = 0
 
+# 在途落库任务（进程级；graceful shutdown 前经 flush() 收口，消除 fire-and-forget 丢事件窗口 D8）
+_pending: set = set()
+
 
 def get_sink():
     """当前 sink（None = 默认 stderr 行为）；供接管方保存原值、退出时恢复（token-set/reset 同构）"""
@@ -82,7 +85,9 @@ def enable_feedback_table(store):
         except RuntimeError:
             loop = None
         if loop is not None:
-            loop.create_task(_write_feedback(store, row))
+            task = loop.create_task(_write_feedback(store, row))
+            _pending.add(task)
+            task.add_done_callback(_pending.discard)   # 完成即出集合
         else:
             _fail('无运行中事件循环，__feedback 事件未落库')
 
@@ -90,6 +95,15 @@ def enable_feedback_table(store):
     return lambda: set_sink(prev)
 
 
+async def flush():
+    """等待全部在途 `__feedback` 落库任务完成（graceful shutdown 前调用）。
+
+    落库失败已由 ``_write_feedback`` 计为 ``fail_count``（不抛），故此处 ``gather`` 不冒泡。
+    """
+    while _pending:
+        await asyncio.gather(*list(_pending), return_exceptions=True)
+
+
 def emit(event):
     """产出一条反馈事件：有 sink 回调之；否则打印 stderr（允许拦截，禁止静默）"""
     if _sink is not None:

{storepy-3.2.0 → storepy-3.4.0}/src/py_store/metadef.py

@@ -110,6 +110,28 @@ class MetaDefError(ValueError):
 
 # ─── 纯逻辑（双端逐字节等价；parity 锚） ───────────────────────
 
+def _assert_serializable(value, path=''):
+    """深度检查 defn 是否含函数值 —— 持久化定义 = 纯 JSON 契约（N3）。
+
+    必须先于 ``_to_core_defn`` 调用：后者会把 ``fn/asyncFn`` 归一为 ``True`` 占位、把其余函数剔除，
+    使「含回调定义」静默降级入库，回滚/restore 即丢失回调（缺陷台账 D17）。
+    本函数在归一化**之前**显式拒绝（fail-fast），文案对齐 node ``_assertSerializable``（逐字节一致）。
+    """
+    if callable(value):
+        raise MetaDefError(
+            f'metadef: 定义含函数回调（{path}），不可持久化；'
+            '回调类定义禁止经控制面发布（定义内改用 fnRef 字符串，实现由宿主 register 时注入）'
+        )
+    if value is None or not isinstance(value, (dict, list, tuple)):
+        return
+    if isinstance(value, dict):
+        for k, v in value.items():
+            _assert_serializable(v, f'{path}.{k}' if path else str(k))
+    else:
+        for i, v in enumerate(value):
+            _assert_serializable(v, f'{path}.{i}' if path else str(i))
+
+
 def stable_stringify(value):
     """稳定序列化（键序无关）：与 node ``_stableStringify`` 逐字节等价"""
     return json.dumps(value, sort_keys=True, separators=(',', ':'), ensure_ascii=False)
@@ -204,6 +226,7 @@ async def persist_def(store, defn, opts):
         raise MetaDefError('metadef: defn.name 必填')
     opts = opts or {}
     _, table = _kind_of(opts)
+    _assert_serializable(defn, '')                  # ← 新增：先于 IO 与归一化
     name = defn['name']
     rows = await list_defs(store, {'tenant': opts.get('tenant'), 'env': opts.get('env'),
                                    'name': name, 'kind': opts.get('kind')})

{storepy-3.2.0 → storepy-3.4.0}/src/py_store/workflow.py

@@ -16,6 +16,7 @@ import json
 import re
 import time
 from contextlib import contextmanager
+from typing import List
 
 from . import permission as _permission
 from .crud.exec import _call, _sources_of, run_atomic
@@ -268,6 +269,63 @@ def validate_defn(defn):
     return errors
 
 
+def _collect_param_keys(ast_value, out=None):
+    """递归收集 core 返回 ast 中所有 ``params`` 对象的字符串值（@key 名）。"""
+    if out is None:
+        out = set()
+    if isinstance(ast_value, dict):
+        params = ast_value.get('params')
+        if isinstance(params, dict):
+            # core `ast.params` 的值为 `@key` 形态（含前导 @，core parse.rs::parse_params
+            # 保留 ref 原值）；归一化去掉前导 @，使错误文案为 `@c0` 而非 `@@c0`。
+            for v in params.values():
+                if isinstance(v, str) and v:
+                    out.add(v[1:] if v.startswith('@') else v)
+        for v in ast_value.values():
+            _collect_param_keys(v, out)
+    elif isinstance(ast_value, _LIST_TYPES):
+        for v in ast_value:
+            _collect_param_keys(v, out)
+    return out
+
+
+def validate_planable(defn):
+    """注册期「只校验不绑参」可规划性校验 → 错误列表（空 = 通过）。纯内存、无 IO、无参数值绑定。
+
+    ① 结构性可规划：对每个 query 步骤的 gql 调 core 门面
+       ``_core.build_pipeline(gql, {}, None)``（params 传 {} = 不绑参；ctx 传 None）；
+       不可规划 → core 抛异常，此处汇聚为注册期错误。
+    ② 参数键完整：返回体 ``ast`` 暴露 ``params``（槽位→@key，含嵌套关系）；
+       gql 引用的每个 ``@key`` 须在 ``step['params']`` 顶层存在。
+
+    与 ``validate_defn``（纯函数）分职：本函数需要 core 注册表，故独立、不入 validate_defn。
+    """
+    errors: List[str] = []
+    if not isinstance(defn, dict):
+        return errors
+    steps = defn.get('steps')
+    if not isinstance(steps, _LIST_TYPES):
+        return errors
+    for i, step in enumerate(steps):
+        if not isinstance(step, dict) or step.get('op') != 'query':
+            continue
+        gql = step.get('gql')
+        if not isinstance(gql, str):
+            continue
+        where = f'steps[{i}]'
+        try:
+            built = _core.build_pipeline(gql, {}, None)
+        except Exception as e:  # 透传 core 文案，与 node 逐字节对齐
+            errors.append(f'{where}: gql 不可规划: {e}')
+            continue
+        params = step.get('params')
+        provided = set(params) if isinstance(params, dict) else set()
+        for key in sorted(_collect_param_keys(built.get('ast') if isinstance(built, dict) else None)):
+            if key not in provided:
+                errors.append(f'{where}: gql 引用了未提供的参数 @{key}（params 须提供该键）')
+    return errors
+
+
 def _split_when(when):
     """when → (op, param_key)；无歧义文法：含 exists 键即 op=exists（is 作参数键），
     其余算子的右值键统一 than（is 键已被 exists 参数占用；is/eq 算子同用 than）"""
@@ -317,6 +375,10 @@ def register(defn, ctx=None):
     errors = validate_defn(defn)
     if errors:
         raise WorkflowError('WORKFLOW_UNSUPPORTED: ' + '；'.join(errors))
+    # B1：注册期「只校验不绑参」可规划性（结构 + 参数键完整）；独立于纯函数 validate_defn
+    plan_errors = validate_planable(defn)
+    if plan_errors:
+        raise WorkflowError('WORKFLOW_UNSUPPORTED: ' + '；'.join(plan_errors))
     name = defn['name']
     if name in _workflows:
         if _workflows[name] == defn:

{storepy-3.2.0 → storepy-3.4.0}/src/storepy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: storepy
-Version: 3.2.0
+Version: 3.4.0
 Summary: Multi-backend data layer for Python asyncio (MongoDB, MySQL, SQLite, PostgreSQL): pure JSON schemas, GQL tree queries compiled to a single native query, GROUP BY/HAVING aggregation, computed columns, soft-delete and role-based access control
 Author-email: leo <coen_ddt@qq.com>
 License-Expression: MIT

{storepy-3.2.0 → storepy-3.4.0}/src/storepy.egg-info/SOURCES.txt

@@ -4,6 +4,8 @@ pyproject.toml
 src/py_store/__init__.py
 src/py_store/ask.py
 src/py_store/ask_knowledge.md
+src/py_store/bootstrap.py
+src/py_store/cache.py
 src/py_store/core.py
 src/py_store/datasource.py
 src/py_store/ddl.py
@@ -36,8 +38,10 @@ src/storepy.egg-info/dependency_links.txt
 src/storepy.egg-info/requires.txt
 src/storepy.egg-info/top_level.txt
 tests/test_ask.py
+tests/test_cache.py
 tests/test_coverage_margin.py
 tests/test_federation_e2e.py
+tests/test_feedback_flush.py
 tests/test_host_contract.py
 tests/test_host_paths.py
 tests/test_metadef.py

storepy-3.4.0/tests/test_cache.py

@@ -0,0 +1,64 @@
+"""缓存状态注记（B6）单测：注记必须为真——无 provider 恒 BYPASS；
+非法值/抛错回落 BYPASS 且走反馈通道留痕（不打断响应，禁静默）。
+
+运行：$env:LOCAL_CORE='1'; $env:PYTHONPATH='py-store/src'; python -m pytest py-store/tests/test_cache.py -q
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / 'src'))
+
+from py_store import cache, feedback
+
+
+def _collect(body):
+    """收集期间 emit 的事件（用后恢复原 sink，并复位 provider 防跨用例污染）"""
+    prev = feedback.get_sink()
+    events = []
+    feedback.set_sink(events.append)
+    try:
+        body()
+    finally:
+        feedback.set_sink(prev)
+        cache.set_cache_status(None)
+    return events
+
+
+def test_no_provider_bypass():
+    cache.set_cache_status(None)
+    assert cache.cache_status() == 'BYPASS'
+
+
+def test_invalid_value_bypass_with_feedback():
+    def _body():
+        cache.set_cache_status(lambda ctx: 'NOPE')
+        assert cache.cache_status() == 'BYPASS'
+
+    events = _collect(_body)
+    assert len(events) == 1
+    assert events[0]['code'] == 'cacheStatusInvalid'
+    assert events[0]['layer'] == 'host'
+
+
+def test_provider_raises_bypass_with_feedback():
+    def _body():
+        def _boom(ctx):
+            raise RuntimeError('boom')
+
+        cache.set_cache_status(_boom)
+        assert cache.cache_status() == 'BYPASS'
+
+    events = _collect(_body)
+    assert len(events) == 1
+    assert events[0]['code'] == 'cacheStatusFailed'
+    assert 'boom' in events[0]['message']
+
+
+def test_valid_value_passthrough():
+    def _body():
+        cache.set_cache_status(lambda ctx: 'HIT')
+        assert cache.cache_status() == 'HIT'
+
+    events = _collect(_body)
+    assert events == []

storepy-3.4.0/tests/test_feedback_flush.py

@@ -0,0 +1,40 @@
+"""A3 残留（D8）：__feedback 落库 flush 与失败不静默 —— mock store，不连库。"""
+import asyncio
+
+from py_store import feedback
+
+
+class _MockStore:
+    def __init__(self):
+        self.rows = []
+
+    async def insert(self, name, row):
+        self.rows.append((name, row))
+        return row
+
+
+class _BoomStore:
+    async def insert(self, name, row):
+        raise RuntimeError('boom')
+
+
+def test_flush_persists_inflight():
+    async def run():
+        s = _MockStore()
+        dispose = feedback.enable_feedback_table(s)
+        feedback.emit({'type': 't', 'code': 'c', 'layer': 'host', 'message': 'm', 'hint': 'h'})
+        await feedback.flush()
+        assert len(s.rows) == 1 and s.rows[0][0] == '__feedback' and s.rows[0][1]['code'] == 'c'
+        dispose()
+    asyncio.run(run())
+
+
+def test_flush_failure_not_silent():
+    async def run():
+        before = feedback.fail_count()
+        dispose = feedback.enable_feedback_table(_BoomStore())
+        feedback.emit({'type': 't', 'code': 'c', 'layer': 'host'})
+        await feedback.flush()
+        assert feedback.fail_count() == before + 1
+        dispose()
+    asyncio.run(run())

{storepy-3.2.0 → storepy-3.4.0}/tests/test_metadef.py

@@ -232,6 +232,37 @@ def test_d21_rollback_visible_via_restore_defs():
     _run_in_sqlite(_run)
 
 
+# ─── N3：回调类定义不可持久化（持久化定义 = 纯 JSON）─────────────
+
+def test_n3_callback_defn_rejected_no_row():
+    """N3：含函数回调的 defn 经 persist_def 显式拒绝，库内零新增行"""
+
+    async def _run(store):
+        o = {'tenant': 't12', 'env': 'dev'}
+        defn = {'name': 'CbItem', 'fields': {'_id': {'type': 'string'}},
+                'computes': {'total': {'fn': lambda item: 1}}}
+        with pytest.raises(MetaDefError, match='不可持久化'):
+            await md.persist_def(store, defn, o)
+        rows = await md.list_defs(store, {**o, 'name': 'CbItem'})
+        assert len(rows) == 0  # 拒绝先于 IO：库内零新增行
+
+    _run_in_sqlite(_run)
+
+
+def test_n3_pure_json_defn_persists_same_shape():
+    """N3：纯 JSON defn（fnRef 字符串）正常落库且与入参同形"""
+
+    async def _run(store):
+        o = {'tenant': 't12', 'env': 'dev'}
+        defn = {'name': 'CbPure', 'fields': {'_id': {'type': 'string'}},
+                'computes': {'total': {'fnRef': 'sum', 'type': 'int'}}}
+        row = await md.persist_def(store, defn, o)
+        assert row['version'] == 1
+        assert md.same_defn(row['defn'], defn)
+
+    _run_in_sqlite(_run)
+
+
 # ─── workflow 定义持久化（kind=workflow，落 __workflowDef；审计 §8 N1）───────
 
 def test_wf_persist_idempotent_versioning_and_list():

{storepy-3.2.0 → storepy-3.4.0}/tests/test_workflow.py

@@ -12,9 +12,23 @@ import pytest
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent / 'src'))
 
+from py_store import schema as sc
 from py_store import workflow as wf
 from py_store.workflow import WorkflowError
 
+
+# B1 前置：GOOD 的 gql/mutation 引用 Inventory，注册期可规划性校验要求其已注册。
+# 本仓 conftest 的模块级夹具会在每模块清空注册表（clear_schemas），故按约定入口
+# `_register_test_schemas` 提供（只定义不执行，由夹具在清场后重放）。
+def _register_test_schemas():
+    sc.register({
+        'name': 'Inventory', 'collection': 'inventory', 'idPrefix': 'inv',
+        'fields': {
+            '_id': {'type': 'string'}, 'stock': {'type': 'int'},
+            'productId': {'type': 'string'}, 'warehouse': {'type': 'string'},
+        },
+    })
+
 GOOD = {
     'name': 'placeOrder',
     'read': ['admin', 'ops'],
@@ -322,3 +336,26 @@ def test_parity_run_doc_shape():
         assert sorted(run_doc['steps'][1]) == ['as', 'op', 'state']
     finally:
         wf._workflows.pop('shapeWf', None)
+
+
+# ─── B1：注册期 GQL 可规划性校验（结构 + 参数键完整） ─────────
+
+def test_b1_planable_unplanned_rejected():
+    bad = {'name': 'noModelWf', 'steps': [
+        {'op': 'query', 'as': 'a', 'gql': 'NoSuchModel{_id}', 'params': {}}]}
+    assert len(wf.validate_planable(bad)) == 1
+    with pytest.raises(wf.WorkflowError, match=r'WORKFLOW_UNSUPPORTED: steps\[0\]: gql 不可规划'):
+        wf.register(bad)
+
+
+def test_b1_planable_missing_param_key():
+    bad = {'name': 'missParamWf', 'steps': [
+        {'op': 'query', 'as': 'a', 'gql': 'Inventory($condition:@c0){_id}', 'params': {}}]}
+    assert wf.validate_planable(bad) == [
+        'steps[0]: gql 引用了未提供的参数 @c0（params 须提供该键）']
+
+
+def test_b1_planable_ok():
+    assert wf.validate_planable({'name': 'okWf', 'steps': [
+        {'op': 'query', 'as': 'a', 'gql': 'Inventory($condition:@c0){_id, stock}',
+         'params': {'c0': {'stock': 1}}}]}) == []