Undine - GraphQL for Django

pip install undine

Documentation: https://undine-graphql.dev/

Documentation for LLMs: https://undine-graphql.dev/llms.txt

Contributing: https://undine-graphql.dev/contributing/

Undine is a GraphQL library for Django. It's designed to be easy to use and extend while providing out-of-the-box solutions for many common issues GraphQL developers face.

Feature highlights:

Automatic generation of GraphQL types from Django models
Automatic query optimization
Logically composable filtering
Ordering based on enums
Single and bulk mutations, including relations
Hidden and input-only mutation inputs
Built-in permission and validation hooks
Support for Relay Global object IDs and Connection pagination
File uploads based on GraphQL multipart request specification
Support for asynchronous execution and DataLoaders
Subscriptions with WebSockets, Server-Sent Events, or Multipart HTTP
Apollo Federation v2 support
Server-side query caching
Optional persisted documents support
Lifecycle hooks for customizing the GraphQL request cycle
Hiding fields and types from schema
Incremental delivery (experimental)
Built-in testing tools

Check out the Tutorial to get started.

import asyncio
from collections.abc import AsyncIterator
from typing import Any

from undine import (
    Entrypoint,
    Field,
    Filter,
    FilterSet,
    GQLInfo,
    Input,
    MutationType,
    Order,
    OrderSet,
    QueryType,
    RootType,
    create_schema,
)
from undine.exceptions import GraphQLPermissionError, GraphQLValidationError
from undine.relay import Connection, Node
from undine.subscriptions import ModelCreateSubscription

from .models import Task


class TaskFilterSet(FilterSet[Task]):
    name = Filter(lookup="icontains")
    done = Filter()


class TaskOrderSet(OrderSet[Task]):
    id = Order()
    name = Order(null_placement="last")


@Node
@TaskFilterSet
@TaskOrderSet
class TaskType(QueryType[Task], schema_name="Task"):
    pk = Field()
    name = Field()

    @name.permissions
    def name_permissions(self, instance: Task, info: GQLInfo) -> None:
        if not info.context.user.is_authenticated:
            raise GraphQLPermissionError


class TaskCreateMutation(MutationType[Task]):
    name = Input()
    done = Input(default_value=False)

    @classmethod
    def __permissions__(cls, instance: Task, info: GQLInfo, input_data: dict[str, Any]) -> None:
        if not info.context.user.is_staff:
            msg = "Only staff members can create tasks"
            raise GraphQLPermissionError(msg)

    @classmethod
    def __validate__(cls, instance: Task, info: GQLInfo, input_data: dict[str, Any]) -> None:
        if len(input_data["name"]) < 3:
            msg = "Task name must be at least 3 characters"
            raise GraphQLValidationError(msg)


class Query(RootType):
    node = Entrypoint(Node)
    task = Entrypoint(TaskType, cache_time=10)
    tasks = Entrypoint(Connection(TaskType))


class Mutation(RootType):
    create_task = Entrypoint(TaskCreateMutation)
    bulk_create_tasks = Entrypoint(TaskCreateMutation, many=True)


class Subscription(RootType):
    task_created = Entrypoint(ModelCreateSubscription(TaskType))

    @Entrypoint
    async def countdown(self, info: GQLInfo) -> AsyncIterator[int]:
        for i in range(10, -1, -1):
            yield i
            await asyncio.sleep(1)


schema = create_schema(query=Query, mutation=Mutation, subscription=Subscription)

Metadata

Release files for undine 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for undine 0.4.1
File	Size	Uploaded
undine-0.4.1.tar.gz	288.1 kB	Sep 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for undine 0.4.1
File	Interpreter	ABI	Platform	Reset
undine-0.4.1-py3-none-any.whl 386.3 kB Sep 7, 2026	Python 3	none	any	Details

Total release size: 674.4 kB

Release files / undine-0.4.1.tar.gz

Download URL	undine-0.4.1.tar.gz
Size	288.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`ebde32ca136d7115db34fe9651d262f1c042a78c374e1fda632ed25609197a09`
BLAKE2b-256 checksum How to use checksums	`0bd5ee036e9d6245445bf3df74b9d10ae78a5dc8d20463d997943886285b6f75`
Upload date	Sep 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / undine-0.4.1-py3-none-any.whl

Download URL	undine-0.4.1-py3-none-any.whl
Size	386.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c9c4b38e18919715dca7233ae9cb8e264a5b81e236a9dbb5bb4df95a319dbd95`
BLAKE2b-256 checksum How to use checksums	`c27454742b9ed54d874f431f7a61a6f93b901db763973425f13db2c3fadc667c`
Upload date	Sep 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`