Metadata-Version: 2.5
Name: graftql
Version: v1.21.0.dev44411
Summary: GraftQL turns your SQLModel definitions into a fully-typed GraphQL API — no schema duplication, no glue code.
Project-URL: Homepage, https://github.com/lorrod/graftql
Project-URL: Documentation, https://lorrod.github.io/graftql/
Project-URL: Repository, https://github.com/lorrod/graftql
Project-URL: Issues, https://github.com/lorrod/graftql/issues
Author: lorrod
License: MIT
License-File: LICENSE
Keywords: api,fastapi,graphql,orm,sqlalchemy,sqlmodel,strawberry
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: fastapi==0.133.1
Requires-Dist: sqlmodel==0.0.37
Requires-Dist: strawberry-graphql[debug-server]==0.307.1
Provides-Extra: dev
Requires-Dist: aiosqlite>=0.20.0; extra == 'dev'
Requires-Dist: fastapi-cli>=0.0.5; extra == 'dev'
Requires-Dist: httpx>=0.27.2; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-env>=1.1.1; extra == 'dev'
Requires-Dist: pytest>=8.3.3; extra == 'dev'
Requires-Dist: taskipy>=1.12.0; extra == 'dev'
Provides-Extra: doc
Requires-Dist: asyncpg>=0.29.0; extra == 'doc'
Requires-Dist: greenlet>=3.0.3; extra == 'doc'
Requires-Dist: jinja2>=3.1.2; extra == 'doc'
Requires-Dist: mdx-include>=1.4.2; extra == 'doc'
Requires-Dist: mkdocs-macros-plugin>=1.0.5; extra == 'doc'
Requires-Dist: mkdocs-material>=9.4.7; extra == 'doc'
Requires-Dist: mkdocs<2,>=1.6; extra == 'doc'
Requires-Dist: mkdocstrings-python>=1.11.1; extra == 'doc'
Requires-Dist: mkdocstrings>=0.26.1; extra == 'doc'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/lorrod/graftql/main/docs/assets/graftql-wordmark-dark.svg">
    <img alt="GraftQL" src="https://raw.githubusercontent.com/lorrod/graftql/main/docs/assets/graftql-wordmark.svg" width="380">
  </picture>
</p>

<p align="center"><strong>SQLModel in, typed GraphQL out.</strong></p>

<p align="center">
  <a href="https://github.com/lorrod/graftql/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/lorrod/graftql/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://pypi.org/project/graftql/"><img alt="PyPI" src="https://img.shields.io/pypi/v/graftql?color=1f9d66"></a>
  <a href="https://pypi.org/project/graftql/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/graftql?color=1f9d66"></a>
  <a href="https://lorrod.github.io/graftql/"><img alt="Docs" src="https://img.shields.io/badge/docs-lorrod.github.io%2Fgraftql-1f9d66"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-1f9d66"></a>
</p>

GraftQL turns your SQLModel definitions into a fully-typed GraphQL API — no schema duplication, no glue code.

---

## Overview

**GraftQL** lets you define your data models once (as `GraftModel` subclasses) and get a
fully-typed GraphQL API automatically — no schema duplication, no glue code. It layers on top of
[SQLModel](https://sqlmodel.tiangolo.com/) for the ORM and [Strawberry](https://strawberry.rocks/)
for the GraphQL schema. Mount `GraftRouter` in any FastAPI app and your models are immediately
queryable and mutable over GraphQL — including paginated connections, filters, ordering, and
fine-grained permission hooks.

Async (SQLAlchemy async engines) and sync engines are both supported, and multiple database
engines can be registered under different names for multi-tenant or federated setups.

---

## Features

- **Single model class** — extend `GraftModel` instead of both `SQLModel` and a Strawberry type.
- **Auto GraphQL schema** — queries, mutations (PUT / DELETE), and paginated connections generated automatically.
- **DataLoaders** — declare relations with `Dl` and `ManyRelation`; N+1 queries solved out of the box.
- **Composable filters** — date ranges, ordering, and custom filter attributes, all typed.
- **Permission hooks** — override `permission_getter` per-model or supply a global `get_permission` function.
- **Async support** — pass an async SQLAlchemy engine and GraftQL handles the rest.
- **Multi-engine** — register multiple engines by name; each model picks its engine via `__enginename__`.
- **Federation-ready** — Strawberry federation directives can be applied through the schema DSL.

---

## Installation

```bash
pip install graftql
```

---

## Quick Start

```python
from datetime import date

from fastapi import FastAPI
from sqlmodel import create_engine

from graftql import Field, GraftModel, GraftRouter

# 1. Define your models — once. No separate Pydantic/Strawberry types needed.
class Student(GraftModel, table=True):
    id: int | None = Field(primary_key=True, default=None)
    name: str
    birth_date: date

# 2. Create tables and mount the router.
engine = create_engine("sqlite:///./dev.db")
GraftModel.metadata.create_all(engine)

app = FastAPI()
router = GraftRouter(
    engine=engine,
    enable_put_mutations=True,
    enable_delete_mutations=True,
)
app.include_router(router, prefix="/graphql")

# 3. Run:  uvicorn main:app --reload
#    Visit: http://localhost:8000/graphql
```

You can now run queries like:

```graphql
mutation {
  students {
    put(input: { name: "Alice", birthDate: "2000-01-01" }) { id }
  }
}

query {
  students {
    many { edges { node { id name birthDate } } }
  }
}
```

---

## Documentation

See the [documentation](https://lorrod.github.io/graftql/) for the full guide including relations, DataLoaders,
authentication, async engines, and federation.

---

## Contributing

1. Fork [lorrod/graftql](https://github.com/lorrod/graftql).
2. Create a feature branch: `git checkout -b feat/my-change`.
3. Make your changes and add tests.
4. Run the checks: `uv run --group dev ruff check . && uv run --group dev pytest`.
5. Open a pull request.

All contributions are welcome — bug reports, documentation fixes, and new features alike.

---

## License

MIT — see [LICENSE](LICENSE).
