Changelog¶

All notable changes to this library are documented here. The format is based on Keep a Changelog and the project adheres to Semantic Versioning.

1.0.0¶

The first release. A GraphQL + Django toolkit built directly on graphene (graphene-core) and Pydantic v2 — no graphene-django, no djangorestframework, no django-filter.

Model types, mutations & the native backend¶

• DjangoModelType / DjangoModelMutation — define a Django model once and get query, list and create/update/delete operations. Backed by Meta.model and a native Pydantic v2 SerializerBackend that validates and persists with the Django ORM (field types, max_length, Decimal precision, required/nullable/ defaults, choices → Enum, FK pk types, M2M as a list of pks), and runs the DB-level checks Pydantic can't — FK existence, uniqueness and unique_together. Supports partial updates.
• Custom validation without a serializer: declare DRF-style inline validate_<field>(self, value) and an object-level validate(self, data) directly on the class, and/or pass a Meta.pydantic_model with validators (they compose).
• Atomic, relation-aware nested writes — Meta.nested_fields = {field: Model} for forward FK, reverse FK and M2M children, written in one transaction (parent or child failure rolls everything back) with field.subfield error paths.
• Custom output fields declared on a DjangoModelType are honored, including their resolve_<field> resolver methods (and source=), inherited/overridable down the MRO.

Filtering¶

• Native and / or / not filtering through a single nested filter: argument (a generated <Model>FilterInput), built on Django's ORM lookups + Q objects. Per-field lookups, relation descent (auto .distinct() on to-many joins), plain-pk / UUIDField filtering (id: { exact/in }), and choices filtered via their Enum. Declared with Meta.filter_fields (list or dict form); the common base lookup set is configurable via COMMON_FILTER_LOOKUPS. A FilterBackend seam keeps it swappable.
• Custom filtering logic via the get_queryset / filter_queryset hooks.

Lists, pagination & performance¶

• Three paginators — LimitOffsetGraphqlPagination, PageGraphqlPagination and CursorGraphqlPagination (keyset cursor with a non-opaque pageInfo). Pagination/ordering live on the results(...) subfield; lists expose the uniform results / totalCount shape, including nested related lists.
• Automatic N+1 query optimization — select_related / prefetch_related / .only() derived from the GraphQL selection (incl. filtered nested-list prefetches), tunable with OPTIMIZE_QUERYSET / OPTIMIZE_ONLY_FIELDS.
• An effective MAX_PAGE_SIZE ceiling applied even when no page-size arg is sent.

Subscriptions¶

• Real-time GraphQL subscriptions over Django Channels 4 (optional [subscriptions] extra) with an in-house signal → group_send engine; configurable notification payload (id-only vs full) and value-scoped "indexed" groups.

Permissions & security¶

• DRF-style permission classes (BasePermission, IsAuthenticated, IsAdmin, IsAuthenticatedOrReadOnly, …) usable on types, subscriptions and views.
• Query depth limiting (MAX_QUERY_DEPTH / Meta.max_deep) and query cost analysis (MAX_QUERY_COST / Meta.complexity, optional extensions.cost).
• Security middlewares — DisableIntrospectionMiddleware, AuthenticatedFieldsMiddleware — and ExtraGraphQLSchema for declaring private fields. Every execution error carries a machine-readable extensions.code.

Views¶

• GraphQLView (response caching + depth/cost rules + extensions.cost), BaseGraphQLView (minimal, self-contained — no graphene-django), and AuthenticatedGraphQLView (endpoint-level auth gate via the library's own permission classes, no DRF). GraphiQL is served from a self-contained CDN page, overridable with graphiql_template for offline / strict-CSP setups.

Directives¶

• Schema directives for string/number/list/date transforms (@title_case, @snake_case, @slugify, @truncate, @round, @abs, @unique, @date, …; custom directive names are snake_case), with directive arguments as GraphQL variables.

Requirements¶

• Python 3.12–3.14, Django 4.0–6.0, graphene >=3.3,<4, pydantic >=2,<3.