store-api-py 0.1.0__py3-none-any.whl

store_api_py/__init__.py

@@ -0,0 +1,10 @@
+"""store-api-py — 为 py-store schema 自动生成 RESTful API 的 FastAPI 适配器。
+
+    from store_api_py import create_app
+    app = create_app(store, prefix='/api')  # uvicorn main:app
+"""
+
+from .app import create_app, filter_archived
+from .params import ParamError, convert_value, parse_query_params
+
+__all__ = ["create_app", "filter_archived", "parse_query_params", "convert_value", "ParamError"]

store_api_py/app.py

@@ -0,0 +1,200 @@
+"""store-api-py — FastAPI 适配器：为已注册 schema 自动生成 RESTful 路由。
+
+路由/参数/错误/上下文语义全部以 spec/*.md 为唯一依据（双端 parity，改动先改 spec）。
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import json
+from typing import Any, Callable
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from .errors import (
+    StoreApiError,
+    context_error,
+    error_payload,
+    invalid_body,
+    map_error,
+    not_found,
+)
+from .params import parse_query_params
+
+ARCHIVE_SUFFIX = "Deleted"
+
+ContextProvider = Callable[[Request], Any]
+
+
+def filter_archived(names: list[str]) -> list[str]:
+    """归档表过滤（spec/01-routing.md）：`XxxDeleted` 且 `Xxx` 也在列表中 ⇒ 视为归档表。"""
+    s = set(names)
+    return [n for n in names if not (n.endswith(ARCHIVE_SUFFIX) and n[: -len(ARCHIVE_SUFFIX)] in s)]
+
+
+async def _resolve_ctx(provider: ContextProvider, request: Request) -> Any:
+    ctx = provider(request)
+    if inspect.isawaitable(ctx):
+        ctx = await ctx
+    return ctx
+
+
+def create_app(
+    store: Any,
+    *,
+    prefix: str = "",
+    id_field: str = "_id",
+    context_provider: ContextProvider | None = None,
+    resources: list[str] | None = None,
+    permission_error: type[BaseException] | None = None,
+) -> FastAPI:
+    """为 store（py-store 的 store 实例，需已 init + register）生成 RESTful FastAPI 应用。
+
+    - prefix: 路由前缀，如 '/api'
+    - id_field: 单条路由主键字段名（双端一致，spec/01-routing.md，默认 '_id'）
+    - context_provider: 每请求上下文钩子（spec/04-context.md）；非权限类抛错 ⇒ 401 CONTEXT_ERROR
+    - resources: 显式资源名；缺省取 store.list() 并过滤归档表
+    - permission_error: store 权限错误类；缺省取 store.PermissionError
+    """
+    app = FastAPI(title="store-api")
+    if permission_error is None:
+        permission_error = getattr(store, "PermissionError", None)
+
+    def _respond(mapped: StoreApiError) -> JSONResponse:
+        return JSONResponse(status_code=mapped.status_code, content=error_payload(mapped.code, mapped.message))
+
+    if context_provider is not None:
+
+        @app.middleware("http")
+        async def _inject_context(request: Request, call_next):
+            try:
+                ctx = await _resolve_ctx(context_provider, request)
+            except Exception as e:  # noqa: BLE001 — spec/04-context.md：PermissionError ⇒ 403（RBAC 拒绝）；其余 ⇒ 401，message 原样透传
+                if permission_error is not None and isinstance(e, permission_error):
+                    return _respond(map_error(e, permission_error))
+                return _respond(context_error(str(e) or None))
+            # spec/04：返回 None 时同样显式注入空上下文（store.set_context(None) 语义为清除，
+            # 有状态持有的运行时禁止残留上一请求上下文，防身份跨请求泄漏）
+            store.set_context(ctx)
+            return await call_next(request)
+
+    # B6：`x-cache` 响应头注记位——取值唯一来源为宿主 store.cache_status（未实现时恒 BYPASS）；
+    # 覆盖所有响应（含错误响应）。非法值回落 BYPASS（宿主侧已对非法/异常走反馈通道留痕）。
+    _CACHE_VALUES = ("HIT", "MISS", "BYPASS")
+
+    @app.middleware("http")
+    async def _annotate_cache(request: Request, call_next):
+        response = await call_next(request)
+        fn = getattr(store, "cache_status", None)
+        v = fn() if callable(fn) else "BYPASS"
+        response.headers["x-cache"] = v if v in _CACHE_VALUES else "BYPASS"
+        return response
+
+    names = resources if resources is not None else filter_archived(store.list())
+    for name in names:
+        # 显式投影（spec/01+02）：GQL 省略投影段 = 只返回 _id（三端 core 契约）。
+        # 列表路由仅在 q 缺失时用它；q 存在时投影完全由 q 决定，适配层不追加。
+        proj = _schema_projection(store, name)
+        _register_resource(app, store, name, prefix, id_field, permission_error, proj)
+
+    return app
+
+
+def _schema_projection(store: Any, name: str) -> str:
+    """从 store 元数据生成显式投影串（' { f1, f2 }'）。
+    取值顺序：store.get(name)（nodejs 形态）→ py_store.schema 模块（py-store 未在 Store 类暴露 get）。
+    两者皆不可得 / fields 为空 → 空串（无投影，data 仅 _id——上游 schema 定义不完整的显式后果）。"""
+    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")
+        else:
+            fields = getattr(meta, "fields", None)
+    if fields is None:
+        try:
+            from py_store import schema as py_schema
+
+            fields = (py_schema.get(name) or {}).get("fields")
+        except Exception:
+            fields = None
+    keys = list((fields or {}).keys())
+    return f" {{ {', '.join(keys)} }}" if keys else ""
+
+
+def _guard(permission_error: type[BaseException] | None) -> Callable:
+    """单一错误出口：handler 抛出的所有错误统一走 map_error 判定（禁 catch 后洗成成功）。"""
+
+    def deco(fn: Callable) -> Callable:
+        @functools.wraps(fn)  # 保留原签名，FastAPI 靠 inspect.signature 注入 Request/路径参数
+        async def wrapper(*args, **kwargs):
+            try:
+                return await fn(*args, **kwargs)
+            except Exception as e:  # noqa: BLE001 — 错误必须映射为带语义的 HTTP 响应，禁止静默
+                mapped = map_error(e, permission_error)
+                return JSONResponse(status_code=mapped.status_code, content=error_payload(mapped.code, mapped.message))
+
+        return wrapper
+
+    return deco
+
+
+def _register_resource(
+    app: FastAPI,
+    store: Any,
+    name: str,
+    prefix: str,
+    id_field: str,
+    permission_error: type[BaseException] | None,
+    proj: str,
+) -> None:
+    # 工厂函数隔离闭包：handler 签名只含 Request 与路径参数，
+    # 否则 FastAPI 会把捕获变量解析成查询参数（缺参即 422）
+    base = f"{prefix}/{name}"
+
+    @app.get(base)
+    @_guard(permission_error)
+    async def list_resource(request: Request):
+        params = parse_query_params(request.query_params)
+        # q 缺失 → 全字段投影（spec/02）；q 存在 → 投影完全由 q 决定
+        gql = name + (request.query_params.get("q") or proj)
+        return {"data": await store.query(gql, params)}
+
+    @app.get(base + "/{rid}")
+    @_guard(permission_error)
+    async def get_one(rid: str):
+        data = await store.query_one(f"{name}($condition: @c0){proj}", {"c0": {id_field: rid}})
+        if data is None:
+            raise not_found(f"记录不存在: {id_field}={rid}")
+        return {"data": data}
+
+    @app.post(base, status_code=201)
+    @_guard(permission_error)
+    async def create_resource(request: Request):
+        return {"data": await store.insert(name, await _read_json_body(request))}
+
+    @app.patch(base + "/{rid}")
+    @_guard(permission_error)
+    async def update_one(rid: str, request: Request):
+        return {"data": await store.update(name, {id_field: rid}, await _read_json_body(request))}
+
+    @app.delete(base + "/{rid}")
+    @_guard(permission_error)
+    async def delete_one(rid: str):
+        return {"data": await store.remove(name, {id_field: rid})}
+
+
+async def _read_json_body(request: Request) -> dict:
+    try:
+        body = await request.json()
+    except json.JSONDecodeError as e:
+        raise invalid_body(f"请求体不是合法 JSON: {e}") from e
+    if not isinstance(body, dict):
+        raise invalid_body("请求体必须是 JSON 对象")
+    return body

store_api_py/errors.py

@@ -0,0 +1,62 @@
+"""错误 → HTTP 状态码映射。
+
+规范依据：spec/03-errors.md（判定顺序双端一致，改动必须先改 spec）。
+遵循 no-error-masking：message 原样透传、取不到置 None（禁伪造），成功响应不得带 error 字段。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .params import ParamError
+
+
+class StoreApiError(Exception):
+    """适配层自身守卫错误（400/401/404），message 为确定性描述。"""
+
+    def __init__(self, status_code: int, code: str, message: str | None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+
+
+def error_payload(code: str, message: str | None) -> dict[str, Any]:
+    return {"error": {"code": code, "message": message}}
+
+
+def store_code(err: BaseException) -> str:
+    """store 错误的分类码：优先 err.code，缺省用错误类名，再缺省用通用码。"""
+    return getattr(err, "code", None) or type(err).__name__ or "STORE_ERROR"
+
+
+def invalid_body(message: str) -> StoreApiError:
+    return StoreApiError(400, "INVALID_BODY", message)
+
+
+def not_found(message: str) -> StoreApiError:
+    return StoreApiError(404, "NOT_FOUND", message)
+
+
+def context_error(message: str | None) -> StoreApiError:
+    return StoreApiError(401, "CONTEXT_ERROR", message)
+
+
+def map_error(err: BaseException, permission_error: type[BaseException] | None) -> StoreApiError:
+    """判定顺序（spec/03-errors.md）：
+    适配层守卫(400) → PermissionError(403) → queryOne 空结果(404) → 其余 500 透传
+    """
+    if isinstance(err, StoreApiError):
+        return err
+    if isinstance(err, ParamError):
+        return StoreApiError(400, "INVALID_PARAM", str(err) or None)
+    if permission_error is not None and isinstance(err, permission_error):
+        # 按类型判定，禁按 message 匹配
+        return StoreApiError(403, store_code(err), str(err) or None)
+    # spec/03 判定顺序第 3 层：GQL 解析失败（core 稳定前缀 ERR_GQL_PARSE:，与
+    # ERR_PERM_PREFIX 同构的类型级契约——前缀判定非文案脆弱匹配）→ 400 GQL_PARSE，
+    # message 剥前缀取原文（与 go/rust/node 同语义）。
+    text = str(err)
+    if text.startswith("ERR_GQL_PARSE:"):
+        return StoreApiError(400, "GQL_PARSE", text[len("ERR_GQL_PARSE:"):])
+    return StoreApiError(500, store_code(err), text or None)

store_api_py/params.py

@@ -0,0 +1,50 @@
+"""查询参数 → GQL params 绑定。
+
+规范依据：spec/02-params.md（双端逐字一致，改动必须先改 spec）。
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+_INT_RE = re.compile(r"^-?\d+$")
+_FLOAT_RE = re.compile(r"^-?\d+\.\d+$")
+
+
+class ParamError(Exception):
+    code = "INVALID_PARAM"
+
+
+def convert_value(raw: str) -> Any:
+    """p.<name> 值的类型转换：true/false/null → 字面量；整数/浮点正则全匹配 → 数值；
+    ``{``/``[`` 开头 → JSON 解析（失败抛 ParamError，禁静默当字符串）；其余 → 字符串原样。
+    """
+    if raw == "true":
+        return True
+    if raw == "false":
+        return False
+    if raw == "null":
+        return None
+    if _INT_RE.match(raw):
+        return int(raw)
+    if _FLOAT_RE.match(raw):
+        return float(raw)
+    if raw.startswith("{") or raw.startswith("["):
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise ParamError(f"参数 JSON 解析失败: {e}") from e
+    return raw
+
+
+def parse_query_params(query_params) -> dict[str, Any]:
+    """从 QueryParams 收集 p.* 参数。同名重复出现 → 列表（每元素各自转换）；单次 → 标量。"""
+    params: dict[str, Any] = {}
+    for key in query_params.keys():
+        if not key.startswith("p."):
+            continue
+        converted = [convert_value(v) for v in query_params.getlist(key)]
+        params[key[2:]] = converted if len(converted) > 1 else converted[0]
+    return params

store_api_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: store-api-py
+Version: 0.1.0
+Summary: FastAPI adapter that auto-generates RESTful APIs for py-store schemas (schema-driven CRUD over GQL)
+License: MIT
+Keywords: py-store,storepy,fastapi,rest,crud,gql
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: uvicorn>=0.29; extra == "dev"
+
+# store-api-py
+
+FastAPI adapter that auto-generates RESTful APIs for py-store schemas (schema-driven CRUD over GQL).
+
+Full documentation: https://github.com/coenddt/store-api

store_api_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+store_api_py/__init__.py,sha256=Cjzla907vQPX8Mf-2m8NJTdE9BIXfBUWIqztABj4eQI,408
+store_api_py/app.py,sha256=prXtQdwoJN3GpKqJXKKGVyFGAHnHGgIVnTU0ZUqfj74,7935
+store_api_py/errors.py,sha256=WkTkoseeNcGd5IWVhKSq9bR6lsQlePnYBrhupEIIPsM,2433
+store_api_py/params.py,sha256=FyHZByR6hoSxPdKGGsWlMsFNSUqpxOYQAnVbvTkXsZM,1563
+store_api_py-0.1.0.dist-info/METADATA,sha256=woZFQmbSFZYifiFpatCzlcyIdGqkPKH4YqGSohDO4LQ,646
+store_api_py-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+store_api_py-0.1.0.dist-info/top_level.txt,sha256=E-5s238JcynR2nQSRrep1Urv2EIWu4NCypieB8d704E,13
+store_api_py-0.1.0.dist-info/RECORD,,

store_api_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

store_api_py-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+store_api_py