sqlmodel-graphql 0.1.0__py3-none-any.whl

sqlmodel_graphql-0.1.0.dist-info/METADATA

@@ -0,0 +1,312 @@
+Metadata-Version: 2.4
+Name: sqlmodel-graphql
+Version: 0.1.0
+Summary: GraphQL SDL generation and query optimization for SQLModel
+Project-URL: Homepage, https://github.com/allmonday/sqlmodel-graphql
+Project-URL: Repository, https://github.com/allmonday/sqlmodel-graphql
+Author-email: tangkikodo <allmonday@126.com>
+License: MIT
+License-File: LICENSE
+Keywords: fastapi,graphql,sqlalchemy,sqlmodel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: aiosqlite>=0.22.1
+Requires-Dist: graphql-core>=3.2.0
+Requires-Dist: greenlet>=3.3.2
+Requires-Dist: sqlmodel>=0.0.14
+Provides-Extra: demo
+Requires-Dist: aiosqlite>=0.19.0; extra == 'demo'
+Requires-Dist: fastapi>=0.100.0; extra == 'demo'
+Requires-Dist: uvicorn>=0.23.0; extra == 'demo'
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.19.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SQLModel GraphQL
+
+GraphQL SDL generation and query optimization for SQLModel.
+
+## Features
+
+- **Automatic SDL Generation**: Generate GraphQL schema from SQLModel classes
+- **@query/@mutation Decorators**: Mark methods as GraphQL operations
+- **Query Optimization**: Parse GraphQL queries to generate optimized SQLAlchemy queries
+- **N+1 Prevention**: Automatic `selectinload` and `load_only` generation
+
+## Installation
+
+```bash
+pip install sqlmodel-graphql
+```
+
+Or with uv:
+
+```bash
+uv add sqlmodel-graphql
+```
+
+## Quick Start
+
+### 1. Define Your Models
+
+```python
+from typing import Optional
+from sqlmodel import SQLModel, Field, Relationship, select
+from sqlmodel_graphql import query, mutation, QueryMeta
+
+class User(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    name: str
+    email: str
+    posts: list["Post"] = Relationship(back_populates="author")
+
+    @query(name='users')
+    async def get_all(cls, limit: int = 10, query_meta: Optional[QueryMeta] = None) -> list['User']:
+        """Get all users with optional query optimization."""
+        from demo.database import async_session
+
+        async with async_session() as session:
+            stmt = select(cls).limit(limit)
+            if query_meta:
+                # Apply optimization: only load requested fields and relationships
+                stmt = stmt.options(*query_meta.to_options(cls))
+            result = await session.exec(stmt)
+            return list(result.all())
+
+    @query(name='user')
+    async def get_by_id(cls, id: int, query_meta: Optional[QueryMeta] = None) -> Optional['User']:
+        return await fetch_user(id, query_meta)
+
+    @mutation(name='createUser')
+    async def create(cls, name: str, email: str) -> 'User':
+        return await create_user(name, email)
+
+class Post(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    title: str
+    content: str = ""
+    author_id: int = Field(foreign_key="user.id")
+    author: User = Relationship(back_populates="posts")
+```
+
+### 2. Generate GraphQL SDL
+
+```python
+from sqlmodel_graphql import SDLGenerator
+
+generator = SDLGenerator([User, Post])
+sdl = generator.generate()
+print(sdl)
+```
+
+Output:
+
+```graphql
+type User {
+  id: Int
+  name: String!
+  email: String!
+  posts: [Post!]!
+}
+
+type Post {
+  id: Int
+  title: String!
+  content: String!
+  author_id: Int!
+  author: User!
+}
+
+type Query {
+  users(limit: Int): [User!]!
+  user(id: Int!): User
+}
+
+type Mutation {
+  createUser(name: String!, email: String!): User!
+}
+```
+
+### 3. Execute Queries with GraphQLHandler
+
+```python
+from sqlmodel_graphql import GraphQLHandler
+
+# Option 1: Auto-discover all entities (recommended)
+handler = GraphQLHandler()
+
+# Option 2: Use a custom base class
+class Base(SQLModel):
+    pass
+
+class User(Base, table=True):
+    ...
+
+handler = GraphQLHandler(base=Base)
+
+# Option 3: Explicitly specify entities
+handler = GraphQLHandler(entities=[User, Post])
+
+# Execute a GraphQL query
+result = await handler.execute("""
+{
+  users(limit: 5) {
+    id
+    name
+    posts {
+      title
+      comments {
+        content
+        author {
+          name
+        }
+      }
+    }
+  }
+}
+""")
+
+# Result includes nested relationships automatically:
+# {
+#   "data": {
+#     "users": [
+#       {
+#         "id": 1,
+#         "name": "Alice",
+#         "posts": [
+#           {
+#             "title": "Hello World",
+#             "comments": [
+#               {"content": "Great post!", "author": {"name": "Bob"}}
+#             ]
+#           }
+#         ]
+#       }
+#     ]
+#   }
+# }
+```
+
+## How It Works
+
+```
+GraphQL Query                        QueryMeta
+─────────────                        ─────────
+{ users {                            QueryMeta(
+  id                                   fields=[FieldSelection('id'), FieldSelection('name')],
+  name                                 relationships={
+  posts {                                'posts': RelationshipSelection(
+    title                                  fields=[FieldSelection('title')]
+  }                                     }
+}                                     }
+)
+       ↓
+  query_meta.to_options(User)
+       ↓
+  select(User).options(
+    load_only(User.id, User.name),
+    selectinload(User.posts).options(load_only(Post.title))
+  )
+```
+
+### Query Optimization Flow
+
+1. **GraphQLHandler** receives the query
+2. **QueryParser** parses the selection set into **QueryMeta**
+3. **QueryMeta** is injected into your `@query` method as `query_meta` parameter
+4. **query_meta.to_options(entity)** generates SQLAlchemy options:
+   - `load_only()` for requested scalar fields
+   - `selectinload()` for requested relationships
+5. Database query only fetches what's needed, preventing N+1 problems
+
+## API Reference
+
+### `@query(name=None, description=None)`
+
+Mark a method as a GraphQL query.
+
+```python
+@query(name='users', description='Get all users')
+async def get_all(cls, limit: int = 10, query_meta: Optional[QueryMeta] = None) -> list['User']:
+    ...
+```
+
+### `@mutation(name=None, description=None)`
+
+Mark a method as a GraphQL mutation.
+
+```python
+@mutation(name='createUser')
+async def create(cls, name: str, email: str) -> 'User':
+    ...
+```
+
+### `SDLGenerator(entities)`
+
+Generate GraphQL SDL from SQLModel classes.
+
+```python
+generator = SDLGenerator([User, Post])
+sdl = generator.generate()
+```
+
+### `GraphQLHandler(entities=None, base=None)`
+
+Execute GraphQL queries against SQLModel entities with auto-discovery support.
+
+```python
+# Auto-discover from SQLModel (default)
+handler = GraphQLHandler()
+
+# Use custom base class
+handler = GraphQLHandler(base=MyBase)
+
+# Explicit entities
+handler = GraphQLHandler(entities=[User, Post])
+
+result = await handler.execute("{ users { id name } }")
+```
+
+**Auto-Discovery Features:**
+- Automatically finds all SQLModel subclasses with `@query/@mutation` decorators
+- Includes all related entities through Relationship fields
+- Supports custom base classes for better organization
+- Recursive discovery of nested relationships
+
+### `QueryParser()`
+
+Parse GraphQL queries to QueryMeta.
+
+```python
+parser = QueryParser()
+metas = parser.parse("{ users { id name } }")
+# metas['users'] -> QueryMeta(fields=[...], relationships={...})
+```
+
+### `QueryMeta`
+
+Metadata extracted from GraphQL selection set.
+
+```python
+@dataclass
+class QueryMeta:
+    fields: list[FieldSelection]
+    relationships: dict[str, RelationshipSelection]
+
+    def to_options(self, entity: type[SQLModel]) -> list[Any]:
+        """Convert to SQLAlchemy options for query optimization."""
+```
+
+## License
+
+MIT License

