storepy 0.1.0__tar.gz

storepy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 py-store contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

storepy-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: storepy
+Version: 0.1.0
+Summary: Lightweight multi-backend data layer (MongoDB / MySQL / SQLite / PostgreSQL): pure JSON schemas, GQL tree queries compiled to a single query, computed columns, soft-delete and role-based access control
+Author-email: leo <coen_ddt@qq.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/coenddt/py-store
+Project-URL: Repository, https://github.com/coenddt/py-store
+Project-URL: Issues, https://github.com/coenddt/py-store/issues
+Keywords: mongodb,mysql,sqlite,postgresql,asyncio,data-layer,query-builder,odm,pymongo,acl
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pymongo>=4.9
+Requires-Dist: rust-store-py<0.2.0,>=0.1.0
+Provides-Extra: mysql
+Requires-Dist: asyncmy>=0.2.9; extra == "mysql"
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == "postgres"
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.19; extra == "sqlite"
+Dynamic: license-file
+
+# py-store
+
+A lightweight multi-backend data layer for Python asyncio apps — define your models as pure JSON schemas, query with GQL tree syntax, and get role-based access control out of the box. One unified MongoDB-style dialect runs on **MongoDB, MySQL, SQLite and PostgreSQL**.
+
+## Supported backends
+
+| Backend | Notes |
+| --- | --- |
+| MongoDB | native aggregation pipeline (`find`/`aggregate`/`$lookup`) |
+| MySQL | parameterized SQL, `information_schema` introspection |
+| SQLite | parameterized SQL, `sqlite_master` + `PRAGMA` introspection |
+| PostgreSQL | parameterized SQL (`$n`), `RETURNING` support |
+
+GQL tree queries compile to a single native query per backend — never hand-write `$lookup` or raw SQL again.
+
+## Features
+
+- **Pure JSON schemas, zero code** — a model is just a dict: fields, relations, computes, indexes.
+- **Read-time defaults & computed columns** — writes store only user data; reads fill defaults and run `fn`/`asyncFn` computes.
+- **GQL tree queries → one native query** — nested relations resolve in a single query; never hand-write `$lookup` again.
+- **Smart mutation** — `mutation()` auto-detects upsert by `_id` + unique index and recursively fills relation children.
+- **Soft-delete built in** — every schema auto-registers a `<Model>Deleted` archive collection/table; `remove()` archives before deleting.
+- **Permission context** — ContextVar-based roles (`super_admin`/`admin`/`guest`/`creator`...), schema/field-level read/write whitelists, automatic owner-condition injection.
+- **Async-first** — built on PyMongo's `AsyncMongoClient` (pymongo >= 4.9).
+
+## Installation
+
+```bash
+pip install storepy
+```
+
+> The distribution name is `storepy`; the import package is `py_store`:
+> `from py_store import init, store`.
+
+Requires Python 3.10+ and one supported backend (MongoDB / MySQL / SQLite / PostgreSQL).
+
+## Quick start
+
+```python
+from pymongo import AsyncMongoClient
+from py_store import init, store
+
+client = AsyncMongoClient("mongodb://localhost:27017")
+await init(client["mydb"])   # idempotently creates indexes for registered schemas
+
+# Register a schema (pure JSON)
+store.register({
+    "name": "Post",                  # model name used in GQL
+    "collection": "posts",           # optional, defaults to name
+    "idPrefix": "PT",                # string _id: prefix + base36 timestamp + random
+    "fields": {
+        "title": {"type": "string", "default": ""},
+        "status": {"type": "string", "default": "draft"},
+        "tags": {"type": "array", "default": []},
+    },
+    "computes": {
+        "statusLabel": {"type": "string", "depends": ["status"],
+                        "fn": lambda doc: doc["status"].upper()},
+    },
+    "indexes": [{"keys": {"status": 1, "createdAt": -1}}],
+})
+
+# Write — only user data; defaults are filled on read
+doc = await store.insert("Post", {"title": "Hello"})
+
+# Query — GQL tree syntax, values referenced from params via @key
+items = await store.query(
+    "Post($condition:@c0,$sort:@s1,$limit:@l) { title, status, statusLabel }",
+    {"c0": {"status": "draft"}, "s1": {"createdAt": -1}, "l": 20},
+)
+```
+
+## GQL syntax
+
+```text
+Model($condition:@c0,$sort:@s1,$skip:@sk,$limit:@l1) {
+  field1, field2, obj.subField,
+  Relation($condition:@c2,$sort:@s3,$limit:@l2) { f3, Nested { f4 } }
+}
+```
+
+- Values come from the params dict: `{"c0": {...}, "s1": {...}}`.
+- Object sub-fields use dot notation; relations are declared in the schema (`type: "many" | "one"`) and resolved automatically — **do not hand-write `$lookup`**.
+- `$pipeline` passes a raw aggregation through as-is (no compute/defaults/permission trimming) — use with care; prefer `store.aggregate(model, pipeline)` for group/sum needs.
+
+## Query & write API
+
+```python
+items  = await store.query(gql, params)              # list[dict]
+one    = await store.query_one(gql, params)          # dict | None
+page   = await store.query_with_count(gql, params)   # {'items','total','hasMore','page','pageSize'} (pageSize capped at 5000)
+exists = await store.exists("Post", {"_id": pid})
+n      = await store.count("Post", {"status": "active"})
+
+doc    = await store.insert("Post", {...})           # auto _id / createdAt / updatedAt
+docs   = await store.insert_many("Post", [{...}, ...])
+await store.update("Post", {"_id": pid}, {"status": "live"})     # plain fields → $set
+await store.update("Post", {"_id": pid}, {"$inc": {"views": 1}}) # '$'-prefixed keys pass through as operators
+await store.update_many("Post", {"type": t}, {"status": "live"})
+r      = await store.remove("Post", {"_id": pid})    # archives to <collection>_deleted first
+await store.mutation("Post", {...})                  # smart upsert + recursive relation children
+await store.upsert("Post", {"code": "A1"}, {...})    # explicit-condition upsert (no relation handling)
+rows  = await store.aggregate("Post", pipeline)      # native aggregation
+```
+
+Notes:
+
+- `None` values are stripped before persisting; `_id` cannot be changed via `update`.
+- `createdAt`/`updatedAt` (ms) are framework-maintained — do not set them manually.
+- Snake-case aliases available: `query_one`, `insert_many`, `update_many`, `parse_gql`, `build_pipeline`, ...
+
+## Permission context
+
+```python
+# Set once per request (in router/dependency layer)
+store.set_context({"userId": uid, "roles": ["editor"]})
+
+# Internal/cron jobs — bypass permission checks
+await store.run_as_internal(lambda: store.remove("Post", {"_id": pid}))
+```
+
+- `super_admin`/`admin`/`internal` roles pass everything; other roles are checked against schema-level and field-level `read`/`write` whitelists; `guest` can never write.
+- `creator` is a pseudo-role resolved by `doc.createdBy == ctx.userId`; schemas granting it automatically get owner conditions injected on queries and ownership checks on update/remove.
+- No context set → permission checks disabled (backward compatible).
+- Denied access raises `store.PermissionError` (with `status = 403`).
+
+## Schema reference
+
+```python
+{
+    "name": "Order",
+    "collection": "orders",
+    "idPrefix": "OD",
+    "timestamps": True,                # default: auto-maintain createdAt/updatedAt (ms)
+    "fields": {
+        "_id": "string",                                        # shorthand
+        "title": {"type": "string", "default": ""},
+        "meta": {"type": "object", "default": {}, "fields": {...}},  # nested object fields
+    },
+    "relations": {
+        "items": {"model": "OrderItem", "type": "many",
+                  "localField": "_id", "foreignField": "orderId"},
+    },
+    "computes": {
+        "total": {"type": "float", "depends": ["amount"], "fn": lambda d: d["amount"] * 1.1},
+        "itemCount": {"type": "int", "lookup": {"$size": {"$ifNull": ["$items", []]}}},
+    },
+    "indexes": [
+        {"keys": {"status": 1}},
+        {"keys": {"code": 1}, "options": {"unique": True}},
+    ],
+    "read": ["editor", "viewer"],      # optional schema-level role whitelists
+    "write": ["editor"],
+}
+```
+
+Types: `string | int | long | float | double | boolean | array | object | date | any`.
+
+## License
+
+[MIT](LICENSE)

