Metadata-Version: 2.4
Name: django-graphex
Version: 1.0.0
Summary: GraphQL for Django, powered by graphene and Pydantic: define types/mutations/subscriptions from your models, with nested filtering (and/or/not), pagination, permissions and directives.
Project-URL: Homepage, https://github.com/eamigo86/django-graphex
Project-URL: Repository, https://github.com/eamigo86/django-graphex
Project-URL: Documentation, https://github.com/eamigo86/django-graphex
Author-email: Ernesto Perez Amigo <eamigop86@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api,django,graphene,graphql,protocol
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries
Requires-Python: <4.0,>=3.12
Requires-Dist: django<7.0,>=4.0
Requires-Dist: graphene<4,>=3.3
Requires-Dist: graphql-relay<4,>=3.2
Requires-Dist: pydantic<3,>=2
Requires-Dist: python-dateutil<3.0,>=2.8.2
Requires-Dist: text-unidecode>=1.3
Provides-Extra: subscriptions
Requires-Dist: channels-redis>=4.2; extra == 'subscriptions'
Requires-Dist: channels<5.0,>=4.0; extra == 'subscriptions'
Description-Content-Type: text/markdown

# django-graphex

![Codecov](https://img.shields.io/codecov/c/github/eamigo86/django-graphex)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-graphex)
![Django Versions](https://img.shields.io/pypi/frameworkversions/django/django-graphex?label=django&color=0C4B33)
![PyPI](https://img.shields.io/pypi/v/django-graphex?color=blue)
![PyPI - License](https://img.shields.io/pypi/l/django-graphex)
![PyPI - Downloads](https://img.shields.io/pypi/dm/django-graphex?style=flat)
![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)

**GraphQL for Django, powered by [graphene](https://graphene-python.org/) and
[Pydantic](https://docs.pydantic.dev/).** Define your GraphQL API straight from your
Django models — no DRF, no `graphene-django`, no `django-filter`.

- **Model-first types & mutations** — `DjangoModelType` / `DjangoModelMutation`
  give you query, list and create/update/delete from a single `Meta.model`,
  validated and persisted with **Pydantic v2** + the Django ORM (FK existence,
  uniqueness, `unique_together`, partial updates, `choices` → Enum).
- **Logical filtering** — one nested `filter:` argument with `and` / `or` / `not`,
  per-field lookups, relation descent and plain-pk/UUID filtering (no `django-filter`).
- **Pagination** — limit/offset, page and keyset **cursor** paginators with a
  uniform `results` / `totalCount` shape (and an automatic N+1 query optimizer).
- **Custom validation** — DRF-style inline `validate_<field>()` / `validate()` or a
  `Meta.pydantic_model`.
- **Permissions, security & directives** — permission classes, depth & cost limits,
  introspection control, and string/number/date/list directives.
- **Subscriptions** — real-time GraphQL over Django Channels 4 (optional extra).

> **Migrating from `graphene-django-extras`?** See the
> [Migration Guide](https://eamigo86.github.io/django-graphex/migration.html).

## Requirements

- **Python:** 3.12+ (3.13, 3.14 supported)
- **Django:** 4.0+ (4.2, 5.0, 5.1, 5.2, 6.0 supported)
- **graphene:** >=3.3,<4
- **pydantic:** >=2,<3

## Installation

```bash
# uv (recommended)
uv add django-graphex
# real-time subscriptions (adds Django Channels 4):
uv add "django-graphex[subscriptions]"
```

```bash
# pip
pip install django-graphex
pip install "django-graphex[subscriptions]"
```

The base install never imports `channels`; only the `subscriptions` extra does.

## Quick start

```python
import graphene
from django.contrib.auth.models import User
from django_graphex import (
    DjangoListObjectType, DjangoListObjectField, DjangoObjectField, DjangoModelMutation,
)
from django_graphex.paginations import LimitOffsetGraphqlPagination


class UserListType(DjangoListObjectType):
    class Meta:
        model = User
        pagination = LimitOffsetGraphqlPagination()
        filter_fields = {"username": ("icontains", "exact"), "is_active": ("exact",)}


class UserMutation(DjangoModelMutation):      # define once -> create/update/delete
    class Meta:
        model = User


class Query(graphene.ObjectType):
    users = DjangoListObjectField(UserListType)


class Mutation(graphene.ObjectType):
    user_create = UserMutation.CreateField()
    user_update = UserMutation.UpdateField()
    user_delete = UserMutation.DeleteField()


schema = graphene.Schema(query=Query, mutation=Mutation)
```

Query it with the nested `filter:` argument (`and` / `or` / `not`):

```graphql
{
  users(filter: { is_active: { exact: true }, username: { icontains: "jo" } }) {
    results(limit: 10, ordering: "-date_joined") { id username }
    totalCount
  }
}
```

## Configuration

All settings live under a single `DJANGO_GRAPHEX` dict (every key is optional):

```python
# settings.py
DJANGO_GRAPHEX = {
    "DEFAULT_PAGINATION_CLASS": "django_graphex.paginations.LimitOffsetGraphqlPagination",
    "DEFAULT_PAGE_SIZE": 20,
    "MAX_PAGE_SIZE": 50,
    "CACHE_ACTIVE": True,
}
```

To use directives, add the middleware and pass `all_directives` to the schema:

```python
GRAPHENE = {"MIDDLEWARE": ["django_graphex.ExtraGraphQLDirectiveMiddleware"]}

from django_graphex import all_directives
schema = graphene.Schema(query=Query, mutation=Mutation, directives=all_directives)
```

## Documentation

📚 **[Full documentation](https://eamigo86.github.io/django-graphex/)** — including the
[Quick Start](https://eamigo86.github.io/django-graphex/quickstart/),
[Model backend](https://eamigo86.github.io/django-graphex/usage/backends/),
[Filtering](https://eamigo86.github.io/django-graphex/usage/filtering/),
[Pagination](https://eamigo86.github.io/django-graphex/usage/pagination/),
[Subscriptions](https://eamigo86.github.io/django-graphex/usage/subscriptions/),
[Settings](https://eamigo86.github.io/django-graphex/usage/settings/) and the
[Migration Guide](https://eamigo86.github.io/django-graphex/migration/).

## License

MIT License — see the [LICENSE](LICENSE) file.