sqlmodel_graphql-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+sqlmodel_graphql/__init__.py,sha256=KnCsvqbtz135cOKactcb1PplY-w5ARKVGD7B5oWPWBo,1667
+sqlmodel_graphql/decorator.py,sha256=z8mwzNfbYBnoHFM_pkD3tsjdJFORwpf8LwoekZg6C1g,4458
+sqlmodel_graphql/handler.py,sha256=ZCs8nYqoAlKpdMlVBgVxe-_vnLFOTGtAfk9M7wWWHG0,14364
+sqlmodel_graphql/introspection.py,sha256=MNCokC28WD5vcvIXYlq5IpVejpy6dEyWznZdy12C58U,13835
+sqlmodel_graphql/query_parser.py,sha256=SLC03j-k1YL41-8z6gYgvCQQir7uGwG0F6cpsqSl8K0,3148
+sqlmodel_graphql/sdl_generator.py,sha256=QQzCAl2g-WRU5XV1Y0dne22kwReH2iURFM6ShXTJ008,9105
+sqlmodel_graphql/type_converter.py,sha256=xuT2-BZ_kOt9EbosYZLYdk5_beU-CBRXAL1AVb_0-zU,5492
+sqlmodel_graphql/types.py,sha256=Xtus2Xws8wCKT8rMZsElzKtKY-R3LEY-_UmtuBGNMOM,5015
+sqlmodel_graphql-0.1.0.dist-info/METADATA,sha256=2MYdAZB7RqlYnenmV_KalOAqHZohTfaGE1XN-KVcheQ,7983
+sqlmodel_graphql-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sqlmodel_graphql-0.1.0.dist-info/licenses/LICENSE,sha256=lNVRR3y_bFVoFKuK2JM8N4sFaj3m-7j29kvL3olFi5Y,1067
+sqlmodel_graphql-0.1.0.dist-info/RECORD,,

sqlmodel_graphql-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sqlmodel_graphql-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tangkikodo
+
+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.