storepy-0.1.0/README.md

@@ -0,0 +1,161 @@
+# py-store
+
+A lightweight multi-backend data layer for Python asyncio apps — define your models as pure JSON schemas, query with GQL tree syntax, and get role-based access control out of the box. One unified MongoDB-style dialect runs on **MongoDB, MySQL, SQLite and PostgreSQL**.
+
+## Supported backends
+
+| Backend | Notes |
+| --- | --- |
+| MongoDB | native aggregation pipeline (`find`/`aggregate`/`$lookup`) |
+| MySQL | parameterized SQL, `information_schema` introspection |
+| SQLite | parameterized SQL, `sqlite_master` + `PRAGMA` introspection |
+| PostgreSQL | parameterized SQL (`$n`), `RETURNING` support |
+
+GQL tree queries compile to a single native query per backend — never hand-write `$lookup` or raw SQL again.
+
+## Features
+
+- **Pure JSON schemas, zero code** — a model is just a dict: fields, relations, computes, indexes.
+- **Read-time defaults & computed columns** — writes store only user data; reads fill defaults and run `fn`/`asyncFn` computes.
+- **GQL tree queries → one native query** — nested relations resolve in a single query; never hand-write `$lookup` again.
+- **Smart mutation** — `mutation()` auto-detects upsert by `_id` + unique index and recursively fills relation children.
+- **Soft-delete built in** — every schema auto-registers a `<Model>Deleted` archive collection/table; `remove()` archives before deleting.
+- **Permission context** — ContextVar-based roles (`super_admin`/`admin`/`guest`/`creator`...), schema/field-level read/write whitelists, automatic owner-condition injection.
+- **Async-first** — built on PyMongo's `AsyncMongoClient` (pymongo >= 4.9).
+
+## Installation
+
+```bash
+pip install storepy
+```
+
+> The distribution name is `storepy`; the import package is `py_store`:
+> `from py_store import init, store`.
+
+Requires Python 3.10+ and one supported backend (MongoDB / MySQL / SQLite / PostgreSQL).
+
+## Quick start
+
+```python
+from pymongo import AsyncMongoClient
+from py_store import init, store
+
+client = AsyncMongoClient("mongodb://localhost:27017")
+await init(client["mydb"])   # idempotently creates indexes for registered schemas
+
+# Register a schema (pure JSON)
+store.register({
+    "name": "Post",                  # model name used in GQL
+    "collection": "posts",           # optional, defaults to name
+    "idPrefix": "PT",                # string _id: prefix + base36 timestamp + random
+    "fields": {
+        "title": {"type": "string", "default": ""},
+        "status": {"type": "string", "default": "draft"},
+        "tags": {"type": "array", "default": []},
+    },
+    "computes": {
+        "statusLabel": {"type": "string", "depends": ["status"],
+                        "fn": lambda doc: doc["status"].upper()},
+    },
+    "indexes": [{"keys": {"status": 1, "createdAt": -1}}],
+})
+
+# Write — only user data; defaults are filled on read
+doc = await store.insert("Post", {"title": "Hello"})
+
+# Query — GQL tree syntax, values referenced from params via @key
+items = await store.query(
+    "Post($condition:@c0,$sort:@s1,$limit:@l) { title, status, statusLabel }",
+    {"c0": {"status": "draft"}, "s1": {"createdAt": -1}, "l": 20},
+)
+```
+
+## GQL syntax
+
+```text
+Model($condition:@c0,$sort:@s1,$skip:@sk,$limit:@l1) {
+  field1, field2, obj.subField,
+  Relation($condition:@c2,$sort:@s3,$limit:@l2) { f3, Nested { f4 } }
+}
+```
+
+- Values come from the params dict: `{"c0": {...}, "s1": {...}}`.
+- Object sub-fields use dot notation; relations are declared in the schema (`type: "many" | "one"`) and resolved automatically — **do not hand-write `$lookup`**.
+- `$pipeline` passes a raw aggregation through as-is (no compute/defaults/permission trimming) — use with care; prefer `store.aggregate(model, pipeline)` for group/sum needs.
+
+## Query & write API
+
+```python
+items  = await store.query(gql, params)              # list[dict]
+one    = await store.query_one(gql, params)          # dict | None
+page   = await store.query_with_count(gql, params)   # {'items','total','hasMore','page','pageSize'} (pageSize capped at 5000)
+exists = await store.exists("Post", {"_id": pid})
+n      = await store.count("Post", {"status": "active"})
+
+doc    = await store.insert("Post", {...})           # auto _id / createdAt / updatedAt
+docs   = await store.insert_many("Post", [{...}, ...])
+await store.update("Post", {"_id": pid}, {"status": "live"})     # plain fields → $set
+await store.update("Post", {"_id": pid}, {"$inc": {"views": 1}}) # '$'-prefixed keys pass through as operators
+await store.update_many("Post", {"type": t}, {"status": "live"})
+r      = await store.remove("Post", {"_id": pid})    # archives to <collection>_deleted first
+await store.mutation("Post", {...})                  # smart upsert + recursive relation children
+await store.upsert("Post", {"code": "A1"}, {...})    # explicit-condition upsert (no relation handling)
+rows  = await store.aggregate("Post", pipeline)      # native aggregation
+```
+
+Notes:
+
+- `None` values are stripped before persisting; `_id` cannot be changed via `update`.
+- `createdAt`/`updatedAt` (ms) are framework-maintained — do not set them manually.
+- Snake-case aliases available: `query_one`, `insert_many`, `update_many`, `parse_gql`, `build_pipeline`, ...
+
+## Permission context
+
+```python
+# Set once per request (in router/dependency layer)
+store.set_context({"userId": uid, "roles": ["editor"]})
+
+# Internal/cron jobs — bypass permission checks
+await store.run_as_internal(lambda: store.remove("Post", {"_id": pid}))
+```
+
+- `super_admin`/`admin`/`internal` roles pass everything; other roles are checked against schema-level and field-level `read`/`write` whitelists; `guest` can never write.
+- `creator` is a pseudo-role resolved by `doc.createdBy == ctx.userId`; schemas granting it automatically get owner conditions injected on queries and ownership checks on update/remove.
+- No context set → permission checks disabled (backward compatible).
+- Denied access raises `store.PermissionError` (with `status = 403`).
+
+## Schema reference
+
+```python
+{
+    "name": "Order",
+    "collection": "orders",
+    "idPrefix": "OD",
+    "timestamps": True,                # default: auto-maintain createdAt/updatedAt (ms)
+    "fields": {
+        "_id": "string",                                        # shorthand
+        "title": {"type": "string", "default": ""},
+        "meta": {"type": "object", "default": {}, "fields": {...}},  # nested object fields
+    },
+    "relations": {
+        "items": {"model": "OrderItem", "type": "many",
+                  "localField": "_id", "foreignField": "orderId"},
+    },
+    "computes": {
+        "total": {"type": "float", "depends": ["amount"], "fn": lambda d: d["amount"] * 1.1},
+        "itemCount": {"type": "int", "lookup": {"$size": {"$ifNull": ["$items", []]}}},
+    },
+    "indexes": [
+        {"keys": {"status": 1}},
+        {"keys": {"code": 1}, "options": {"unique": True}},
+    ],
+    "read": ["editor", "viewer"],      # optional schema-level role whitelists
+    "write": ["editor"],
+}
+```
+
+Types: `string | int | long | float | double | boolean | array | object | date | any`.
+
+## License
+
+[MIT](LICENSE)

