store-grpc-py 0.1.0__tar.gz

store_grpc_py-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: store-grpc-py
+Version: 0.1.0
+Summary: gRPC adapter that auto-generates a .proto service per schema for py-store (schema-driven CRUD over GQL, proto-first with runtime compilation, zero manual protoc)
+License: MIT
+Keywords: py-store,storepy,grpc,protobuf,crud,gql
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: grpc
+Requires-Dist: grpcio>=1.60; extra == "grpc"
+Requires-Dist: grpcio-tools>=1.60; extra == "grpc"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: grpcio>=1.60; extra == "dev"
+Requires-Dist: grpcio-tools>=1.60; extra == "dev"
+
+# store-grpc-py
+
+py-store 的 gRPC 皮肤（`store-grpc-py`，PyPI）。规范与用法见仓库根 README 与 `../spec/`。

store_grpc_py-0.1.0/README.md

@@ -0,0 +1,3 @@
+# store-grpc-py
+
+py-store 的 gRPC 皮肤（`store-grpc-py`，PyPI）。规范与用法见仓库根 README 与 `../spec/`。

store_grpc_py-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "store-grpc-py"
+version = "0.1.0"
+description = "gRPC adapter that auto-generates a .proto service per schema for py-store (schema-driven CRUD over GQL, proto-first with runtime compilation, zero manual protoc)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["py-store", "storepy", "grpc", "protobuf", "crud", "gql"]
+dependencies = []
+
+[project.optional-dependencies]
+grpc = ["grpcio>=1.60", "grpcio-tools>=1.60"]
+dev = ["pytest>=8", "grpcio>=1.60", "grpcio-tools>=1.60"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

store_grpc_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

store_grpc_py-0.1.0/src/store_grpc/__init__.py

@@ -0,0 +1,28 @@
+"""store_grpc_py — 为 py-store 已注册 schema 自动生成 gRPC service。
+
+语义依据：../../spec/*.md（双端 parity，改动先改 spec）。
+设计哲学：gRPC 只是 GQL 的又一层 RPC 皮肤 —— 适配层零语义发明。
+proto-first 双出口：
+  build_proto(store, **opts)  → .proto 文本（IDL 事实源，纯构建，零 gRPC 依赖）
+  export_proto(store, **opts) → 同上（命名对齐 store-graphql 的 export_sdl，喂外部 protoc / codegen）
+  create_server(store, **opts) → grpcio server（同一份 proto 文本运行时编译注册，零手工 protoc）
+
+store 端口契约见 spec/00：list/get/query/query_one/insert/update/remove/set_context。
+"""
+
+from .proto import build_proto, export_proto, filter_archived, service_name
+
+__all__ = [
+    "build_proto",
+    "export_proto",
+    "filter_archived",
+    "service_name",
+    "create_server",
+]
+
+
+def create_server(*args, **kwargs):
+    """延迟导入承载层（grpcio + grpcio-tools 为可选依赖）。"""
+    from .server import create_server as impl
+
+    return impl(*args, **kwargs)

store_grpc_py-0.1.0/src/store_grpc/errors.py

@@ -0,0 +1,105 @@
+"""spec/03 — 错误判定链（判定顺序双端一致，改动必须先改 spec）。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from grpc import StatusCode
+
+ERR_GQL_PARSE_PREFIX = "ERR_GQL_PARSE:"
+ERR_PERMISSION_PREFIX = "ERR_PERMISSION:"
+
+GUARD_CODES_INVALID = ("INVALID_PARAM", "INVALID_BODY")
+
+
+@dataclass
+class MappedError(Exception):
+    """已映射的 gRPC 错误：status / details / 稳定码（trailer store-error-code）。"""
+
+    status: StatusCode
+    details: str
+    code: str
+
+    def __str__(self) -> str:  # abort 需要 message 可读
+        return self.details or self.code
+
+
+def store_code(err: BaseException) -> str:
+    """store 错误的分类码：优先 err.code，缺省用类型名，再缺省通用码（与 REST storeCode 链一致）。"""
+    return getattr(err, "code", None) or type(err).__name__ or "STORE_ERROR"
+
+
+class _GuardError(Exception):
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+
+
+def invalid_param(message: str) -> _GuardError:
+    return _GuardError("INVALID_PARAM", message)
+
+
+def invalid_body(message: str) -> _GuardError:
+    return _GuardError("INVALID_BODY", message)
+
+
+def not_found(message: str) -> _GuardError:
+    return _GuardError("NOT_FOUND", message)
+
+
+class ContextError(_GuardError):
+    def __init__(self, message: str):
+        super().__init__("CONTEXT_ERROR", message)
+
+
+def parse_json_field(raw: str | None, make_err, label: str):
+    """spec/02：空串/None ⇒ None；非法 JSON ⇒ 带码错误。"""
+    if raw is None or raw == "":
+        return None
+    import json
+
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise make_err(f"{label} 不是合法 JSON: {e}") from e
+
+
+def require_json_object(raw: str | None, label: str):
+    """spec/02：必须为 JSON 对象编码（数组/标量/非法 JSON 拒绝）；空 ⇒ None。"""
+    import json
+
+    v = parse_json_field(raw, invalid_body, label)
+    if v is not None and not isinstance(v, dict):
+        raise invalid_body(f"{label} 必须是 JSON 对象编码")
+    return v
+
+
+def map_store_error(err: BaseException, permission_error: type[BaseException] | None) -> MappedError:
+    """spec/03 判定链：适配层守卫 → PermissionError 类 → ERR_PERMISSION: 前缀 → ERR_GQL_PARSE: 前缀 → INTERNAL。
+
+    details 一律原 message 透传、取不到置空串（禁伪造）。
+    """
+    message = str(getattr(err, "args", [None])[0]) if getattr(err, "args", None) else ""
+    if message is None:
+        message = ""
+
+    def fail(status: StatusCode, code: str, details: str | None) -> MappedError:
+        return MappedError(status, details if details is not None else "", code)
+
+    if isinstance(err, _GuardError):
+        if err.code == "NOT_FOUND":
+            return fail(StatusCode.NOT_FOUND, err.code, err.args[0])
+        if err.code == "CONTEXT_ERROR":
+            return fail(StatusCode.UNAUTHENTICATED, err.code, err.args[0])
+        return fail(StatusCode.INVALID_ARGUMENT, err.code, err.args[0])
+
+    if permission_error is not None and isinstance(err, permission_error):
+        return fail(StatusCode.PERMISSION_DENIED, store_code(err), message)
+
+    if message.startswith(ERR_PERMISSION_PREFIX):
+        return fail(StatusCode.PERMISSION_DENIED, "ERR_PERMISSION", message)
+
+    if message.startswith(ERR_GQL_PARSE_PREFIX):
+        return fail(StatusCode.INVALID_ARGUMENT, "GQL_PARSE", message[len(ERR_GQL_PARSE_PREFIX):])
+
+    return fail(StatusCode.INTERNAL, store_code(err), message)

store_grpc_py-0.1.0/src/store_grpc/proto.py

@@ -0,0 +1,112 @@
+"""spec/01 — proto 文本生成（与 node 端 buildProto 逐字一致，双端 byte-identical）。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+ARCHIVE_SUFFIX = "Deleted"
+PACKAGE = "store.v0"
+
+_COMMON_MESSAGES = """message ListRequest {
+  string q = 1;           // 模型名之后的 GQL 余部（参数列表与投影，REST ?q= 同源）；空串 ⇒ 服务端补 schema 投影
+  string params_json = 2; // GQL params（如 {"c0":{"age":{"$gte":18}}}）的 JSON 编码
+}
+
+message GetRequest     { string id = 1; }
+
+message CreateRequest  { string body_json = 1; }
+
+message UpdateRequest  { string id = 1; string set_json = 2; }
+
+message DeleteRequest  { string id = 1; }
+
+message StoreReply     { string data_json = 1; }
+"""
+
+_RPC_COMMENTS = {
+    "list": "列表查询：q 为模型名之后的 GQL 余部（参数列表与投影，与 REST ?q= 同源）；空串 ⇒ 服务端按 schema 投影",
+    "get": "单条查询：按 id_field 精确匹配；无记录 ⇒ NOT_FOUND",
+    "create": "插入：body_json 必须为 JSON 对象编码",
+    "update": "按 id_field 定位后部分更新：set_json 必须为 JSON 对象编码；返回 store.update 原始结果",
+    "remove": "按 id_field 定位删除：返回 store.remove 原始结果",
+}
+
+
+def filter_archived(names: list[str]) -> list[str]:
+    """归档表过滤（spec/01）：`XxxDeleted` 且 `Xxx` 也在列表中 ⇒ 视为归档表（与 store-api / store-graphql 逐字一致）。"""
+    s = set(names)
+    return [n for n in names if not (n.endswith(ARCHIVE_SUFFIX) and n[: -len(ARCHIVE_SUFFIX)] in s)]
+
+
+def service_name(name: str) -> str:
+    """spec/01：service 名 = 模型名首字母大写、其余原样。"""
+    return name[0].upper() + name[1:] if name else name
+
+
+def _x_grpc(defn: Any) -> dict:
+    return (defn or {}).get("x-grpc") or {}
+
+
+def collect_services(store: Any, resources: list[str] | None = None) -> list[dict]:
+    """收集待生成 service（归档过滤 + x-grpc 注记 + Pascal 冲突检测）。"""
+    names = resources if resources is not None else filter_archived(store.list())
+    seen: dict[str, str] = {}
+    out: list[dict] = []
+    get = getattr(store, "get", None)
+    for name in names:
+        defn = None
+        if callable(get):
+            try:
+                defn = get(name)
+            except KeyError:
+                defn = None
+        xg = _x_grpc(defn if isinstance(defn, dict) else None)
+        if xg.get("hidden"):
+            continue  # spec/01 注记：模型级 hidden
+        svc = service_name(name)
+        if svc in seen:
+            raise ValueError(
+                f"ERR_NAME_CONFLICT:模型 \"{name}\" 与 \"{seen[svc]}\" 的 service 名 \"{svc}\" 冲突（spec/01）"
+            )
+        seen[svc] = name
+        description = (defn or {}).get("description") if isinstance(defn, dict) else None
+        out.append({"name": name, "svc": svc, "readonly": bool(xg.get("readonly")), "description": description or ""})
+    return out
+
+
+def _render_service(s: dict) -> str:
+    lines: list[str] = []
+    if s["description"]:
+        lines.append(f"// {s['description']}")
+    lines.append(f"service {s['svc']} {{")
+    lines.append(f"  // {_RPC_COMMENTS['list']}")
+    lines.append(f"  rpc List{s['svc']} (ListRequest) returns (StoreReply);")
+    lines.append(f"  // {_RPC_COMMENTS['get']}")
+    lines.append(f"  rpc Get{s['svc']} (GetRequest) returns (StoreReply);")
+    if not s["readonly"]:
+        lines.append(f"  // {_RPC_COMMENTS['create']}")
+        lines.append(f"  rpc Create{s['svc']} (CreateRequest) returns (StoreReply);")
+        lines.append(f"  // {_RPC_COMMENTS['update']}")
+        lines.append(f"  rpc Update{s['svc']} (UpdateRequest) returns (StoreReply);")
+        lines.append(f"  // {_RPC_COMMENTS['remove']}")
+        lines.append(f"  rpc Delete{s['svc']} (DeleteRequest) returns (StoreReply);")
+    lines.append("}")
+    return "\n".join(lines)
+
+
+def build_proto(store: Any, *, resources: list[str] | None = None) -> str:
+    """spec/01：schema → .proto 文本（纯构建，零 gRPC 依赖）。"""
+    services = collect_services(store, resources)
+    return (
+        "// 由 store-grpc 自动生成 —— 事实源：store 的 JSON schema（与 store-api / store-graphql 同源）\n"
+        'syntax = "proto3";\n\n'
+        f"package {PACKAGE};\n\n"
+        f"{_COMMON_MESSAGES}\n"
+        + "\n\n".join(_render_service(s) for s in services)
+        + "\n"
+    )
+
+
+def export_proto(store: Any, *, resources: list[str] | None = None) -> str:
+    """spec/01：export_proto ≡ build_proto（命名对齐 store-graphql 的 export_sdl）。"""
+    return build_proto(store, resources=resources)

store_grpc_py-0.1.0/src/store_grpc/server.py

@@ -0,0 +1,299 @@
+"""spec/02 — gRPC 承载（grpcio + grpcio-tools，可选依赖；同一份 proto 文本运行时编译，零手工 protoc）。"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import inspect
+import json
+import os
+import re
+
+import tempfile
+from typing import Any, Callable
+
+from .errors import (
+    ContextError,
+    MappedError,
+    invalid_body,
+    invalid_param,
+    map_store_error,
+    not_found,
+    parse_json_field,
+    require_json_object,
+)
+from .proto import PACKAGE, build_proto, collect_services
+
+ContextProvider = Callable[[Any], Any]
+
+_REQ_CLASS_BY_VERB = {
+    "List": "ListRequest",
+    "Get": "GetRequest",
+    "Create": "CreateRequest",
+    "Update": "UpdateRequest",
+    "Delete": "DeleteRequest",
+}
+
+
+_COMPILED_TYPE_NAMES = (
+    "ListRequest",
+    "GetRequest",
+    "CreateRequest",
+    "UpdateRequest",
+    "DeleteRequest",
+    "StoreReply",
+)
+
+
+class _Compiled:
+    """编译产物：按 message 名取消息类（pb.ListRequest / pb.StoreReply ...）。"""
+
+    def __init__(self, classes: dict):
+        for name, cls in classes.items():
+            setattr(self, name, cls)
+
+
+def _compile_proto(proto_text: str):
+    """grpc_tools.protoc 编译 proto 文本 → 独立 descriptor pool 的消息类集合。
+
+    用 --descriptor_set_out + 独立 DescriptorPool（非全局 Default pool）：不同 schema 组合
+    反复编译时同名 message（store.v0.ListRequest 等）不冲突；进程内按内容 hash 缓存。
+    """
+    from google.protobuf import descriptor_pb2, descriptor_pool, message_factory
+    from grpc_tools import protoc
+
+    cache = _compile_proto._cache
+    key = hashlib.sha1(proto_text.encode("utf-8")).hexdigest()
+    if key in cache:
+        return cache[key]
+
+    tmp = tempfile.mkdtemp(prefix="store-grpc-")
+    proto_file = os.path.join(tmp, "store_grpc.proto")
+    with open(proto_file, "w", encoding="utf-8") as f:
+        f.write(proto_text)
+    desc_file = os.path.join(tmp, "store_grpc.desc")
+    rc = protoc.main(
+        ["protoc", f"-I{tmp}", f"--descriptor_set_out={desc_file}", proto_file]
+    )
+    if rc != 0:
+        raise RuntimeError(f"grpc_tools.protoc 编译失败 rc={rc}")
+
+    fds = descriptor_pb2.FileDescriptorSet()
+    with open(desc_file, "rb") as f:
+        fds.ParseFromString(f.read())
+    pool = descriptor_pool.DescriptorPool()
+    for fd in fds.file:
+        pool.Add(fd)
+
+    classes = {
+        name: message_factory.GetMessageClass(pool.FindMessageTypeByName(f"{PACKAGE}.{name}"))
+        for name in _COMPILED_TYPE_NAMES
+    }
+    module = _Compiled(classes)
+    cache[key] = module
+    return module
+
+
+_compile_proto._cache = {}
+
+
+def _run_coro(coro):
+    """同步承载执行协程：工作线程内建私有事件循环（py-store 实例方法为 async，spec/02 py 端差异）。"""
+    import asyncio
+
+    return asyncio.run(coro)
+
+
+def _run_maybe_coro(fn, *args):
+    result = fn(*args)
+    if inspect.isawaitable(result):
+        result = _run_coro(result)
+    return result
+
+
+async def _maybe_await(value):
+    """store 方法同步 / async 双兼容（py-store 实例方法为 async，mock 可为同步）。"""
+    if inspect.isawaitable(value):
+        return await value
+    return value
+
+
+def _schema_projection(store: Any, name: str) -> str:
+    """spec/02：fields + computes 均视为字段（与 store-graphql 对齐）；取不到 / 空 ⇒ 空串。"""
+    fields: dict | None = None
+    get = getattr(store, "get", None)
+    if callable(get):
+        try:
+            meta = get(name)
+        except KeyError:
+            meta = None
+        if isinstance(meta, dict):
+            fields = {**(meta.get("fields") or {}), **(meta.get("computes") or {})}
+    keys = list((fields or {}).keys())
+    return f" {{ {', '.join(keys)} }}" if keys else ""
+
+
+def _make_handlers(store: Any, s: dict, *, id_field: str, context_provider: ContextProvider | None, permission_error, pb):
+    name, svc, readonly = s["name"], s["svc"], s["readonly"]
+    proj = _schema_projection(store, name)
+    store_set_context = store.set_context
+
+    def wrap(fn: Callable[[Any], Any]):
+        def behavior(request, context):
+            try:
+                if context_provider is not None:
+                    try:
+                        ctx = context_provider(dict(context.invocation_metadata() or ()))
+                        if inspect.isawaitable(ctx):
+                            # 同步 grpcio 承载：provider 的 awaitable 结果经私有事件循环执行
+                            ctx = _run_coro(ctx)
+                    except MappedError:
+                        raise
+                    except Exception as e:  # noqa: BLE001 — spec/02：权限类/前缀 ⇒ PERMISSION_DENIED；其余 ⇒ UNAUTHENTICATED
+                        if permission_error is not None and isinstance(e, permission_error):
+                            raise
+                        if str(e).startswith("ERR_PERMISSION:"):
+                            raise
+                        raise ContextError(str(e) or "") from e
+                    # spec/02：None 同样显式注入（set_context(None) 清除语义必须落地，防跨请求残留）
+                    _run_maybe_coro(store_set_context, ctx)
+                data = _run_maybe_coro(fn, request)
+                return pb.StoreReply(data_json=json.dumps(data, ensure_ascii=False))
+            except Exception as e:  # noqa: BLE001 — 单一错误出口：一切异常过 spec/03 判定链（禁静默）
+                mapped = e if isinstance(e, MappedError) else map_store_error(e, permission_error)
+                context.set_trailing_metadata((("store-error-code", mapped.code),))
+                context.abort(mapped.status, mapped.details)
+
+        return behavior
+
+    async def _list(req):
+        params = parse_json_field(req.params_json, invalid_param, "params_json")
+        # spec/02：q 缺失 → schema 投影；q 存在 → 投影完全由 q 决定，适配层不追加
+        gql = name + (req.q or proj)
+        return await _maybe_await(store.query(gql, params))
+
+    async def _get(req):
+        data = await _maybe_await(store.query_one(f"{name}($condition: @c0){proj}", {"c0": {id_field: req.id}}))
+        if data is None:
+            raise not_found(f"记录不存在: {id_field}={req.id}")
+        return data
+
+    handlers = {
+        f"List{svc}": wrap(_list),
+        f"Get{svc}": wrap(_get),
+    }
+    if not readonly:
+
+        async def _create(req):
+            body = require_json_object(req.body_json, "body_json")
+            if body is None:
+                raise invalid_body("body_json 必须是 JSON 对象编码")
+            return await _maybe_await(store.insert(name, body))
+
+        async def _update(req):
+            set_ = require_json_object(req.set_json, "set_json")
+            if set_ is None:
+                raise invalid_body("set_json 必须是 JSON 对象编码")
+            return await _maybe_await(store.update(name, {id_field: req.id}, set_))
+
+        async def _delete(req):
+            return await _maybe_await(store.remove(name, {id_field: req.id}))
+
+        handlers.update(
+            {
+                f"Create{svc}": wrap(_create),
+                f"Update{svc}": wrap(_update),
+                f"Delete{svc}": wrap(_delete),
+            }
+        )
+    return handlers
+
+
+class _Router:
+    """按 method 路由（'/store.v0.{svc}/{rpc}'）→ RpcMethodHandler；未注册路径返回 None（grpcio ⇒ UNIMPLEMENTED）。"""
+
+    def __init__(self, pb: Any, routes: dict[str, Callable], handler_factory: Callable):
+        self._pb = pb
+        self._routes = routes
+        self._handler = handler_factory
+
+    def service(self, handler_call_details):
+        behavior = self._routes.get(handler_call_details.method or "")
+        if behavior is None:
+            return None
+        verb = re.match(r"^(List|Get|Create|Update|Delete)", behavior.rpc).group(1)
+        req_cls = getattr(self._pb, _REQ_CLASS_BY_VERB[verb])
+        return self._handler(
+            behavior,
+            request_deserializer=req_cls.FromString,
+            response_serializer=self._pb.StoreReply.SerializeToString,
+        )
+
+
+class GrpcServer:
+    """承载句柄：.server / .pb / .proto / .port / .stop(grace)（与 node 端 { server, proto, port, shutdown } 同构）。"""
+
+    def __init__(self, server: Any, pb: Any, proto: str, port: int | None):
+        self.server = server
+        self.pb = pb
+        self.proto = proto
+        self.port = port
+
+    def stop(self, grace: float | None = None) -> None:
+        self.server.stop(grace)
+
+
+def create_server(
+    store: Any,
+    *,
+    port: int | None = None,
+    host: str = "127.0.0.1",
+    resources: list[str] | None = None,
+    id_field: str = "_id",
+    context_provider: ContextProvider | None = None,
+    permission_error: type[BaseException] | None = None,
+) -> GrpcServer:
+    """spec/02：注册 service 并按需监听。port 给定 ⇒ start 后返回（0 ⇒ 随机端口）；None ⇒ 仅注册不监听。
+
+    承载依赖缺失 ⇒ 抛带安装指引的错误（禁静默降级）。
+    """
+    try:
+        import grpc  # noqa: F401
+        from grpc_tools import protoc  # noqa: F401
+    except ImportError as e:  # noqa: F841 — 报错信息自身已含原因
+        raise ImportError(
+            "create_server 需要安装 grpcio 与 grpcio-tools：pip install 'store-grpc-py[grpc]'；"
+            "或仅用 build_proto / export_proto 自行承载"
+        ) from e
+
+    import grpc
+
+    proto_text = build_proto(store, resources=resources)
+    pb = _compile_proto(proto_text)
+    services = collect_services(store, resources)
+
+    if permission_error is None:
+        permission_error = getattr(store, "PermissionError", None)
+
+    routes: dict[str, Any] = {}
+    for s in services:
+        handlers = _make_handlers(
+            store, s, id_field=id_field, context_provider=context_provider, permission_error=permission_error, pb=pb
+        )
+        for rpc, behavior in handlers.items():
+            behavior.rpc = rpc
+            routes[f"/{PACKAGE}.{s['svc']}/{rpc}"] = behavior
+
+    from concurrent import futures
+
+    server = grpc.server(futures.ThreadPoolExecutor(max_workers=8), options=None)
+    server.add_generic_rpc_handlers([_Router(pb, routes, grpc.unary_unary_rpc_method_handler)])
+
+    if port is None:
+        return GrpcServer(server, pb, proto_text, None)
+
+    bound = server.add_insecure_port(f"{host}:{port}")
+    if bound == 0:
+        raise RuntimeError(f"grpc server 绑定端口失败: {host}:{port}")
+    server.start()
+    return GrpcServer(server, pb, proto_text, bound)

store_grpc_py-0.1.0/src/store_grpc_py.egg-info/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: store-grpc-py
+Version: 0.1.0
+Summary: gRPC adapter that auto-generates a .proto service per schema for py-store (schema-driven CRUD over GQL, proto-first with runtime compilation, zero manual protoc)
+License: MIT
+Keywords: py-store,storepy,grpc,protobuf,crud,gql
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: grpc
+Requires-Dist: grpcio>=1.60; extra == "grpc"
+Requires-Dist: grpcio-tools>=1.60; extra == "grpc"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: grpcio>=1.60; extra == "dev"
+Requires-Dist: grpcio-tools>=1.60; extra == "dev"
+
+# store-grpc-py
+
+py-store 的 gRPC 皮肤（`store-grpc-py`，PyPI）。规范与用法见仓库根 README 与 `../spec/`。

store_grpc_py-0.1.0/src/store_grpc_py.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/store_grpc/__init__.py
+src/store_grpc/errors.py
+src/store_grpc/proto.py
+src/store_grpc/server.py
+src/store_grpc_py.egg-info/PKG-INFO
+src/store_grpc_py.egg-info/SOURCES.txt
+src/store_grpc_py.egg-info/dependency_links.txt
+src/store_grpc_py.egg-info/requires.txt
+src/store_grpc_py.egg-info/top_level.txt
+tests/test_conformance.py
+tests/test_smoke.py

store_grpc_py-0.1.0/src/store_grpc_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

store_grpc_py-0.1.0/src/store_grpc_py.egg-info/requires.txt

@@ -0,0 +1,9 @@
+
+[dev]
+pytest>=8
+grpcio>=1.60
+grpcio-tools>=1.60
+
+[grpc]
+grpcio>=1.60
+grpcio-tools>=1.60

store_grpc_py-0.1.0/src/store_grpc_py.egg-info/top_level.txt

@@ -0,0 +1 @@
+store_grpc

store_grpc_py-0.1.0/tests/test_conformance.py

@@ -0,0 +1,156 @@
+"""conformance runner — 读取共享用例 JSON（../../conformance/cases/*.json）逐项执行，
+与 node 端 runner 断言同一份文件（spec 唯一事实源）。
+"""
+
+import json
+import os
+import re
+
+import pytest
+
+grpc = pytest.importorskip("grpc")
+pytest.importorskip("grpc_tools")
+
+from store_grpc import create_server  # noqa: E402
+
+CASES_DIR = os.path.join(os.path.dirname(__file__), "..", "..", "conformance", "cases")
+
+STATUS_BY_NAME = {
+    "INVALID_ARGUMENT": grpc.StatusCode.INVALID_ARGUMENT,
+    "UNAUTHENTICATED": grpc.StatusCode.UNAUTHENTICATED,
+    "PERMISSION_DENIED": grpc.StatusCode.PERMISSION_DENIED,
+    "NOT_FOUND": grpc.StatusCode.NOT_FOUND,
+    "INTERNAL": grpc.StatusCode.INTERNAL,
+}
+
+REQ_FIELD_BY_RPC = {
+    "List": "ListRequest",
+    "Get": "GetRequest",
+    "Create": "CreateRequest",
+    "Update": "UpdateRequest",
+    "Delete": "DeleteRequest",
+}
+
+
+class PermissionErrorMock(Exception):
+    pass
+
+
+def make_mock_store(defn):
+    rows = []
+
+    def guard_gql(gql):
+        # 模拟 core 的 ERR_GQL_PARSE: 前缀契约：括号不配平即解析失败
+        if gql.count("(") != gql.count(")"):
+            raise ValueError("ERR_GQL_PARSE:括号不配平")
+
+    class Store:
+        PermissionError = PermissionErrorMock
+        list = staticmethod(lambda: [defn["name"]])
+        get = staticmethod(lambda name: defn)
+
+        @staticmethod
+        def query(gql, params=None):
+            guard_gql(gql)
+            cond = (params or {}).get("c0")
+            return [r for r in rows if not cond or all(r.get(k) == v for k, v in cond.items())]
+
+        @staticmethod
+        def query_one(gql, params=None):
+            guard_gql(gql)
+            cond = (params or {}).get("c0")
+            return next((r for r in rows if all(r.get(k) == v for k, v in cond.items())), None)
+
+        @staticmethod
+        def insert(name, data):
+            doc = {"_id": f"u{len(rows) + 1}", **data}
+            rows.append(doc)
+            return doc
+
+        @staticmethod
+        def update(name, cond, data):
+            row = next(r for r in rows if all(r.get(k) == v for k, v in cond.items()))
+            row.update(data)
+            return row
+
+        @staticmethod
+        def remove(name, cond):
+            for i, r in enumerate(rows):
+                if all(r.get(k) == v for k, v in cond.items()):
+                    rows.pop(i)
+                    return 1
+            return 0
+
+        @staticmethod
+        def set_context(ctx):
+            pass
+
+    return Store()
+
+
+def encode_request(pb, svc, step_request):
+    """conformance 通用形状 → py 侧 snake_case 字段；字符串值原样传递（预编码/非法样本），对象才 dumps。"""
+    verb = re.match(r"^(List|Get|Create|Update|Delete)", step_request.get("rpc", "List")).group(1)
+    req_cls = getattr(pb, REQ_FIELD_BY_RPC[verb])
+    kwargs = {}
+    if step_request.get("q") is not None:
+        kwargs["q"] = step_request["q"]
+    if step_request.get("id") is not None:
+        kwargs["id"] = step_request["id"]
+    if step_request.get("params") is not None:
+        p = step_request["params"]
+        kwargs["params_json"] = p if isinstance(p, str) else json.dumps(p)
+    if step_request.get("body") is not None:
+        kwargs["body_json"] = json.dumps(step_request["body"])
+    if step_request.get("set") is not None:
+        kwargs["set_json"] = json.dumps(step_request["set"])
+    return req_cls(**kwargs)
+
+
+@pytest.mark.parametrize("file", [f for f in os.listdir(CASES_DIR) if f.endswith(".json")])
+def test_conformance(file):
+    with open(os.path.join(CASES_DIR, file), encoding="utf-8") as f:
+        spec = json.load(f)
+    svc = spec["service"]
+    defn = {"name": svc, "fields": {"_id": {"type": "string"}, "name": {"type": "string"}, "age": {"type": "int"}}}
+    store = make_mock_store(defn)
+    server = create_server(store, port=0)
+    try:
+        pb = server.pb
+        channel = grpc.insecure_channel(f"127.0.0.1:{server.port}")
+        try:
+            created_id = None
+            for i, step in enumerate(spec["steps"]):
+                request = encode_request(pb, svc, {"rpc": step["rpc"], **(step.get("request") or {})})
+                if step.get("useCreatedId") and getattr(request, "id", "") == "":
+                    request.id = created_id
+                unary = channel.unary_unary(
+                    f"/store.v0.{svc}/{step['rpc']}",
+                    request_serializer=type(request).SerializeToString,
+                    response_deserializer=pb.StoreReply.FromString,
+                )
+                try:
+                    reply = unary(request, timeout=10)
+                    error = None
+                except grpc.RpcError as e:
+                    reply = None
+                    error = e
+
+                expect = step["expect"]
+                if expect.get("ok"):
+                    assert error is None, f"step#{i} {step['rpc']} 应成功: {error and error.details}"
+                    data = json.loads(reply.data_json)
+                    if "dataKeys" in expect:
+                        assert sorted(k for k in data if k in expect["dataKeys"]) == sorted(expect["dataKeys"])
+                    if "listLength" in expect:
+                        assert len(data) == expect["listLength"]
+                    if i == 0:
+                        created_id = data["_id"]
+                else:
+                    assert error is not None, f"step#{i} {step['rpc']} 应失败"
+                    assert error.code() == STATUS_BY_NAME[expect["statusCode"]], f"step#{i} status"
+                    assert dict(error.trailing_metadata())["store-error-code"] == expect["errorCode"], f"step#{i} code"
+        finally:
+            channel.close()
+    finally:
+        server.stop(None)

store_grpc_py-0.1.0/tests/test_smoke.py

@@ -0,0 +1,354 @@
+"""冒烟测试 — mock store + 真实 grpcio server（本地随机端口，不连真实库）。
+
+用例语义与 node 端 smoke / ../../conformance/cases/users-crud.json 对齐（spec 唯一事实源）。
+"""
+
+import json
+import re
+
+import pytest
+
+grpc = pytest.importorskip("grpc")
+pytest.importorskip("grpc_tools")
+
+from store_grpc import build_proto, create_server, export_proto, filter_archived, service_name  # noqa: E402
+
+DEFN = {
+    "name": "User",
+    "description": "用户表：平台账号主档",
+    "fields": {
+        "_id": {"type": "string", "description": "主键，u 前缀"},
+        "name": {"type": "string"},
+        "age": {"type": "int"},
+        "profile": {"type": "object", "description": "个人资料", "fields": {"bio": {"type": "string"}}},
+    },
+}
+
+STATUS = grpc.StatusCode
+REQ_CLASS_BY_RPC = {
+    "List": "ListRequest",
+    "Get": "GetRequest",
+    "Create": "CreateRequest",
+    "Update": "UpdateRequest",
+    "Delete": "DeleteRequest",
+}
+
+
+class PermissionErrorMock(Exception):
+    """实例 name 显式化（真实 store 权限类有稳定码/name；Python 类名即 __name__）。"""
+
+
+def make_mock_store():
+    rows = []
+    state = {"last_ctx": "initial-not-cleaned"}
+
+    def guard_gql(gql):
+        # 模拟 core 的 ERR_GQL_PARSE: 前缀契约：括号不配平即解析失败（conformance GQL_PARSE 用例依赖）
+        if gql.count("(") != gql.count(")"):
+            raise ValueError("ERR_GQL_PARSE:括号不配平")
+
+    class Store:
+        PermissionError = PermissionErrorMock
+        list = staticmethod(lambda: ["User"])
+        get = staticmethod(lambda name: DEFN)
+
+        @staticmethod
+        async def query(gql, params=None):
+            guard_gql(gql)
+            cond = (params or {}).get("c0")
+            return [r for r in rows if not cond or all(r.get(k) == v for k, v in cond.items())]
+
+        @staticmethod
+        async def query_one(gql, params=None):
+            guard_gql(gql)
+            cond = (params or {}).get("c0")
+            return next((r for r in rows if all(r.get(k) == v for k, v in cond.items())), None)
+
+        @staticmethod
+        async def insert(name, data):
+            doc = {"_id": f"u{len(rows) + 1}", **data}
+            rows.append(doc)
+            return doc
+
+        @staticmethod
+        async def update(name, cond, data):
+            row = next(r for r in rows if all(r.get(k) == v for k, v in cond.items()))
+            row.update(data)
+            return row
+
+        @staticmethod
+        async def remove(name, cond):
+            for i, r in enumerate(rows):
+                if all(r.get(k) == v for k, v in cond.items()):
+                    rows.pop(i)
+                    return 1
+            return 0
+
+        @staticmethod
+        async def set_context(ctx):
+            state["last_ctx"] = ctx
+
+    return Store(), rows, state
+
+
+def err_details(e):
+    """grpcio 错误 details：活跃错误为属性、_InactiveRpcError 为方法，统一取值。"""
+    d = e.details
+    return d() if callable(d) else d
+
+
+def make_client(h, svc="User", readonly=False):
+    """用 server 暴露的 proto 文本编译产物构造 client（与生产客户端同路径）。"""
+    pb = h.pb
+    verbs = ["List", "Get"] if readonly else ["List", "Get", "Create", "Update", "Delete"]
+
+    def call(rpc, request):
+        verb = re.match(r"^(List|Get|Create|Update|Delete)", rpc).group(1)
+        req_cls = getattr(pb, REQ_CLASS_BY_RPC[verb])
+        reply_cls = pb.StoreReply
+        channel = grpc.insecure_channel(f"127.0.0.1:{h.port}")
+        try:
+            unary = channel.unary_unary(
+                f"/store.v0.{svc}/{rpc}",
+                request_serializer=req_cls.SerializeToString,
+                response_deserializer=reply_cls.FromString,
+            )
+            try:
+                return {"reply": unary(request, timeout=10)}
+            except grpc.RpcError as e:
+                return {"error": e}
+        finally:
+            channel.close()
+
+    return call
+
+
+@pytest.fixture()
+def h():
+    store, rows, state = make_mock_store()
+    server = create_server(store, port=0)
+    yield server, store, rows, state
+    server.stop(None)
+
+
+def test_filter_archived():
+    assert filter_archived(["User", "UserDeleted", "Log"]) == ["User", "Log"]
+
+
+def test_service_name():
+    assert service_name("user") == "User"
+    assert service_name("User") == "User"
+
+
+def test_build_proto():
+    store, _, _ = make_mock_store()
+    proto = build_proto(store)
+    assert 'syntax = "proto3";' in proto
+    assert "package store.v0;" in proto
+    assert "service User {" in proto
+    assert "rpc ListUser (ListRequest) returns (StoreReply);" in proto
+    assert "rpc GetUser (GetRequest) returns (StoreReply);" in proto
+    assert "rpc CreateUser (CreateRequest) returns (StoreReply);" in proto
+    assert "rpc UpdateUser (UpdateRequest) returns (StoreReply);" in proto
+    assert "rpc DeleteUser (DeleteRequest) returns (StoreReply);" in proto
+    assert "// 用户表：平台账号主档" in proto  # description 透传（spec/01）
+    assert export_proto(store) == proto  # export_proto ≡ build_proto（spec/01）
+
+
+def test_build_proto_notes_and_conflict():
+    store, _, _ = make_mock_store()
+    store.list = lambda: ["User", "SecretLog", "AuditEvent"]
+    store.get = lambda n: (
+        DEFN
+        if n == "User"
+        else {**DEFN, "name": "SecretLog", "x-grpc": {"hidden": True}}
+        if n == "SecretLog"
+        else {**DEFN, "name": "AuditEvent", "x-grpc": {"readonly": True}}
+    )
+    proto = build_proto(store)
+    assert "SecretLog" not in proto
+    assert "service AuditEvent {" in proto
+    assert "rpc ListAuditEvent" in proto
+    assert "rpc CreateAuditEvent" not in proto  # readonly → 只出查询两段
+
+    store.list = lambda: ["user", "User"]
+    with pytest.raises(ValueError, match="ERR_NAME_CONFLICT"):
+        build_proto(store)
+
+
+def test_five_rpc_full_chain(h):
+    server, store, rows, _ = h
+    call = make_client(server)
+    pb = server.pb
+
+    # CreateUser
+    r = call("CreateUser", pb.CreateRequest(body_json=json.dumps({"name": "alice", "age": 30})))
+    assert r["reply"].data_json == '{"_id": "u1", "name": "alice", "age": 30}'
+
+    # ListUser（q 透传 + params_json）
+    r = call(
+        "ListUser",
+        pb.ListRequest(q="($condition: @c0) { name, age }", params_json=json.dumps({"c0": {"age": 30}})),
+    )
+    assert json.loads(r["reply"].data_json)[0]["name"] == "alice"
+
+    # ListUser（q 缺省 → schema 投影拼接；投影串由适配层拼进 GQL）
+    r = call("ListUser", pb.ListRequest())
+    assert r["reply"].data_json  # 成功即可，投影语义由 smoke 的 gqlLog 用例覆盖
+
+    # GetUser
+    r = call("GetUser", pb.GetRequest(id="u1"))
+    assert json.loads(r["reply"].data_json) == {"_id": "u1", "name": "alice", "age": 30}
+
+    # UpdateUser（返回 store.update 原始结果，不做二次回读——spec/02 对齐 REST）
+    r = call("UpdateUser", pb.UpdateRequest(id="u1", set_json=json.dumps({"age": 31})))
+    assert json.loads(r["reply"].data_json) == {"_id": "u1", "name": "alice", "age": 31}
+
+    # DeleteUser
+    r = call("DeleteUser", pb.DeleteRequest(id="u1"))
+    assert json.loads(r["reply"].data_json) == 1
+
+    # 删除后 GetUser ⇒ NOT_FOUND + trailer store-error-code（spec/03）
+    r = call("GetUser", pb.GetRequest(id="u1"))
+    err = r["error"]
+    assert err.code() == STATUS.NOT_FOUND
+    assert err_details(err) == "记录不存在: _id=u1"
+    assert dict(err.trailing_metadata())["store-error-code"] == "NOT_FOUND"
+
+
+def test_error_mapping(h):
+    server, store, _, _ = h
+    call = make_client(server)
+    pb = server.pb
+
+    # body_json 数组 / 非法 JSON ⇒ INVALID_ARGUMENT + INVALID_BODY
+    assert call("CreateUser", pb.CreateRequest(body_json="[1,2]"))["error"].code() == STATUS.INVALID_ARGUMENT
+    r = call("CreateUser", pb.CreateRequest(body_json="{oops"))
+    assert dict(r["error"].trailing_metadata())["store-error-code"] == "INVALID_BODY"
+
+    # params_json 非法 JSON ⇒ INVALID_PARAM
+    r = call("ListUser", pb.ListRequest(params_json="not-json"))
+    assert r["error"].code() == STATUS.INVALID_ARGUMENT
+    assert dict(r["error"].trailing_metadata())["store-error-code"] == "INVALID_PARAM"
+
+    # core GQL 解析失败（ERR_GQL_PARSE: 前缀）⇒ GQL_PARSE，details 剥前缀
+    r = call("ListUser", pb.ListRequest(q="($bogus"))
+    assert dict(r["error"].trailing_metadata())["store-error-code"] == "GQL_PARSE"
+    assert err_details(r["error"]) == "括号不配平"
+
+    # ERR_PERMISSION: 前缀 ⇒ PERMISSION_DENIED
+    orig_query = store.query
+
+    def deny(gql, params=None):
+        raise ValueError("ERR_PERMISSION:无访问权限")
+
+    store.query = deny
+    r = call("ListUser", pb.ListRequest())
+    assert r["error"].code() == STATUS.PERMISSION_DENIED
+    assert dict(r["error"].trailing_metadata())["store-error-code"] == "ERR_PERMISSION"
+
+    # PermissionError 类（store.PermissionError 来源）⇒ PERMISSION_DENIED，码取 store_code
+
+    def deny_class(gql, params=None):
+        raise PermissionErrorMock("RBAC 拒绝")
+
+    store.query = deny_class
+    r = call("ListUser", pb.ListRequest())
+    assert r["error"].code() == STATUS.PERMISSION_DENIED
+    assert dict(r["error"].trailing_metadata())["store-error-code"] == "PermissionErrorMock"
+
+    # 其余 store 错误 ⇒ INTERNAL，message 原样透传（禁掩盖）
+
+    def boom(gql, params=None):
+        raise RuntimeError("数据库连接失败")
+
+    store.query = boom
+    r = call("ListUser", pb.ListRequest())
+    assert r["error"].code() == STATUS.INTERNAL
+    assert err_details(r["error"]) == "数据库连接失败"
+    assert dict(r["error"].trailing_metadata())["store-error-code"] == "RuntimeError"
+
+
+def test_context_provider(h):
+    server, store, _, state = h
+    call = make_client(server)
+    pb = server.pb
+
+    def provider(metadata):
+        user = metadata.get("x-user")
+        if user == "bad":
+            raise ValueError("ERR_PERMISSION:无访问权限")
+        if user == "broken":
+            raise ValueError("上下文钩子故障")
+        if user == "anon":
+            return None  # 显式空上下文
+        return {"user": user}
+
+    # 重新起一个带 provider 的 server
+    server.stop(None)
+    store2, rows2, state2 = make_mock_store()
+    server2 = create_server(store2, port=0, context_provider=provider)
+    try:
+        call2 = make_client(server2)
+        chan = grpc.insecure_channel(f"127.0.0.1:{server2.port}")
+        unary = chan.unary_unary(
+            "/store.v0.User/ListUser",
+            request_serializer=pb.ListRequest.SerializeToString,
+            response_deserializer=pb.StoreReply.FromString,
+        )
+
+        def raw(user):
+            md = (("x-user", user),)
+            try:
+                unary(pb.ListRequest(q=" { _id }"), metadata=md, timeout=10)
+                return None
+            except grpc.RpcError as e:
+                return e
+
+        # 注入：set_context 收到 provider 返回的对象
+        raw("alice")
+        assert state2["last_ctx"] == {"user": "alice"}
+
+        # ERR_PERMISSION: 前缀 ⇒ PERMISSION_DENIED
+        err = raw("bad")
+        assert err.code() == STATUS.PERMISSION_DENIED
+
+        # 非权限类 ⇒ UNAUTHENTICATED，message 原样透传
+        err = raw("broken")
+        assert err.code() == STATUS.UNAUTHENTICATED
+        assert err_details(err) == "上下文钩子故障"
+
+        # 返回 None ⇒ 显式 set_context(None)（清除语义落地，防上一请求上下文残留）
+        raw("anon")
+        assert state2["last_ctx"] is None
+        chan.close()
+    finally:
+        server2.stop(None)
+
+
+def test_readonly_model():
+    store, _, _ = make_mock_store()
+    store.list = lambda: ["AuditEvent"]
+    store.get = lambda n: {**DEFN, "name": n, "x-grpc": {"readonly": True}}
+    server = create_server(store, port=0)
+    try:
+        call = make_client(server, svc="AuditEvent", readonly=True)
+        pb = server.pb
+        assert json.loads(call("ListAuditEvent", pb.ListRequest())["reply"].data_json) == []
+        assert call("GetAuditEvent", pb.GetRequest(id="x"))["error"].code() == STATUS.NOT_FOUND
+    finally:
+        server.stop(None)
+
+
+def test_proto_roundtrip():
+    store, _, _ = make_mock_store()
+    proto = export_proto(store)
+    from grpc_tools import protoc
+    import os
+    import tempfile
+
+    tmp = tempfile.mkdtemp()
+    f = os.path.join(tmp, "store_grpc.proto")
+    with open(f, "w", encoding="utf-8") as fh:
+        fh.write(proto)
+    assert protoc.main(["protoc", f"-I{tmp}", f"--python_out={tmp}", f]) == 0  # 可再编译 = 合法 IDL