store-graphql-py 0.1.0__tar.gz

store_graphql_py-0.1.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: store-graphql-py
+Version: 0.1.0
+Summary: GraphQL adapter that auto-generates standard GraphQL APIs for py-store schemas (schema-driven CRUD over GQL, projection pushdown)
+License: MIT
+Keywords: py-store,storepy,graphql,crud,gql
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: graphql-core>=3.2
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: fastapi>=0.110; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+
+# store-graphql-py
+
+GraphQL adapter that auto-generates standard GraphQL APIs for **py-store** schemas (schema-driven CRUD over GQL, projection pushdown).
+
+```python
+from store_graphql import build_graphql_schema, create_app, export_sdl
+
+schema = build_graphql_schema(store)      # 反射 py-store 已注册的 JSON schema
+app = create_app(store, schema=schema)    # FastAPI 承载（可选依赖）；或 graphql(schema, query) 自行执行
+export_sdl(schema)                        # SDL 导出，喂客户端 codegen
+```
+
+完整文档（双语主文档 / spec / conformance）：见仓库根 [README.zh-CN.md](https://github.com/coenddt/store-graphql#readme)。

store_graphql_py-0.1.0/README.md

@@ -0,0 +1,13 @@
+# store-graphql-py
+
+GraphQL adapter that auto-generates standard GraphQL APIs for **py-store** schemas (schema-driven CRUD over GQL, projection pushdown).
+
+```python
+from store_graphql import build_graphql_schema, create_app, export_sdl
+
+schema = build_graphql_schema(store)      # 反射 py-store 已注册的 JSON schema
+app = create_app(store, schema=schema)    # FastAPI 承载（可选依赖）；或 graphql(schema, query) 自行执行
+export_sdl(schema)                        # SDL 导出，喂客户端 codegen
+```
+
+完整文档（双语主文档 / spec / conformance）：见仓库根 [README.zh-CN.md](https://github.com/coenddt/store-graphql#readme)。

store_graphql_py-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "store-graphql-py"
+version = "0.1.0"
+description = "GraphQL adapter that auto-generates standard GraphQL APIs for py-store schemas (schema-driven CRUD over GQL, projection pushdown)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["py-store", "storepy", "graphql", "crud", "gql"]
+dependencies = ["graphql-core>=3.2"]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.110"]
+dev = ["pytest>=8", "fastapi>=0.110", "httpx>=0.27"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

store_graphql_py-0.1.0/setup.cfg

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

store_graphql_py-0.1.0/src/store_graphql/__init__.py

@@ -0,0 +1,26 @@
+"""store-graphql-py — 为 py-store 已注册 schema 自动生成标准 GraphQL API。
+
+语义依据：../../spec/*.md（多端 parity，改动先改 spec）。
+设计哲学：GraphQL 只是 GQL 的又一层 HTTP 皮 —— 适配层零语义发明。
+
+分层：
+    build_graphql_schema(store, **opts) → 纯 graphql-core GraphQLSchema
+    create_app(store, **opts)           → FastAPI 应用（可选依赖 fastapi）
+    export_sdl(schema)                  → SDL 字符串（喂客户端 codegen）
+
+store 端口契约见 spec/00：list/get/query/insert/update/remove/set_context。
+"""
+
+from .adapter import (
+    build_graphql_schema,
+    create_app,
+    export_sdl,
+    filter_archived,
+)
+
+__all__ = [
+    "build_graphql_schema",
+    "create_app",
+    "export_sdl",
+    "filter_archived",
+]

store_graphql_py-0.1.0/src/store_graphql/adapter.py

@@ -0,0 +1,576 @@
+"""adapter — py 端核心实现（语义依据 ../../spec/*.md，与 node 端镜像）。"""
+
+import inspect
+import json
+
+from graphql import (
+    graphql,
+    parse,
+    GraphQLArgument,
+    GraphQLBoolean,
+    GraphQLField,
+    GraphQLFloat,
+    GraphQLID,
+    GraphQLInt,
+    GraphQLList,
+    GraphQLNonNull,
+    GraphQLObjectType,
+    GraphQLScalarType,
+    GraphQLSchema,
+    GraphQLString,
+    print_schema,
+)
+
+# GraphQL AST kind 字符串(graphql-core 3.x 的 node.kind 即字符串,无 Kind 常量类)
+K_FIELD = "field"
+K_INLINE_FRAGMENT = "inline_fragment"
+K_FRAGMENT_SPREAD = "fragment_spread"
+K_VARIABLE = "variable"
+K_BOOLEAN = "boolean"
+
+ARCHIVE_SUFFIX = "Deleted"
+
+# spec/02 limit 守卫常量:core 的行数封顶仅 text2query 档生效(standard 档原样返回),
+# 适配层守上界;调整先改 spec 再三端同步。
+LIST_LIMIT_DEFAULT = 50
+LIST_LIMIT_MAX = 1000
+
+# spec/04 查询深度守卫:深度 = 从 operation 顶层 selectionSet 起的最大字段嵌套层数,
+# FragmentSpread 按定义递归(visiting 防环);超限 HTTP 400 + ERR_DEPTH: 稳定前缀。
+MAX_QUERY_DEPTH = 10
+
+# spec/04 复杂度守卫:AST 字段节点总数(别名不单列——字段计数已覆盖别名堆叠)。
+MAX_QUERY_FIELDS = 300
+
+
+def query_field_count(document):
+    """字段计数 + introspection 使用检测(fragment 展开计入,防环;__typename 放行)。"""
+    fragments = {
+        d.name.value: d
+        for d in document.definitions
+        if d.kind == "fragment_definition"
+    }
+    out = {"fields": 0, "introspection_used": False}
+
+    def walk_sel_set(sel_set, visiting):
+        if sel_set is None:
+            return
+        for sel in sel_set.selections:
+            if sel.kind == K_FIELD:
+                out["fields"] += 1
+                name = sel.name.value
+                if not out["introspection_used"] and name in ("__schema", "__type"):
+                    out["introspection_used"] = True
+                walk_sel_set(sel.selection_set, visiting)
+            elif sel.kind == K_INLINE_FRAGMENT:
+                walk_sel_set(sel.selection_set, visiting)
+            elif sel.kind == K_FRAGMENT_SPREAD:
+                if sel.name.value in visiting:
+                    continue
+                frag = fragments.get(sel.name.value)
+                if frag:
+                    walk_sel_set(frag.selection_set, visiting | {sel.name.value})
+
+    for d in document.definitions:
+        if d.kind == "operation_definition":
+            walk_sel_set(d.selection_set, set())
+    return out
+
+
+def query_depth(document):
+    fragments = {
+        d.name.value: d
+        for d in document.definitions
+        if d.kind == "fragment_definition"
+    }
+
+    def depth_of_sel_set(sel_set, visiting):
+        if sel_set is None:
+            return 0
+        max_d = 0
+        for sel in sel_set.selections:
+            if sel.kind == K_FIELD:
+                d = 1 + depth_of_sel_set(sel.selection_set, visiting)
+            elif sel.kind == K_INLINE_FRAGMENT:
+                d = depth_of_sel_set(sel.selection_set, visiting)
+            elif sel.kind == K_FRAGMENT_SPREAD:
+                if sel.name.value in visiting:
+                    continue
+                frag = fragments.get(sel.name.value)
+                d = (
+                    depth_of_sel_set(frag.selection_set, visiting | {sel.name.value})
+                    if frag
+                    else 0
+                )
+            else:
+                d = 0
+            if d > max_d:
+                max_d = d
+        return max_d
+
+    max_d = 0
+    for d in document.definitions:
+        if d.kind == "operation_definition":
+            od = depth_of_sel_set(d.selection_set, set())
+            if od > max_d:
+                max_d = od
+    return max_d
+
+# spec/05：GraphiQL 文档页（CDN 版，GET /graphql 返回；POST 才执行查询）
+GRAPHIQL_HTML = """<!doctype html>
+<html lang="en">
+<head>
+  <title>store-graphql GraphiQL</title>
+  <link rel="stylesheet" href="https://unpkg.com/graphiql/graphiql.min.css" />
+  <style>body { margin: 0; } #graphiql { height: 100vh; }</style>
+</head>
+<body>
+  <div id="graphiql">Loading GraphiQL...</div>
+  <script crossorigin src="https://unpkg.com/react/umd/react.production.min.js"></script>
+  <script crossorigin src="https://unpkg.com/react-dom/umd/react-dom.production.min.js"></script>
+  <script crossorigin src="https://unpkg.com/graphiql/graphiql.min.js"></script>
+  <script>
+    function graphQLFetcher(graphQLParams) {
+      return fetch('/graphql', {
+        method: 'post',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(graphQLParams),
+      }).then(function (r) { return r.json(); });
+    }
+    ReactDOM.createRoot(document.getElementById('graphiql')).render(
+      React.createElement(GraphiQL, { fetcher: graphQLFetcher })
+    );
+  </script>
+</body>
+</html>
+"""
+
+# ── spec/01：归档表过滤（与 store-api 三端逐字一致）──
+
+
+def filter_archived(names):
+    s = set(names)
+    return [
+        n
+        for n in names
+        if not (n.endswith(ARCHIVE_SUFFIX) and n[: -len(ARCHIVE_SUFFIX)] in s)
+    ]
+
+
+# ── spec/01：JSON 标量（只接受 variables 传入）──
+
+GraphQLJSON = GraphQLScalarType(
+    name="JSON",
+    description="任意 JSON 值（条件/排序/写入文档）。只接受 variables 形式（spec/02）。",
+    serialize=lambda v: v,
+    parse_value=lambda v: v,
+    parse_literal=lambda _node, *_a: (_ for _ in ()).throw(
+        ValueError("JSON 标量只接受 variables 传入（spec/02）")
+    ),
+)
+
+
+# ── spec/01：defn 字段类型 → GraphQL 输出类型 ──
+
+
+def _scalar_for(type_name):
+    return {
+        "string": GraphQLString,
+        "datetime": GraphQLString,
+        "int": GraphQLInt,
+        "float": GraphQLFloat,
+        "bool": GraphQLBoolean,
+    }.get(type_name)
+
+
+def _out_type(field_defn, type_name):
+    if field_defn.get("type") == "object" and "fields" in field_defn:
+        return GraphQLObjectType(
+            name=type_name,
+            description=field_defn.get("description"),  # spec/05：description 透传不改写
+            fields=lambda: _map_fields(field_defn["fields"], type_name),
+        )
+    return _scalar_for(field_defn.get("type")) or GraphQLJSON
+
+
+def _map_fields(fields, type_name):
+    return {
+        k: GraphQLField(
+            GraphQLNonNull(GraphQLID) if k == "_id" else _out_type(v, f"{type_name}_{k}"),
+            description=v.get("description"),  # spec/05：含 computes 与嵌套字段
+        )
+        for k, v in (fields or {}).items()
+    }
+
+
+def _model_fields(defn):
+    merged = dict(defn.get("fields") or {})
+    merged.update(defn.get("computes") or {})  # spec/01：computes 视同字段
+    return merged
+
+
+# ── spec/02：selection → GQL 投影串 ──
+
+
+def _should_include(node, variables):
+    for d in node.directives or ():
+        if d.name.value not in ("skip", "include"):
+            continue
+        if_arg = next((a for a in d.arguments or () if a.name.value == "if"), None)
+        if if_arg is None:
+            continue
+        if if_arg.value.kind == K_VARIABLE:
+            val = (variables or {}).get(if_arg.value.name.value)
+        elif if_arg.value.kind == K_BOOLEAN:
+            val = if_arg.value.value
+        else:
+            continue
+        if val is None:
+            continue
+        if d.name.value == "skip" and val:
+            return False
+        if d.name.value == "include" and not val:
+            return False
+    return True
+
+
+def projection_from_info(info):
+    root = next((n for n in info.field_nodes if n.kind == K_FIELD), None)
+    if root is None or root.selection_set is None:
+        return "_id"
+    variables = info.variable_values
+    if not isinstance(variables, dict):  # graphql-core 3.3 的 VariableValues 对象,强制值在 .coerced
+        variables = getattr(variables, "coerced", None) or {}
+
+    def walk(sel):
+        if sel.kind == K_FIELD:
+            if not _should_include(sel, variables):
+                return None
+            head = sel.name.value  # alias v0 忽略（spec/02）
+            if sel.selection_set:
+                inner = ", ".join(
+                    filter(None, (walk(s) for s in sel.selection_set.selections))
+                )
+                if inner:
+                    return f"{head} {{ {inner} }}"
+            return head
+        if sel.kind == K_INLINE_FRAGMENT:
+            return ", ".join(
+                filter(None, (walk(s) for s in sel.selection_set.selections))
+            )
+        if sel.kind == K_FRAGMENT_SPREAD:
+            frag = (info.fragments or {}).get(sel.name.value)
+            if frag is None:
+                return None
+            return ", ".join(
+                filter(None, (walk(s) for s in frag.selection_set.selections))
+            )
+        return None
+
+    return ", ".join(filter(None, (walk(s) for s in root.selection_set.selections))) or "_id"
+
+
+# ── spec/02：根 resolver（投影下推，无 N+1）──
+
+
+def _make_get(store, name, id_field):
+    async def resolve(_src, info, *, id):
+        projection = projection_from_info(info)
+        rows = await store.query(
+            f"{name}($condition:@c0) {{ {projection} }}", {"c0": {id_field: id}}
+        )
+        return rows[0] if rows else None
+
+    return resolve
+
+
+def _make_list(store, name):
+    async def resolve(_src, info, *, condition=None, sort=None, limit=None):
+        # spec/02 limit 守卫:缺省 50 防全表;超上限抛错(ERR_LIMIT: 稳定前缀),不静默截断
+        if limit is None:
+            limit = LIST_LIMIT_DEFAULT
+        if limit > LIST_LIMIT_MAX:
+            raise ValueError(f"ERR_LIMIT:list limit 上限 {LIST_LIMIT_MAX},收到 {limit}")
+        projection = projection_from_info(info)
+        head = name
+        parts, params = [], {}
+        if condition is not None:
+            parts.append("$condition:@c0")
+            params["c0"] = condition
+        if sort is not None:
+            parts.append("$sort:@s1")
+            params["s1"] = sort
+        parts.append("$limit:@l")
+        params["l"] = limit
+        head += f"({','.join(parts)})"
+        return await store.query(f"{head} {{ {projection} }}", params)
+
+    return resolve
+
+
+def _make_create(store, name):
+    async def resolve(_src, _info, *, input):
+        return await store.insert(name, input)
+
+    return resolve
+
+
+def _make_update(store, name, id_field):
+    async def resolve(_src, info, *, id, set):
+        await store.update(name, {id_field: id}, set)
+        projection = projection_from_info(info)
+        rows = await store.query(
+            f"{name}($condition:@c0) {{ {projection} }}", {"c0": {id_field: id}}
+        )
+        return rows[0] if rows else None
+
+    return resolve
+
+
+def _make_delete(store, name, id_field):
+    async def resolve(_src, _info, *, id):
+        await store.remove(name, {id_field: id})
+        return True
+
+    return resolve
+
+
+# ── schema 构建 ──
+
+
+def build_graphql_schema(
+    store,
+    *,
+    resources=None,
+    overrides=None,
+    extensions=None,
+    id_field="_id",
+):
+    overrides = dict(overrides or {})
+    extensions = dict(extensions or {})
+    names = resources if resources is not None else filter_archived(store.list())
+
+    query_fields = {}
+    mutation_fields = {}
+    used_override_keys = set()
+
+    def resolve_with_override(key, fallback):
+        fn = overrides.get(key)
+        if fn is not None:
+            used_override_keys.add(key)
+        return fn or fallback
+
+    for name in names:
+        defn = store.get(name)
+        xg = defn.get("x-graphql") or {}
+        if xg.get("hidden"):  # spec/03 钩子 1：模型级 hidden
+            continue
+        model_type = GraphQLObjectType(
+            name=name,
+            description=defn.get("description"),  # spec/05
+            # n=name 显式捕获:延迟 thunk 求值时循环变量已到末值,会造成嵌套类型重名
+            fields=lambda d=defn, n=name: _map_fields(_model_fields(d), n),
+        )
+
+        query_fields[f"get_{name}"] = GraphQLField(
+            model_type,
+            args={"id": GraphQLArgument(GraphQLNonNull(GraphQLID))},
+            resolve=resolve_with_override(f"Query.get_{name}", _make_get(store, name, id_field)),
+        )
+        query_fields[f"list_{name}"] = GraphQLField(
+            GraphQLNonNull(GraphQLList(GraphQLNonNull(model_type))),
+            args={
+                "condition": GraphQLArgument(GraphQLJSON),
+                "sort": GraphQLArgument(GraphQLJSON),
+                "limit": GraphQLArgument(GraphQLInt),
+            },
+            resolve=resolve_with_override(f"Query.list_{name}", _make_list(store, name)),
+        )
+        if not xg.get("readonly"):  # spec/03 钩子 1：模型级 readonly → 只出 Query
+            mutation_fields[f"create_{name}"] = GraphQLField(
+                model_type,
+                args={"input": GraphQLArgument(GraphQLNonNull(GraphQLJSON))},
+                resolve=resolve_with_override(
+                    f"Mutation.create_{name}", _make_create(store, name)
+                ),
+            )
+            mutation_fields[f"update_{name}"] = GraphQLField(
+                model_type,
+                args={
+                    "id": GraphQLArgument(GraphQLNonNull(GraphQLID)),
+                    "set": GraphQLArgument(GraphQLNonNull(GraphQLJSON)),
+                },
+                resolve=resolve_with_override(
+                    f"Mutation.update_{name}", _make_update(store, name, id_field)
+                ),
+            )
+            mutation_fields[f"delete_{name}"] = GraphQLField(
+                GraphQLNonNull(GraphQLBoolean),
+                args={"id": GraphQLArgument(GraphQLNonNull(GraphQLID))},
+                resolve=resolve_with_override(
+                    f"Mutation.delete_{name}", _make_delete(store, name, id_field)
+                ),
+            )
+
+    # spec/03 钩子 3：extend（SDL 同步追加）
+    for key, fields in extensions.items():
+        if key == "Query":
+            query_fields.update(fields)
+        elif key == "Mutation":
+            mutation_fields.update(fields)
+        else:
+            raise ValueError(f'extensions 仅支持 Query/Mutation，收到 "{key}"（spec/03）')
+
+    # spec/03：override 键构建期校验，未知路径报错不静默
+    for key in overrides:
+        if key not in used_override_keys:
+            raise ValueError(f'override 路径 "{key}" 未命中任何生成字段（spec/03）')
+
+    return GraphQLSchema(
+        query=GraphQLObjectType(name="Query", fields=lambda: query_fields),
+        mutation=(
+            GraphQLObjectType(name="Mutation", fields=lambda: mutation_fields)
+            if mutation_fields
+            else None
+        ),
+    )
+
+
+def export_sdl(schema):
+    """spec/01：SDL 导出（喂客户端 codegen）。"""
+    return print_schema(schema)
+
+
+# ── spec/04：HTTP 承载（FastAPI，可选依赖）──
+
+
+def create_app(
+    store,
+    *,
+    schema=None,
+    path="/graphql",
+    context_provider=None,
+    permission_error=None,
+    resources=None,
+    overrides=None,
+    extensions=None,
+    id_field="_id",
+    max_query_depth=None,
+    max_query_fields=None,
+    introspection=True,
+):
+    try:
+        from fastapi import FastAPI, Request
+        from fastapi.responses import HTMLResponse, JSONResponse
+    except ImportError as e:  # noqa: F841 — 报错信息自身已含原因
+        raise ImportError(
+            "create_app 需要安装 fastapi：pip install 'store-graphql-py[fastapi]'；"
+            "或仅用 build_graphql_schema 自行承载"
+        ) from e
+
+    app = FastAPI(title="store-graphql")
+    gql_schema = schema or build_graphql_schema(
+        store,
+        resources=resources,
+        overrides=overrides,
+        extensions=extensions,
+        id_field=id_field,
+    )
+    if permission_error is None:
+        permission_error = getattr(store, "PermissionError", None)
+
+    @app.get(path)
+    async def graphiql_page():
+        # spec/05：GET 返回 GraphiQL 文档页（执行走 POST；GET 查询执行列 v1）
+        return HTMLResponse(GRAPHIQL_HTML)
+
+    @app.post(path)
+    async def graphql_endpoint(request: Request):
+        raw = await request.body()
+        # spec/04：请求体上限 1MB（对齐 store-api 三端，防大 body 撑内存）
+        if len(raw) > (1 << 20):
+            return JSONResponse(
+                status_code=413,
+                content={"errors": [{"message": "请求体超过 1MB 上限（spec/04）"}]},
+            )
+        try:
+            body = json.loads(raw) if raw else {}
+            if not isinstance(body, dict):
+                raise ValueError("body 不是 JSON 对象")
+        except Exception:  # noqa: BLE001 — 非 JSON 请求体按 400 明确反馈，不静默
+            return JSONResponse(
+                status_code=400, content={"errors": [{"message": "请求体必须是 JSON"}]}
+            )
+        if context_provider is not None:
+            try:
+                ctx = context_provider(request)
+                if inspect.isawaitable(ctx):
+                    ctx = await ctx
+            except Exception as e:  # noqa: BLE001 — spec/04：权限类 ⇒ 403；其余 ⇒ 401
+                status = 403 if (permission_error and isinstance(e, permission_error)) else 401
+                return JSONResponse(
+                    status_code=status,
+                    content={"errors": [{"message": str(e) or "CONTEXT_ERROR"}]},
+                )
+            # spec/04：None 同样显式注入（清除语义必须落地，防身份跨请求残留）
+            store.set_context(ctx)
+        # spec/04 深度/复杂度/introspection 守卫:执行前独立 parse 检查
+        # (语法错不在此拦,维持执行器原路径;双 parse 成本微秒级,如实标注 spec/04)
+        depth_limit = MAX_QUERY_DEPTH if max_query_depth is None else max_query_depth
+        fields_limit = MAX_QUERY_FIELDS if max_query_fields is None else max_query_fields
+        query_str = body.get("query") or ""
+        try:
+            doc = parse(query_str)
+        except Exception:  # noqa: BLE001 — 语法解析失败交给执行器原路径报错
+            doc = None
+        if doc is not None:
+            depth = query_depth(doc)
+            if depth > depth_limit:
+                return JSONResponse(
+                    status_code=400,
+                    content={
+                        "errors": [
+                            {
+                                "message": f"ERR_DEPTH:查询深度 {depth} 超过上限 {depth_limit}",
+                                "extensions": {"code": "ERR_DEPTH"},
+                            }
+                        ]
+                    },
+                )
+            usage = query_field_count(doc)
+            if usage["introspection_used"] and not introspection:
+                return JSONResponse(
+                    status_code=400,
+                    content={
+                        "errors": [
+                            {
+                                "message": "ERR_INTROSPECTION:introspection 已禁用",
+                                "extensions": {"code": "ERR_INTROSPECTION"},
+                            }
+                        ]
+                    },
+                )
+            if usage["fields"] > fields_limit:
+                return JSONResponse(
+                    status_code=400,
+                    content={
+                        "errors": [
+                            {
+                                "message": f"ERR_COMPLEXITY:查询字段数 {usage['fields']} 超过上限 {fields_limit}",
+                                "extensions": {"code": "ERR_COMPLEXITY"},
+                            }
+                        ]
+                    },
+                )
+        result = await graphql(
+            gql_schema,
+            query_str,
+            variable_values=body.get("variables"),
+            operation_name=body.get("operationName"),
+        )
+        payload = {"data": result.data}
+        if result.errors:
+            payload["errors"] = [e.formatted for e in result.errors]
+        return JSONResponse(payload)
+
+    return app

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

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: store-graphql-py
+Version: 0.1.0
+Summary: GraphQL adapter that auto-generates standard GraphQL APIs for py-store schemas (schema-driven CRUD over GQL, projection pushdown)
+License: MIT
+Keywords: py-store,storepy,graphql,crud,gql
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: graphql-core>=3.2
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: fastapi>=0.110; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+
+# store-graphql-py
+
+GraphQL adapter that auto-generates standard GraphQL APIs for **py-store** schemas (schema-driven CRUD over GQL, projection pushdown).
+
+```python
+from store_graphql import build_graphql_schema, create_app, export_sdl
+
+schema = build_graphql_schema(store)      # 反射 py-store 已注册的 JSON schema
+app = create_app(store, schema=schema)    # FastAPI 承载（可选依赖）；或 graphql(schema, query) 自行执行
+export_sdl(schema)                        # SDL 导出，喂客户端 codegen
+```
+
+完整文档（双语主文档 / spec / conformance）：见仓库根 [README.zh-CN.md](https://github.com/coenddt/store-graphql#readme)。

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

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/store_graphql/__init__.py
+src/store_graphql/adapter.py
+src/store_graphql_py.egg-info/PKG-INFO
+src/store_graphql_py.egg-info/SOURCES.txt
+src/store_graphql_py.egg-info/dependency_links.txt
+src/store_graphql_py.egg-info/requires.txt
+src/store_graphql_py.egg-info/top_level.txt
+tests/test_conformance.py
+tests/test_e2e_real.py
+tests/test_smoke.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,9 @@
+graphql-core>=3.2
+
+[dev]
+pytest>=8
+fastapi>=0.110
+httpx>=0.27
+
+[fastapi]
+fastapi>=0.110

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

@@ -0,0 +1 @@
+store_graphql

store_graphql_py-0.1.0/tests/test_conformance.py

@@ -0,0 +1,88 @@
+"""conformance runner — 直接消费 ../../conformance/cases/*.json 执行断言。
+
+三端 runner 同构:同一份用例,同一套 expect 契约(dataKeys/gql/paramsLimit/errorCodePrefix)。
+语义变更必须先改 spec/,再改 cases/,再三端 runner——三者不一致即为缺陷。
+"""
+
+import asyncio
+import json
+from pathlib import Path
+
+from graphql import execute as gql_execute, parse
+
+from store_graphql import build_graphql_schema
+
+CASE = json.loads(
+    (Path(__file__).resolve().parents[2] / "conformance" / "cases" / "users-graphql.json").read_text(
+        encoding="utf-8"
+    )
+)
+
+
+class CaseStore:
+    def __init__(self, schema_defn):
+        self.defn = schema_defn
+        self.rows = []
+        self.gql_log = []
+
+    def list(self):
+        return [self.defn["name"]]
+
+    def get(self, _name):
+        return self.defn
+
+    async def query(self, gql, params=None):
+        self.gql_log.append({"gql": gql, "params": params})
+        cond = (params or {}).get("c0")
+        return [r for r in self.rows if not cond or all(r.get(k) == v for k, v in cond.items())]
+
+    async def insert(self, _name, data):
+        doc = {"_id": "u1", **data}
+        self.rows.append(doc)
+        return doc
+
+    async def update(self, _name, cond, data):
+        row = next(r for r in self.rows if all(r.get(k) == v for k, v in cond.items()))
+        row.update(data)
+        return row
+
+    async def remove(self, _name, cond):
+        self.rows = [r for r in self.rows if not all(r.get(k) == v for k, v in cond.items())]
+
+    def set_context(self, _ctx):
+        pass
+
+
+def test_conformance():
+    store = CaseStore(CASE["schema"])
+    schema = build_graphql_schema(store)
+
+    async def run_step(step):
+        result = await gql_execute(
+            schema, parse(step["query"]), variable_values=step.get("variables") or {}
+        )
+        return result
+
+    async def run_all():
+        for i, step in enumerate(CASE["steps"]):
+            result = await run_step(step)
+            expect = step["expect"]
+            errors = result.errors or ()
+            if expect.get("errorCodePrefix"):
+                assert errors, f"step#{i} 应抛 {expect['errorCodePrefix']}"
+                assert errors[0].message.startswith(expect["errorCodePrefix"]), (
+                    f"step#{i} 错误前缀不符: {errors[0].message}"
+                )
+                continue
+            assert not errors, f"step#{i} 不应有错误: {[e.message for e in errors]}"
+            data = result.data or {}
+            for key in expect.get("dataKeys") or []:
+                assert key in data, f"step#{i} data 缺少 {key}"
+            if "gql" in expect:
+                assert store.gql_log[-1]["gql"] == expect["gql"], f"step#{i} 投影下推串不符"
+            if "paramsLimit" in expect:
+                assert store.gql_log[-1]["params"]["l"] == expect["paramsLimit"], (
+                    f"step#{i} params.l 不符"
+                )
+
+    asyncio.run(run_all())

store_graphql_py-0.1.0/tests/test_e2e_real.py

@@ -0,0 +1,89 @@
+"""e2e(真实库)— py-store(真实 rust core)+ aiosqlite 内存库跑 GraphQL 全链路。
+
+验证点:适配层契约(store.list()/get() 真实返回结构)、投影下推串被真实 core 接受、
+CRUD 全链路真实落库(含归档编排)。依赖缺失 ⇒ pytest.skip 显式标注(不静默)。
+
+真实契约点(与 node 端 e2e 同款,出处见各断言注释):
+- SQL 源须传 executors.create_connection('sqlite', db) 描述符,裸传驱动实例被当 Mongo
+- py-store 不写 DDL,generate_ddl 纯文本由应用执行(aiosqlite 的 executescript 须 await)
+- 归档表 UserDeleted 由 core 自动注册,remove 的归档编排需要其 DDL
+"""
+
+import asyncio
+
+import pytest
+
+from store_graphql import build_graphql_schema
+
+pytest.importorskip("py_store", reason="py-store 未安装(pip install -e py-store)")
+pytest.importorskip("aiosqlite", reason="aiosqlite 未安装(pip install aiosqlite)")
+
+DEFN = {
+    "name": "User",
+    "collection": "users",
+    "idPrefix": "u",
+    "fields": {
+        "_id": {"type": "string"},
+        "name": {"type": "string"},
+        "age": {"type": "int"},
+    },
+}
+
+
+async def _run_case():
+    import aiosqlite
+    import py_store
+
+    async with aiosqlite.connect(":memory:") as db:
+        conn = py_store.executors.create_connection("sqlite", db)
+        await py_store.init({"default": conn})
+        py_store.store.register(DEFN)
+        # py-store 不写 DDL;aiosqlite 的 executescript 是协程,必须 await
+        await db.executescript(py_store.store.generate_ddl("sqlite", ["User"]))
+        await db.executescript(py_store.store.generate_ddl("sqlite", ["UserDeleted"]))
+
+        schema = build_graphql_schema(py_store.store)
+
+        async def run(query, variable_values=None):
+            from graphql import parse, execute as gql_execute
+
+            result = await gql_execute(
+                schema, parse(query), variable_values=variable_values or {}
+            )
+            if result.errors:
+                raise AssertionError(f"GraphQL 执行失败: {[e.message for e in result.errors]}")
+            return result.data
+
+        # create:真实 core 生成 _id + timestamps,真实落库
+        created = await run(
+            "mutation($input: JSON!) { create_User(input: $input) { _id name age } }",
+            {"input": {"name": "alice", "age": 30}},
+        )
+        real_id = created["create_User"]["_id"]
+        assert real_id.startswith("u"), f"应返回真实生成的 u 前缀 _id,实际 {real_id}"
+
+        # list:投影下推串经真实 core 解析并走 SQLite
+        listed = await run("{ list_User { _id name } }")
+        assert len(listed["list_User"]) == 1
+        assert listed["list_User"][0]["name"] == "alice"
+
+        # get:条件投影
+        got = await run(f'{{ get_User(id: "{real_id}") {{ name age }} }}')
+        assert got["get_User"] == {"name": "alice", "age": 30}
+
+        # update:写入 + 回读
+        updated = await run(
+            "mutation($id: ID!, $set: JSON!) { update_User(id: $id, set: $set) { name age } }",
+            {"id": real_id, "set": {"age": 31}},
+        )
+        assert updated["update_User"]["age"] == 31
+
+        # delete:归档编排(deletedCount + archivedCount)后列表为空
+        deleted = await run(f'mutation {{ delete_User(id: "{real_id}") }}')
+        assert deleted["delete_User"] is True
+        after = await run("{ list_User { _id } }")
+        assert after["list_User"] == []
+
+
+def test_e2e_real_sqlite():
+    asyncio.run(_run_case())

store_graphql_py-0.1.0/tests/test_smoke.py

@@ -0,0 +1,306 @@
+"""冒烟测试 — mock store(不连真实库,不依赖 rust core 绑定)。
+
+用例语义与 ../../conformance/cases/users-graphql.json 及 node 端 smoke.test.js 对齐。
+"""
+
+import asyncio
+
+import pytest
+from graphql import GraphQLBoolean, GraphQLField, graphql
+
+from store_graphql import build_graphql_schema, export_sdl, filter_archived
+
+DEFN = {
+    "name": "User",
+    "description": "用户表：平台账号主档",
+    "fields": {
+        "_id": {"type": "string", "description": "主键，u 前缀"},
+        "name": {"type": "string"},
+        "age": {"type": "int"},
+        "profile": {
+            "type": "object",
+            "description": "个人资料",
+            "fields": {"bio": {"type": "string"}},
+        },
+    },
+}
+
+
+class MockStore:
+    def __init__(self):
+        self.rows = []
+        self.gql_log = []
+
+    def list(self):
+        return ["User"]
+
+    def get(self, _name):
+        return DEFN
+
+    async def query(self, gql, params=None):
+        self.gql_log.append({"gql": gql, "params": params})
+        cond = (params or {}).get("c0")
+        return [
+            r
+            for r in self.rows
+            if not cond or all(r.get(k) == v for k, v in cond.items())
+        ]
+
+    async def insert(self, _name, data):
+        doc = {"_id": f"u{len(self.rows) + 1}", **data}
+        self.rows.append(doc)
+        return doc
+
+    async def update(self, _name, cond, data):
+        row = next(r for r in self.rows if all(r.get(k) == v for k, v in cond.items()))
+        row.update(data)
+        return row
+
+    async def remove(self, _name, cond):
+        self.rows = [r for r in self.rows if not all(r.get(k) == v for k, v in cond.items())]
+
+    def set_context(self, _ctx):
+        pass
+
+
+async def run(schema, query, variable_values=None):
+    result = await graphql(schema, query, variable_values=variable_values)
+    if result.errors:
+        raise AssertionError(f"GraphQL 执行失败: {[e.message for e in result.errors]}")
+    return result.data
+
+
+def test_filter_archived():
+    assert filter_archived(["User", "UserDeleted", "Log"]) == ["User", "Log"]
+
+
+def test_sdl_generation():
+    sdl = export_sdl(build_graphql_schema(MockStore()))
+    assert "type User {" in sdl
+    assert "get_User(id: ID!): User" in sdl
+    assert "list_User(condition: JSON, sort: JSON, limit: Int): [User!]!" in sdl
+    assert "create_User(input: JSON!): User" in sdl
+    assert "profile: User_profile" in sdl
+    # description 管道（spec/05）：模型/字段/嵌套类型三层透传
+    assert '"""用户表：平台账号主档"""' in sdl
+    assert '"""主键，u 前缀"""' in sdl
+    assert '"""个人资料"""' in sdl
+    assert "SecretLog" not in sdl
+
+
+def test_create_list_pushdown():
+    store = MockStore()
+    schema = build_graphql_schema(store)
+    created = asyncio.run(
+        run(
+            schema,
+            "mutation($input: JSON!) { create_User(input: $input) { _id name age } }",
+            {"input": {"name": "a", "age": 1}},
+        )
+    )
+    assert created["create_User"]["name"] == "a"
+
+    listed = asyncio.run(
+        run(
+            schema,
+            "query($c: JSON, $l: Int) { list_User(condition: $c, limit: $l) { name profile { bio } } }",
+            {"c": {"name": "a"}, "l": 10},
+        )
+    )
+    assert len(listed["list_User"]) == 1
+    assert listed["list_User"][0]["name"] == "a"
+
+    # 投影下推断言:selection 编入 GQL 串,参数按需拼接(spec/02 映射表)
+    last = store.gql_log[-1]
+    assert last["gql"] == "User($condition:@c0,$limit:@l) { name, profile { bio } }"
+    assert last["params"] == {"c0": {"name": "a"}, "l": 10}
+
+
+def test_get_update_delete():
+    store = MockStore()
+    schema = build_graphql_schema(store)
+    asyncio.run(
+        run(schema, "mutation($i: JSON!) { create_User(input: $i) { _id } }", {"i": {"name": "b"}})
+    )
+
+    got = asyncio.run(run(schema, '{ get_User(id: "u1") { name } }'))
+    assert got["get_User"]["name"] == "b"
+
+    updated = asyncio.run(
+        run(
+            schema,
+            "mutation($id: ID!, $set: JSON!) { update_User(id: $id, set: $set) { name age } }",
+            {"id": "u1", "set": {"age": 2}},
+        )
+    )
+    assert updated["update_User"]["age"] == 2
+
+    deleted = asyncio.run(run(schema, 'mutation { delete_User(id: "u1") }'))
+    assert deleted["delete_User"] is True
+    listed = asyncio.run(run(schema, "{ list_User { _id } }"))
+    assert listed["list_User"] == []
+
+
+def test_skip_and_fragment():
+    store = MockStore()
+    schema = build_graphql_schema(store)
+    asyncio.run(
+        run(schema, "mutation($i: JSON!) { create_User(input: $i) { _id } }", {"i": {"name": "c"}})
+    )
+    asyncio.run(
+        run(
+            schema,
+            "query($noAge: Boolean!) { list_User { name age @skip(if: $noAge) ...U } }"
+            "fragment U on User { name }",
+            {"noAge": True},
+        )
+    )
+    assert store.gql_log[-1]["gql"] == "User($limit:@l) { name, name }"
+
+
+def test_limit_guard():
+    # spec/02:缺省 50 / 超限 ERR_LIMIT: / 边界 1000
+    store = MockStore()
+    schema = build_graphql_schema(store)
+    asyncio.run(run(schema, "{ list_User { _id } }"))
+    last = store.gql_log[-1]
+    assert last["gql"] == "User($limit:@l) { _id }"
+    assert last["params"]["l"] == 50
+
+    asyncio.run(run(schema, "query($l: Int) { list_User(limit: $l) { _id } }", {"l": 1000}))
+    assert store.gql_log[-1]["params"]["l"] == 1000
+
+    result = asyncio.run(
+        graphql(schema, "query($l: Int) { list_User(limit: $l) { _id } }", variable_values={"l": 1001})
+    )
+    assert result.errors and "ERR_LIMIT:" in result.errors[0].message
+    assert result.data is None  # list_User 非空 ⇒ 错误冒泡至根,data 整体为 None
+
+
+def test_annotations_hidden_readonly():
+    store = MockStore()
+    hidden = {**DEFN, "name": "SecretLog", "x-graphql": {"hidden": True}}
+    readonly = {**DEFN, "name": "AuditEvent", "x-graphql": {"readonly": True}}
+    store.list = lambda: ["User", "SecretLog", "AuditEvent"]
+    store.get = lambda n: {"User": DEFN, "SecretLog": hidden, "AuditEvent": readonly}[n]
+    sdl = export_sdl(build_graphql_schema(store))
+    assert "SecretLog" not in sdl
+    assert "get_AuditEvent" in sdl
+    assert "create_AuditEvent" not in sdl
+
+
+def test_graphiql_page():
+    # spec/05：GET /graphql 返回 GraphiQL 文档页
+    from fastapi.testclient import TestClient
+
+    from store_graphql import create_app
+
+    client = TestClient(create_app(MockStore()))
+    resp = client.get("/graphql")
+    assert resp.status_code == 200
+    assert resp.headers["content-type"].startswith("text/html")
+    assert "graphiql" in resp.text.lower()
+
+
+class _PermissionError(Exception):
+    """模拟 store.PermissionError（RBAC 拒绝）。"""
+
+
+def test_security_matrix():
+    # spec/04 安全矩阵：403/401 分类、400 非 JSON、413 体限
+    from fastapi.testclient import TestClient
+
+    from store_graphql import create_app
+
+    store = MockStore()
+    store.PermissionError = _PermissionError
+
+    def provider(request):
+        user = request.headers.get("x-user")
+        if user == "bad":
+            raise _PermissionError("ERR_PERMISSION:无访问权限")
+        if user == "broken":
+            raise RuntimeError("上下文钩子故障")
+        return {"user": user}
+
+    client = TestClient(create_app(store, context_provider=provider))
+    post = lambda u, body, **kw: client.post(  # noqa: E731
+        "/graphql", content=body, headers={"x-user": u, "Content-Type": "application/json"}, **kw
+    )
+
+    assert post("bad", '{"query":"{ __typename }"}').status_code == 403
+    assert post("broken", '{"query":"{ __typename }"}').status_code == 401
+    assert post("alice", "not-json").status_code == 400
+    assert post("alice", '{"query":"' + "x" * ((1 << 20) + 10) + '"}').status_code == 413
+    ok = post("alice", '{"query":"{ __typename }"}')
+    assert ok.status_code == 200
+    assert ok.json()["data"]["__typename"] == "Query"
+
+
+def test_query_depth_guard():
+    # spec/04:深度算法单元 + HTTP 层小阈值 400
+    from graphql import parse
+
+    from store_graphql.adapter import MAX_QUERY_DEPTH, query_depth
+
+    deep = "{ " + "a { " * 10 + "x " + "}" * 10 + " }"
+    assert MAX_QUERY_DEPTH == 10
+    assert query_depth(parse(deep)) == 11
+    assert query_depth(parse("{ list_User { _id } }")) == 2
+    # fragment 深度计入(非环)+ 环引用给有限值不崩
+    assert query_depth(parse("query { ...A } fragment A on Query { list_User { _id } }")) == 2
+    assert query_depth(parse("query { ...A } fragment A on Query { list_User { ...A } }")) == 1
+
+    from fastapi.testclient import TestClient
+
+    from store_graphql import create_app
+
+    client = TestClient(create_app(MockStore(), max_query_depth=2))
+    ok = client.post("/graphql", json={"query": "{ list_User { _id } }"})
+    assert ok.status_code == 200
+    deep3 = client.post("/graphql", json={"query": "{ list_User { profile { bio } } }"})
+    assert deep3.status_code == 400
+    assert "ERR_DEPTH:" in deep3.json()["errors"][0]["message"]
+
+
+def test_complexity_and_introspection_guard():
+    # spec/04:字段计数单元 + max_query_fields 超限 + introspection 开关
+    from graphql import parse
+
+    from store_graphql.adapter import query_field_count
+
+    assert query_field_count(parse("{ list_User { _id } }"))["fields"] == 2
+    assert query_field_count(parse("{ __schema { queryType { name } } }"))["introspection_used"] is True
+
+    from fastapi.testclient import TestClient
+
+    from store_graphql import create_app
+
+    client = TestClient(create_app(MockStore(), max_query_fields=2, introspection=False))
+    post = lambda q: client.post("/graphql", json={"query": q})  # noqa: E731
+
+    assert post("{ list_User { _id } }").status_code == 200
+    over = post("{ list_User { _id name } }")
+    assert over.status_code == 400 and "ERR_COMPLEXITY:" in over.json()["errors"][0]["message"]
+    assert post("{ __typename }").status_code == 200
+    intro = post("{ __schema { queryType { name } } }")
+    assert intro.status_code == 400 and "ERR_INTROSPECTION:" in intro.json()["errors"][0]["message"]
+
+
+def test_override_and_extend():
+    store = MockStore()
+
+    async def override_list(_src, _info, **_args):
+        return [{"_id": "x", "name": "override", "age": 0, "profile": None}]
+
+    schema = build_graphql_schema(
+        store,
+        overrides={"Query.list_User": override_list},
+        extensions={"Query": {"ping": GraphQLField(GraphQLBoolean, resolve=lambda *_a: True)}},
+    )
+    data = asyncio.run(run(schema, "{ list_User { name } ping }"))
+    assert data["list_User"][0]["name"] == "override"
+    assert data["ping"] is True
+
+    with pytest.raises(ValueError, match="未命中"):
+        build_graphql_schema(store, overrides={"Query.list_Nope": override_list})