sqlmodel-graphql 0.1.0__tar.gz

sqlmodel_graphql-0.1.0/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3:*)",
+      "Bash(uv run python:*)",
+      "WebSearch",
+      "Bash(uv:*)"
+    ]
+  }
+}

sqlmodel_graphql-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: Test
+
+on:
+  push:
+    paths:
+      - 'src/sqlmodel_graphql/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run linter
+        run: uv run ruff check src/
+
+      - name: Run formatter check
+        run: uv run ruff format --check src/
+
+      - name: Test with pytest
+        run: uv run pytest tests/ -v

sqlmodel_graphql-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI via uv
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build the package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --token ${{ secrets.PYPI_PUBLISHER }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: See [CHANGELOG](https://github.com/allmonday/sqlmodel-graphql/blob/master/CHANGELOG.md) for details.
+          generate_release_notes: true
+          files: |
+            dist/*.tar.gz
+            dist/*.whl

sqlmodel_graphql-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+*.egg
+
+# Virtual environments
+.venv
+venv/
+env/
+ENV/
+
+# Database files
+*.db
+*.sqlite
+*.sqlite3
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Distribution
+*.manifest
+*.spec

sqlmodel_graphql-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

sqlmodel_graphql-0.1.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-03-06
+
+### Added
+- Initial release
+- Automatic GraphQL SDL generation from SQLModel classes
+- `@query` and `@mutation` decorators for defining GraphQL operations
+- `GraphQLHandler` for executing GraphQL queries with auto-discovery support
+- `QueryParser` for extracting QueryMeta from GraphQL queries
+- `QueryMeta.to_options()` for generating SQLAlchemy query optimizations
+- Support for nested relationship queries (User → Posts → Comments)
+- Auto-discovery of entities from SQLModel or custom base classes
+- Recursive collection of related entities through Relationship fields
+- Type extraction from complex type hints (Optional, List, forward references)
+- FastAPI integration example with GraphiQL interface
+- Comprehensive documentation and examples
+
+### Features
+- **Auto-discovery**: Automatically finds all SQLModel entities with `@query/@mutation` decorators
+- **Relationship Support**: Includes all related entities through Relationship fields
+- **N+1 Prevention**: Automatic `selectinload` and `load_only` generation based on query fields
+- **Type Safety**: Full support for Python type hints including forward references
+- **Framework Agnostic**: Can be integrated with any web framework (FastAPI, Flask, etc.)
+
+### Documentation
+- README with quick start guide
+- API reference documentation
+- How it works explanation
+- Demo application with examples
+- Release guide for maintainers
+
+## [Unreleased]
+
+### Planned
+- Subscription support
+- More database backends (PostgreSQL, MySQL)
+- Custom scalar types
+- Input type generation
+- Better error messages
+- Performance benchmarks

sqlmodel_graphql-0.1.0/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.

sqlmodel_graphql-0.1.0/PKG-INFO

@@ -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