storepy-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "storepy"
+version = "0.1.0"
+description = "Lightweight multi-backend data layer (MongoDB / MySQL / SQLite / PostgreSQL): pure JSON schemas, GQL tree queries compiled to a single query, computed columns, soft-delete and role-based access control"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["mongodb", "mysql", "sqlite", "postgresql", "asyncio", "data-layer", "query-builder", "odm", "pymongo", "acl"]
+authors = [
+    { name = "leo", email = "coen_ddt@qq.com" },
+]
+dependencies = [
+  "pymongo>=4.9",
+  "rust-store-py>=0.1.0,<0.2.0",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Framework :: AsyncIO",
+  "Topic :: Database",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+mysql = ["asyncmy>=0.2.9"]
+postgres = ["asyncpg>=0.29"]
+sqlite = ["aiosqlite>=0.19"]
+
+[project.urls]
+Homepage = "https://github.com/coenddt/py-store"
+Repository = "https://github.com/coenddt/py-store"
+Issues = "https://github.com/coenddt/py-store/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

storepy-0.1.0/setup.cfg

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

storepy-0.1.0/src/py_store/__init__.py

@@ -0,0 +1,210 @@
+"""
+py-store — 轻量多后端数据层（Python 版，Rust 单核心架构；支持 MongoDB / MySQL / SQLite / PostgreSQL）
+
+核心理念:
+  1. 纯 JSON schema 定义，零代码
+  2. Rust core 统一实现 GQL 解析 / 权限 / 计算列 / 命令规划（core-py 绑定）
+  3. src/py_store/*.py 为薄 Host 适配层：驱动 IO + 回调 + 占位符替换
+  4. Node 侧（core-node）复用同一 Rust core，双端语义天然一致
+
+用法:
+    from py_store import init, store
+
+    await init(db)                       # 单库简写（Mongo db 实例）
+    await init({                         # 多数据源（schema 的 datasource 绑定路由）
+        'default': mongo_db,
+        'mysql_a': executors.create_connection('mysql', mysql_pool),
+    })
+
+    items = await store.query(`Model($condition:@c0) { field1, field2 }`, {'c0': {...}})
+"""
+
+from collections.abc import Mapping
+from typing import Any
+
+from pymongo.errors import PyMongoError
+
+from . import crud, datasource, executors, introspect, permission, schema
+from .sync import sync_schema
+
+
+def _build_pipeline(gql, params=None):
+    """解析 GQL 并构建 pipeline，返回 `{tokens, ast, pipeline, projection}`"""
+    return schema.core.build_pipeline(
+        gql, params if params is not None else {}, permission.get_context())
+
+
+_store_map = {
+    # Schema 管理
+    'register': schema.register,
+    'get': schema.get,
+    'has': schema.has,
+    'list': schema.list,
+    # CRUD
+    'query': crud.query,
+    'queryOne': crud.query_one,
+    'queryWithCount': crud.query_with_count,
+    'queryFederated': crud.query_federated,
+    'exists': crud.exists,
+    'count': crud.count,
+    'insert': crud.insert,
+    'insertMany': crud.insert_many,
+    'update': crud.update,
+    'updateMany': crud.update_many,
+    'remove': crud.remove,
+    # Mutation — 智能持久化（upsert/insert + 父子关联填充）
+    'mutation': crud.mutation,
+    # Upsert — 显式条件 upsert（不处理父子关系）
+    'upsert': crud.upsert,
+    # 底层工具（调试/高级用法）
+    'buildPipeline': _build_pipeline,
+    'build_pipeline': _build_pipeline,
+    # 原生聚合查询
+    'aggregate': crud.aggregate,
+    # 结构同步（SQL 数据源：introspect → schemaFromRows → mergeSchema → register）
+    'syncSchema': sync_schema,
+    'sync_schema': sync_schema,
+    # 数据源连接（多后端路由）
+    'setConnections': crud.set_connections,
+    'set_connections': crud.set_connections,
+    # 权限控制（ContextVar 上下文）
+    'setContext': permission.set_context,
+    'getContext': permission.get_context,
+    'set_context': permission.set_context,
+    'get_context': permission.get_context,
+    'scopedRoles': permission.scoped_roles,
+    'scoped_roles': permission.scoped_roles,
+    'runAsInternal': permission.run_as_internal,
+    'run_as_internal': permission.run_as_internal,
+    'PermissionError': permission.PermissionError,
+    # 蛇形命名别名（Python 风格调用）
+    'query_one': crud.query_one,
+    'query_with_count': crud.query_with_count,
+    'query_federated': crud.query_federated,
+    'insert_many': crud.insert_many,
+    'update_many': crud.update_many,
+}
+
+
+class Store:
+    """以属性方式访问 _store_map，支持 store.query(...) 调用形态"""
+
+    async def query(self, gql: str, params: dict | None = None) -> list[dict[str, Any]]:
+        return await crud.query(gql, params)
+
+    async def query_one(self, gql: str, params: dict | None = None) -> dict[str, Any] | None:
+        return await crud.query_one(gql, params)
+
+    async def query_with_count(self, gql: str, params: dict | None = None) -> dict[str, Any]:
+        return await crud.query_with_count(gql, params)
+
+    async def query_federated(self, gql: str, params: dict | None = None) -> list[dict[str, Any]]:
+        """跨库联邦查询（一条 GQL 跨多数据源：各源取数 → 内存 join → 统一后处理）"""
+        return await crud.query_federated(gql, params)
+
+    async def insert(self, schema_name: str, data: dict) -> dict[str, Any]:
+        return await crud.insert(schema_name, data)
+
+    async def insert_many(self, schema_name: str, docs: list[dict]) -> list[dict[str, Any]]:
+        return await crud.insert_many(schema_name, docs)
+
+    async def update(self, schema_name: str, condition: dict, data: dict,
+                     options: dict | None = None) -> dict[str, Any] | None:
+        return await crud.update(schema_name, condition, data, options)
+
+    async def update_many(self, schema_name: str, condition: dict, data: dict) -> dict[str, Any]:
+        return await crud.update_many(schema_name, condition, data)
+
+    async def remove(self, schema_name: str, condition: dict) -> dict[str, Any]:
+        return await crud.remove(schema_name, condition)
+
+    async def exists(self, schema_name: str, condition: dict) -> bool:
+        return await crud.exists(schema_name, condition)
+
+    async def count(self, schema_name: str, filter: dict | None = None) -> int:
+        return await crud.count(schema_name, filter)
+
+    async def mutation(self, schema_name: str, data: dict | list[dict]) -> Any:
+        return await crud.mutation(schema_name, data)
+
+    async def upsert(self, schema_name: str, condition: dict, data: dict,
+                     options: dict | None = None) -> dict[str, Any] | None:
+        return await crud.upsert(schema_name, condition, data, options)
+
+    async def aggregate(self, schema_name: str, pipeline: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        return await crud.aggregate(schema_name, pipeline)
+
+    async def sync_schema(self, backend: str, driver: Any, introspect_options: dict | None = None,
+                          overlay: list | None = None, datasource: str | None = None,
+                          register_defs: bool = True) -> list[dict[str, Any]]:
+        return await sync_schema(backend, driver, introspect_options, overlay,
+                                 datasource, register_defs)
+
+    def build_pipeline(self, gql: str, params: dict | None = None) -> dict[str, Any]:
+        return _build_pipeline(gql, params)
+
+    def __getattr__(self, name):
+        return _store_map[name]
+
+
+# 自定义权限错误（实例可被 store.PermissionError 捕获）
+Store.PermissionError = permission.PermissionError
+
+store = Store()
+
+# 索引名对齐 MongoDB 自动命名（k1_v1_k2_v2），用于幂等创建
+async def _create_indexes_if_needed():
+    """按数据源分派：Mongo 源执行索引创建；SQL 后端**不建索引**（indexes 仅元数据）"""
+    names = schema.list()
+    for name in names:
+        s = schema.get(name)
+        db = datasource.connection_of_schema(name)
+        if datasource.is_sql(db):
+            continue  # SQL 后端不建索引（铁律 6）
+        coll = db[s['collection']]
+        try:
+            index_cursor = await coll.list_indexes()
+            existing_indexes = await index_cursor.to_list(length=None)
+        except PyMongoError:
+            existing_indexes = []
+
+        for idx in s.get('indexes') or []:
+            try:
+                keys = idx.get('keys')
+                if not keys:
+                    continue
+                # 合并 inline 选项（unique/sparse/expireAfterSeconds 等）与显式 options
+                explicit_options = idx.get('options') or {}
+                final_options = {k: v for k, v in idx.items() if k not in ('keys', 'options')}
+                final_options.update(explicit_options)
+
+                # 检查是否已有同 key 模式的索引（忽略选项差异）
+                name_from_keys = '_'.join(f'{k}_{v}' for k, v in keys.items())
+                if any(ei.get('name') == name_from_keys for ei in existing_indexes):
+                    continue
+
+                await coll.create_index(list(keys.items()), **final_options)
+            except PyMongoError as e:
+                import sys
+                print(f'[py-store] 创建索引失败 {s["collection"]}: {e}', file=sys.stderr)
+
+
+async def init(connections):
+    """
+    初始化 store — 传入数据源连接映射
+
+      - 多源：``init({'default': db, 'mysql_a': {'kind': 'mysql', 'exec': ...}})``
+      - 单源简写：``init(db)``（PyMongo async 的 db 实例，自动归一为 ``{'default': db}``）
+
+    连接按 schema 的 ``datasource`` 绑定路由；缺省绑定回落 ``default``。
+    """
+    if connections is None or (
+            not isinstance(connections, Mapping)
+            and not callable(getattr(connections, '__getitem__', None))):
+        raise TypeError('init(connections) 需要数据源连接映射（或单个 PyMongo 的 db 实例）')
+    datasource.set_connections(connections)
+
+    # 自动创建索引（仅 Mongo 源）— 幂等安全
+    await _create_indexes_if_needed()
+
+    return store