django-graphql 0.1.0__py3-none-any.whl

django_graphql/__init__.py

@@ -0,0 +1,21 @@
+"""SDL-first GraphQL for Django.
+
+Write your schema in GraphQL SDL, bind object types to Django models with
+``@model``, and let ``@queryset``/``@get`` generate N+1-aware resolvers.
+"""
+
+from .checks import SchemaIssue, register_django_check
+from .resolvers import default_field_resolver
+from .schema import Schema, SchemaError
+from .views import GraphQLView
+
+__all__ = [
+    "GraphQLView",
+    "Schema",
+    "SchemaError",
+    "SchemaIssue",
+    "default_field_resolver",
+    "register_django_check",
+]
+
+__version__ = "0.1.0"

django_graphql/checks.py

@@ -0,0 +1,101 @@
+"""Drift detection between SDL object types and their bound Django models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from django.core import checks as django_checks
+from django.core.exceptions import FieldDoesNotExist
+from django.db import models
+
+from .directives import RESERVED_ARGS
+from .naming import to_snake
+
+if TYPE_CHECKING:
+    from .schema import Schema
+
+
+@dataclass(frozen=True)
+class SchemaIssue:
+    """A mismatch between the SDL and the Django models it is bound to.
+
+    ``path`` is ``"Type.field"`` or ``"Type.field(arg)"``.
+    """
+
+    path: str
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.path}: {self.message}"
+
+
+def _has_attribute(model: type[models.Model], name: str) -> bool:
+    for candidate in (name, to_snake(name)):
+        try:
+            model._meta.get_field(candidate)
+            return True
+        except FieldDoesNotExist:
+            pass
+        if hasattr(model, candidate):
+            return True
+    return False
+
+
+def _lookup_root_exists(model: type[models.Model], arg: str) -> bool:
+    root = to_snake(arg).split("__", 1)[0]
+    if root == "pk":
+        return True
+    try:
+        model._meta.get_field(root)
+        return True
+    except FieldDoesNotExist:
+        return False
+
+
+def check_schema(schema: Schema) -> list[SchemaIssue]:
+    """Return every place where ``schema`` refers to something its models lack.
+
+    * Fields of ``@model`` types must exist on the model (field, reverse
+      accessor, property or method; camelCase is matched against snake_case).
+    * Filter arguments of ``@queryset``/``@get`` fields must start with a
+      model field name (``title__icontains`` -> ``title``).
+    * Fields with a custom resolver (see :meth:`Schema.resolver`) are skipped,
+      since they do not read from the model instance.
+    """
+    issues: list[SchemaIssue] = []
+    for type_name, model in schema.models.items():
+        gql_type = schema.graphql_schema.get_type(type_name)
+        for field_name in gql_type.fields:  # type: ignore[union-attr]
+            path = f"{type_name}.{field_name}"
+            if path in schema.custom_resolvers:
+                continue
+            if not _has_attribute(model, field_name):
+                issues.append(
+                    SchemaIssue(path, f"{model._meta.label} has no field or attribute '{field_name}'.")
+                )
+    for path, (model, kind) in schema.bound_fields.items():
+        type_name, field_name = path.split(".")
+        field = schema.graphql_schema.get_type(type_name).fields[field_name]  # type: ignore[union-attr]
+        reserved = RESERVED_ARGS if kind == "queryset" else frozenset()
+        for arg in field.args:
+            if arg in reserved:
+                continue
+            if not _lookup_root_exists(model, arg):
+                issues.append(
+                    SchemaIssue(f"{path}({arg})", f"'{arg}' is not a lookup on {model._meta.label}.")
+                )
+    return issues
+
+
+def register_django_check(schema: Schema, *, check_id: str = "django_graphql.E001") -> None:
+    """Register ``schema`` with Django's system check framework.
+
+    Every :class:`SchemaIssue` is reported as a ``checks.Error`` so
+    ``manage.py check`` (and therefore ``runserver``/``migrate``) surface drift.
+    """
+
+    def _check(app_configs: object = None, **kwargs: object) -> list[django_checks.CheckMessage]:
+        return [django_checks.Error(str(issue), obj=issue.path, id=check_id) for issue in check_schema(schema)]
+
+    django_checks.register(_check, "django_graphql")

django_graphql/directives.py

@@ -0,0 +1,56 @@
+"""SDL directives understood by :class:`django_graphql.Schema`.
+
+The directive definitions are prepended to every SDL document automatically,
+so schemas never need to declare them.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from graphql import (
+    DirectiveLocation,
+    GraphQLArgument,
+    GraphQLDirective,
+    GraphQLNonNull,
+    GraphQLString,
+    get_directive_values,
+)
+
+#: ``type Book @model(name: "library.Book")`` binds an object type to a Django model.
+MODEL = GraphQLDirective(
+    name="model",
+    locations=[DirectiveLocation.OBJECT],
+    args={"name": GraphQLArgument(GraphQLNonNull(GraphQLString))},
+    description="Bind this object type to a Django model given as 'app_label.ModelName'.",
+)
+
+#: ``books(...): [Book!]! @queryset`` resolves a list field from the model's default manager.
+QUERYSET = GraphQLDirective(
+    name="queryset",
+    locations=[DirectiveLocation.FIELD_DEFINITION],
+    description="Resolve a list field from the bound model's queryset; arguments become filters.",
+)
+
+#: ``book(id: ID!): Book @get`` resolves a single object (or null) by its arguments.
+GET = GraphQLDirective(
+    name="get",
+    locations=[DirectiveLocation.FIELD_DEFINITION],
+    description="Resolve a single object of the bound model; arguments become lookups.",
+)
+
+DIRECTIVES_SDL = """
+directive @model(name: String!) on OBJECT
+directive @queryset on FIELD_DEFINITION
+directive @get on FIELD_DEFINITION
+"""
+
+#: Argument names on ``@queryset`` fields that control paging/ordering instead of filtering.
+RESERVED_ARGS = frozenset({"limit", "offset", "orderBy"})
+
+
+def directive_values(directive: GraphQLDirective, node: Any) -> dict[str, Any] | None:
+    """Return the argument values of ``directive`` on an AST ``node``, or ``None`` if absent."""
+    if node is None:
+        return None
+    return get_directive_values(directive, node)

django_graphql/naming.py

@@ -0,0 +1,18 @@
+"""Name conversion between GraphQL (camelCase) and Django (snake_case)."""
+
+from __future__ import annotations
+
+import re
+
+_BOUNDARY = re.compile(r"(?<=[a-z0-9])([A-Z])")
+
+
+def to_snake(name: str) -> str:
+    """Convert ``camelCase`` to ``snake_case``; ``__`` lookup separators are preserved.
+
+    >>> to_snake("publishedYear")
+    'published_year'
+    >>> to_snake("title__icontains")
+    'title__icontains'
+    """
+    return _BOUNDARY.sub(r"_\1", name).lower()

django_graphql/optimizer.py

@@ -0,0 +1,94 @@
+"""Selection-aware queryset optimisation.
+
+Given the GraphQL selection for a list or single-object field, add
+``select_related`` for forward foreign keys / one-to-ones and
+``prefetch_related`` for reverse and many-to-many relations, so that a
+typical one-level-nested query runs in a constant number of SQL queries.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+
+from django.db import models
+from django.db.models import Field, ForeignObjectRel
+from graphql import FieldNode, FragmentDefinitionNode, FragmentSpreadNode, InlineFragmentNode
+
+from .naming import to_snake
+
+
+def _iter_fields(
+    selections: Iterable[object],
+    fragments: dict[str, FragmentDefinitionNode],
+) -> Iterator[FieldNode]:
+    """Yield the field nodes of a selection set, flattening fragments."""
+    for selection in selections:
+        if isinstance(selection, FieldNode):
+            yield selection
+        elif isinstance(selection, InlineFragmentNode):
+            yield from _iter_fields(selection.selection_set.selections, fragments)
+        elif isinstance(selection, FragmentSpreadNode):
+            fragment = fragments.get(selection.name.value)
+            if fragment is not None:
+                yield from _iter_fields(fragment.selection_set.selections, fragments)
+
+
+def relation_fields(model: type[models.Model]) -> dict[str, Field | ForeignObjectRel]:
+    """Map attribute names (forward field names and reverse accessors) to relation fields."""
+    result: dict[str, Field | ForeignObjectRel] = {}
+    for field in model._meta.get_fields():
+        if not field.is_relation:
+            continue
+        if field.auto_created and not field.concrete:
+            accessor = field.get_accessor_name()
+            if accessor:
+                result[accessor] = field
+        else:
+            result[field.name] = field
+    return result
+
+
+def relations_for_selection(
+    model: type[models.Model],
+    field_nodes: Iterable[FieldNode],
+    fragments: dict[str, FragmentDefinitionNode] | None = None,
+) -> tuple[list[str], list[str]]:
+    """Return ``(select_related, prefetch_related)`` names for the given selection.
+
+    Only sub-selections that themselves have a selection set (i.e. object
+    fields) are considered; scalars never trigger joins.
+    """
+    fragments = fragments or {}
+    relations = relation_fields(model)
+    select: list[str] = []
+    prefetch: list[str] = []
+    for node in field_nodes:
+        if node.selection_set is None:
+            continue
+        for child in _iter_fields(node.selection_set.selections, fragments):
+            if child.selection_set is None:
+                continue
+            graphql_name = child.name.value
+            name = graphql_name if graphql_name in relations else to_snake(graphql_name)
+            field = relations.get(name)
+            if field is None:
+                continue
+            single = field.many_to_one or field.one_to_one
+            target = select if single else prefetch
+            if name not in target:
+                target.append(name)
+    return select, prefetch
+
+
+def optimize(
+    queryset: models.QuerySet,
+    field_nodes: Iterable[FieldNode],
+    fragments: dict[str, FragmentDefinitionNode] | None = None,
+) -> models.QuerySet:
+    """Apply ``select_related``/``prefetch_related`` to ``queryset`` for the selection."""
+    select, prefetch = relations_for_selection(queryset.model, list(field_nodes), fragments)
+    if select:
+        queryset = queryset.select_related(*select)
+    if prefetch:
+        queryset = queryset.prefetch_related(*prefetch)
+    return queryset

django_graphql/resolvers.py

@@ -0,0 +1,116 @@
+"""Resolvers generated for ``@queryset``/``@get`` fields and the default field resolver."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Any
+
+from django.db import models
+from graphql import GraphQLError, GraphQLResolveInfo
+
+from .directives import RESERVED_ARGS
+from .naming import to_snake
+from .optimizer import optimize
+
+Resolver = Callable[..., Any]
+
+
+def materialize(value: Any) -> Any:
+    """Evaluate managers and querysets into lists; return anything else unchanged.
+
+    graphql-core treats objects with ``__aiter__`` (which Django querysets
+    have) as async iterables, so lists are handed to the executor instead.
+    """
+    if isinstance(value, models.Manager):
+        value = value.all()
+    if isinstance(value, models.QuerySet):
+        return list(value)
+    return value
+
+
+def wrap_resolver(func: Resolver) -> Resolver:
+    """Wrap a user resolver so returned querysets/managers are materialized."""
+
+    @functools.wraps(func)
+    def resolve(source: Any, info: GraphQLResolveInfo, **kwargs: Any) -> Any:
+        return materialize(func(source, info, **kwargs))
+
+    return resolve
+
+
+def default_field_resolver(source: Any, info: GraphQLResolveInfo, **kwargs: Any) -> Any:
+    """Resolve a field from ``source`` by attribute or mapping key.
+
+    Tries the GraphQL name first, then its snake_case form. Related managers
+    (reverse foreign keys, many-to-many) are evaluated via ``manager.all()``
+    so prefetched results are reused; plain callables are called with the
+    field arguments.
+    """
+    name = info.field_name
+    value: Any = None
+    if isinstance(source, dict):
+        value = source.get(name, source.get(to_snake(name)))
+    else:
+        for candidate in (name, to_snake(name)):
+            if hasattr(source, candidate):
+                value = getattr(source, candidate)
+                break
+    if callable(value) and not isinstance(value, models.Manager):
+        value = value(**kwargs)
+    return materialize(value)
+
+
+def _filters(kwargs: dict[str, Any], reserved: frozenset[str]) -> dict[str, Any]:
+    """Turn GraphQL arguments into ORM lookups, dropping reserved and null ones."""
+    return {to_snake(k): v for k, v in kwargs.items() if k not in reserved and v is not None}
+
+
+def _base_queryset(model: type[models.Model], info: GraphQLResolveInfo) -> models.QuerySet:
+    queryset = model._default_manager.all()
+    return optimize(queryset, info.field_nodes, info.fragments)
+
+
+def make_queryset_resolver(model: type[models.Model], max_limit: int | None) -> Resolver:
+    """Build a resolver returning filtered, ordered and sliced ``model`` instances.
+
+    Arguments ``limit``, ``offset`` and ``orderBy`` control paging and ordering;
+    every other non-null argument is passed to ``QuerySet.filter`` after
+    camelCase-to-snake_case conversion (so ``title__icontains`` and
+    ``publishedYear__gte`` both work). ``limit`` is capped at ``max_limit``.
+    """
+
+    def resolve(source: Any, info: GraphQLResolveInfo, **kwargs: Any) -> list[models.Model]:
+        queryset = _base_queryset(model, info).filter(**_filters(kwargs, RESERVED_ARGS))
+        order_by = kwargs.get("orderBy")
+        if order_by:
+            queryset = queryset.order_by(*(to_snake(o) for o in order_by))
+        offset = kwargs.get("offset") or 0
+        limit = kwargs.get("limit")
+        if offset < 0 or (limit is not None and limit < 0):
+            raise GraphQLError("'limit' and 'offset' must be non-negative.")
+        if max_limit is not None:
+            limit = max_limit if limit is None else min(limit, max_limit)
+        if offset or limit is not None:
+            queryset = queryset[offset : None if limit is None else offset + limit]
+        return list(queryset)
+
+    return resolve
+
+
+def make_get_resolver(model: type[models.Model]) -> Resolver:
+    """Build a resolver returning the single ``model`` instance matching the arguments.
+
+    Returns ``None`` when nothing matches and raises a GraphQL error when the
+    lookup is ambiguous.
+    """
+
+    def resolve(source: Any, info: GraphQLResolveInfo, **kwargs: Any) -> models.Model | None:
+        try:
+            return _base_queryset(model, info).get(**_filters(kwargs, frozenset()))
+        except model.DoesNotExist:
+            return None
+        except model.MultipleObjectsReturned as exc:
+            raise GraphQLError(f"More than one {model.__name__} matches {kwargs!r}.") from exc
+
+    return resolve

django_graphql/schema.py

@@ -0,0 +1,186 @@
+"""The :class:`Schema` object: SDL in, executable Django-backed GraphQL schema out."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any, Literal, TypeVar
+
+from django.apps import apps
+from django.db import models
+from graphql import (
+    ExecutionResult,
+    GraphQLList,
+    GraphQLObjectType,
+    GraphQLSchema,
+    build_schema,
+    get_nullable_type,
+    graphql_sync,
+)
+
+from .checks import SchemaIssue, check_schema
+from .directives import DIRECTIVES_SDL, GET, MODEL, QUERYSET, directive_values
+from .resolvers import (
+    default_field_resolver,
+    make_get_resolver,
+    make_queryset_resolver,
+    wrap_resolver,
+)
+
+F = TypeVar("F", bound=Callable[..., Any])
+BindingKind = Literal["queryset", "get"]
+
+
+class SchemaError(Exception):
+    """Raised when the SDL cannot be bound to Django models."""
+
+
+class Schema:
+    """An executable GraphQL schema built from SDL and bound to Django models.
+
+    Object types annotated with ``@model(name: "app_label.Model")`` are bound
+    to that model; fields annotated with ``@queryset`` (list of a bound type)
+    or ``@get`` (single bound type) get generated resolvers. All other fields
+    use :func:`~django_graphql.resolvers.default_field_resolver` unless a
+    custom resolver is registered with :meth:`resolver`.
+
+    Args:
+        sdl: The schema in GraphQL SDL. The ``@model``, ``@queryset`` and
+            ``@get`` directive definitions are added automatically.
+        resolvers: Optional mapping of ``"Type.field"`` to resolver callables,
+            equivalent to decorating each with :meth:`resolver`.
+        max_limit: Upper bound applied to every ``@queryset`` field's
+            ``limit`` (also used when no ``limit`` is given). ``None`` disables it.
+
+    Raises:
+        SchemaError: on unknown models, misplaced directives or unknown
+            resolver paths.
+    """
+
+    def __init__(
+        self,
+        sdl: str,
+        *,
+        resolvers: Mapping[str, Callable[..., Any]] | None = None,
+        max_limit: int | None = 100,
+    ) -> None:
+        self.sdl = sdl
+        self.max_limit = max_limit
+        self.graphql_schema: GraphQLSchema = build_schema(DIRECTIVES_SDL + sdl)
+        #: GraphQL object type name -> bound Django model.
+        self.models: dict[str, type[models.Model]] = {}
+        #: ``"Type.field"`` -> (model, "queryset" | "get") for generated resolvers.
+        self.bound_fields: dict[str, tuple[type[models.Model], BindingKind]] = {}
+        #: ``"Type.field"`` -> user-registered resolver.
+        self.custom_resolvers: dict[str, Callable[..., Any]] = {}
+        self._bind_models()
+        self._bind_fields()
+        for path, func in (resolvers or {}).items():
+            self.resolver(path)(func)
+
+    # -- building -------------------------------------------------------------
+
+    def _object_types(self) -> list[GraphQLObjectType]:
+        return [
+            t
+            for name, t in self.graphql_schema.type_map.items()
+            if isinstance(t, GraphQLObjectType) and not name.startswith("__")
+        ]
+
+    def _bind_models(self) -> None:
+        for gql_type in self._object_types():
+            values = directive_values(MODEL, gql_type.ast_node)
+            if values is None:
+                continue
+            label = values["name"]
+            try:
+                self.models[gql_type.name] = apps.get_model(label)
+            except (LookupError, ValueError) as exc:
+                raise SchemaError(f"{gql_type.name}: unknown Django model '{label}'.") from exc
+
+    def _bind_fields(self) -> None:
+        for gql_type in self._object_types():
+            for field_name, field in gql_type.fields.items():
+                path = f"{gql_type.name}.{field_name}"
+                field.resolve = default_field_resolver
+                is_queryset = directive_values(QUERYSET, field.ast_node) is not None
+                is_get = directive_values(GET, field.ast_node) is not None
+                if not (is_queryset or is_get):
+                    continue
+                if is_queryset and is_get:
+                    raise SchemaError(f"{path}: @queryset and @get are mutually exclusive.")
+                kind: BindingKind = "queryset" if is_queryset else "get"
+                model = self._model_for_return_type(path, field.type, many=is_queryset)
+                self.bound_fields[path] = (model, kind)
+                field.resolve = (
+                    make_queryset_resolver(model, self.max_limit)
+                    if is_queryset
+                    else make_get_resolver(model)
+                )
+
+    def _model_for_return_type(self, path: str, gql_type: Any, *, many: bool) -> type[models.Model]:
+        nullable = get_nullable_type(gql_type)
+        directive = "@queryset" if many else "@get"
+        if many:
+            if not isinstance(nullable, GraphQLList):
+                raise SchemaError(f"{path}: {directive} requires a list return type.")
+            nullable = get_nullable_type(nullable.of_type)
+        elif isinstance(nullable, GraphQLList):
+            raise SchemaError(f"{path}: {directive} requires a non-list return type.")
+        name = getattr(nullable, "name", None)
+        if name not in self.models:
+            raise SchemaError(f"{path}: {directive} must return a type annotated with @model.")
+        return self.models[name]
+
+    # -- public API -------------------------------------------------------------
+
+    def resolver(self, path: str) -> Callable[[F], F]:
+        """Decorator registering a custom resolver for ``"Type.field"``.
+
+        The resolver receives ``(source, info, **arguments)``; ``info.context``
+        is the Django ``HttpRequest`` when executed through :class:`GraphQLView`.
+        It replaces any generated resolver for that field. Returned querysets
+        and managers are evaluated to lists. The original function is returned.
+        """
+        type_name, _, field_name = path.partition(".")
+        gql_type = self.graphql_schema.get_type(type_name)
+        if not isinstance(gql_type, GraphQLObjectType) or field_name not in gql_type.fields:
+            raise SchemaError(f"Cannot register resolver: no field '{path}' in schema.")
+        field = gql_type.fields[field_name]
+
+        def decorator(func: F) -> F:
+            field.resolve = wrap_resolver(func)
+            self.custom_resolvers[path] = func
+            self.bound_fields.pop(path, None)
+            return func
+
+        return decorator
+
+    def execute(
+        self,
+        query: str,
+        variables: Mapping[str, Any] | None = None,
+        *,
+        operation_name: str | None = None,
+        context: Any = None,
+        root: Any = None,
+    ) -> ExecutionResult:
+        """Parse, validate and execute ``query`` synchronously."""
+        return graphql_sync(
+            self.graphql_schema,
+            query,
+            root_value=root,
+            context_value=context,
+            variable_values=dict(variables) if variables is not None else None,
+            operation_name=operation_name,
+        )
+
+    def check(self) -> list[SchemaIssue]:
+        """Report SDL fields and filter arguments that do not exist on bound models."""
+        return check_schema(self)
+
+    def as_view(self, **initkwargs: Any) -> Callable[..., Any]:
+        """Return a CSRF-exempt Django view serving this schema (see :class:`GraphQLView`)."""
+        from .views import GraphQLView
+
+        return GraphQLView.as_view(schema=self, **initkwargs)
+

django_graphql/views.py

@@ -0,0 +1,121 @@
+"""A plain Django class-based view that serves a :class:`~django_graphql.Schema` over HTTP."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from django.http import HttpRequest, HttpResponse, JsonResponse
+from django.utils.decorators import method_decorator
+from django.views import View
+from django.views.decorators.csrf import csrf_exempt
+from graphql import (
+    GraphQLError,
+    OperationType,
+    execute,
+    get_operation_ast,
+    parse,
+    validate,
+)
+
+if TYPE_CHECKING:
+    from .schema import Schema
+
+
+class BadRequest(Exception):
+    """Raised for malformed GraphQL-over-HTTP requests (answered with HTTP 400)."""
+
+
+@method_decorator(csrf_exempt, name="dispatch")
+class GraphQLView(View):
+    """Serve GraphQL over HTTP following the common GraphQL-over-HTTP conventions.
+
+    * ``POST`` with ``application/json`` body ``{"query", "variables", "operationName"}``
+      or form-encoded fields of the same names.
+    * ``GET`` with ``?query=...&variables=<json>&operationName=...``; only
+      query operations are allowed over GET (mutations get HTTP 405).
+
+    Responses are ``{"data": ..., "errors": [...]}`` JSON. Requests that fail
+    before execution (bad JSON, syntax or validation errors) return HTTP 400;
+    execution errors return HTTP 200 alongside partial data, or HTTP 400 when
+    the error nulled the entire ``data``. The Django
+    ``HttpRequest`` is passed as ``info.context``.
+    """
+
+    schema: Schema | None = None
+    http_method_names = ["get", "post"]
+
+    def get(self, request: HttpRequest) -> HttpResponse:
+        params = {k: request.GET.get(k) for k in ("query", "variables", "operationName")}
+        return self._respond(request, params, allow_mutation=False)
+
+    def post(self, request: HttpRequest) -> HttpResponse:
+        if request.content_type == "application/json":
+            try:
+                body = json.loads(request.body or b"{}")
+            except json.JSONDecodeError:
+                return self._error("Request body is not valid JSON.", 400)
+            if not isinstance(body, dict):
+                return self._error("Request body must be a JSON object.", 400)
+            params: dict[str, Any] = body
+        else:
+            params = {k: request.POST.get(k) for k in ("query", "variables", "operationName")}
+        return self._respond(request, params, allow_mutation=True)
+
+    # -- helpers ----------------------------------------------------------------
+
+    @staticmethod
+    def _error(message: str, status: int) -> JsonResponse:
+        return JsonResponse({"errors": [{"message": message}]}, status=status)
+
+    @staticmethod
+    def _parse_variables(raw: Any) -> dict[str, Any] | None:
+        if raw in (None, ""):
+            return None
+        if isinstance(raw, str):
+            try:
+                raw = json.loads(raw)
+            except json.JSONDecodeError as exc:
+                raise BadRequest("'variables' is not valid JSON.") from exc
+        if not isinstance(raw, dict):
+            raise BadRequest("'variables' must be a JSON object.")
+        return raw
+
+    def _respond(self, request: HttpRequest, params: dict[str, Any], *, allow_mutation: bool) -> HttpResponse:
+        if self.schema is None:
+            raise TypeError("GraphQLView requires a 'schema' (use schema.as_view()).")
+        query = params.get("query")
+        if not query or not isinstance(query, str):
+            return self._error("Must provide a 'query' string.", 400)
+        try:
+            variables = self._parse_variables(params.get("variables"))
+        except BadRequest as exc:
+            return self._error(str(exc), 400)
+        operation_name = params.get("operationName") or None
+
+        try:
+            document = parse(query)
+        except GraphQLError as exc:
+            return JsonResponse({"errors": [exc.formatted]}, status=400)
+        schema = self.schema.graphql_schema
+        validation_errors = validate(schema, document)
+        if validation_errors:
+            return JsonResponse({"errors": [e.formatted for e in validation_errors]}, status=400)
+
+        operation = get_operation_ast(document, operation_name)
+        if not allow_mutation and operation is not None and operation.operation != OperationType.QUERY:
+            response = self._error(f"Can only perform a {operation.operation.value} over POST.", 405)
+            response["Allow"] = "POST"
+            return response
+
+        result = execute(
+            schema,
+            document,
+            context_value=request,
+            variable_values=variables,
+            operation_name=operation_name,
+        )
+        payload: dict[str, Any] = {"data": result.data}
+        if result.errors:
+            payload["errors"] = [e.formatted for e in result.errors]
+        return JsonResponse(payload, status=200 if result.data is not None else 400)

django_graphql-0.1.0.dist-info/METADATA

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: django-graphql
+Version: 0.1.0
+Summary: SDL-first GraphQL for Django: bind schema types to models with directives and get N+1-aware resolvers.
+Author: nehz
+License-Expression: MIT
+Keywords: django,graphql,sdl,schema-first,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Requires-Dist: graphql-core<3.4,>=3.2
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-django>=4.5; extra == "test"
+Dynamic: license-file
+
+# django-graphql
+
+**SDL-first GraphQL for Django.** Write your API contract in plain GraphQL SDL, bind
+object types to Django models with a `@model` directive, and let `@queryset` / `@get`
+generate resolvers that filter, page and join efficiently. No `DjangoObjectType`
+classes, no Python mirror of your schema: the `.graphql` text *is* the schema.
+
+Because the SDL and the models are separate sources of truth, django-graphql ships a
+**drift checker** that reports any SDL field or filter argument your models no longer
+back, and can plug it into `manage.py check`.
+
+## Features
+
+- **Schema-first**: build an executable schema from an SDL string with `Schema(sdl)`.
+- **Model binding**: `type Book @model(name: "library.Book")` maps a type to a model;
+  fields resolve by attribute, with automatic `camelCase` to `snake_case` fallback
+  (`publishedYear` reads `published_year`). Properties and methods work too.
+- **Generated resolvers**:
+  - `@queryset` on a list field: every argument becomes an ORM lookup
+    (`title__icontains`, `publishedYear__gte`, `author__name`). `limit`, `offset` and
+    `orderBy` are reserved for paging and ordering. Null arguments are ignored.
+  - `@get` on a single-object field: arguments become a `.get()` lookup. Returns
+    `null` when nothing matches.
+- **N+1 avoidance**: the selection set is inspected, then forward FKs and one-to-ones
+  are `select_related` while reverse FKs and many-to-many are `prefetch_related`
+  (one level deep, fragments included).
+- **Safe paging**: `max_limit` caps every `@queryset` result (default 100).
+- **Custom resolvers**: register them with `@schema.resolver("Type.field")`.
+- **Drift checks**: `schema.check()` returns a list of `SchemaIssue`s, and
+  `register_django_check(schema)` reports them through Django's system checks.
+- **Plain Django view**: GET and POST, JSON or form-encoded, CSRF-exempt.
+  Mutations over GET are refused, and `info.context` is the `HttpRequest`.
+
+## Install
+
+```bash
+pip install django-graphql
+```
+
+Requires Python 3.10+, Django 4.2+ and graphql-core 3.2/3.3. Adding the package to
+`INSTALLED_APPS` is not required.
+
+## Quickstart
+
+```python
+# library/models.py
+from django.db import models
+
+class Author(models.Model):
+    name = models.CharField(max_length=100)
+
+class Book(models.Model):
+    title = models.CharField(max_length=200)
+    published_year = models.IntegerField()
+    author = models.ForeignKey(Author, related_name="books", on_delete=models.CASCADE)
+```
+
+```python
+# library/schema.py
+from django_graphql import Schema, register_django_check
+
+schema = Schema("""
+type Author @model(name: "library.Author") {
+  id: ID!
+  name: String!
+  books: [Book!]!
+}
+
+type Book @model(name: "library.Book") {
+  id: ID!
+  title: String!
+  publishedYear: Int!
+  author: Author!
+}
+
+type Query {
+  books(title__icontains: String, publishedYear__gte: Int,
+        limit: Int, offset: Int, orderBy: [String!]): [Book!]! @queryset
+  book(id: ID!): Book @get
+  me: String
+}
+
+type Mutation {
+  renameAuthor(id: ID!, name: String!): Author
+}
+""", max_limit=50)
+
+@schema.resolver("Query.me")
+def resolve_me(root, info):
+    return info.context.user.get_username()   # info.context is the HttpRequest
+
+@schema.resolver("Mutation.renameAuthor")
+def rename_author(root, info, id, name):
+    from library.models import Author
+    author = Author.objects.get(pk=id)
+    author.name = name
+    author.save()
+    return author
+
+register_django_check(schema)   # `manage.py check` now reports SDL/model drift
+```
+
+```python
+# urls.py
+from django.urls import path
+from library.schema import schema
+
+urlpatterns = [path("graphql/", schema.as_view())]
+```
+
+```graphql
+{
+  books(publishedYear__gte: 1970, orderBy: ["-publishedYear"], limit: 10) {
+    title
+    author { name }      # select_related("author"): one SQL query total
+  }
+}
+```
+
+You can also execute without HTTP:
+
+```python
+result = schema.execute("query($id: ID!) { book(id: $id) { title } }", {"id": "1"})
+result.data, result.errors
+```
+
+## API overview
+
+All names below are importable from `django_graphql`.
+
+### SDL directives (definitions are injected automatically)
+
+| Directive | Location | Meaning |
+|---|---|---|
+| `@model(name: String!)` | object type | Bind the type to the model `"app_label.ModelName"`. |
+| `@queryset` | field | Return type must be a list of a `@model` type. Non-reserved arguments become `QuerySet.filter(**lookups)` (names converted to snake_case). Reserved: `limit`, `offset`, `orderBy` (`[String!]`, `-` prefix for descending). |
+| `@get` | field | Return type must be a single `@model` type. All arguments become a `.get()` lookup. Returns `null` on no match and an error if several rows match. |
+
+### `Schema(sdl, *, resolvers=None, max_limit=100)`
+
+Builds the executable schema. Raises `SchemaError` for an unknown model, a misplaced
+directive (`@queryset` on a non-list, `@get` on a list, either on a non-`@model`
+type, or both on one field) or an unknown resolver path.
+
+- `resolvers`: optional `{"Type.field": callable}` mapping, the same as applying `resolver()` to each.
+- `max_limit`: cap (and default) for `limit` on every `@queryset` field. `None` means no cap.
+
+Attributes:
+
+- `sdl: str`: the SDL you passed in.
+- `max_limit: int | None`
+- `graphql_schema: graphql.GraphQLSchema`: the underlying graphql-core schema.
+- `models: dict[str, type[Model]]`: type name to bound model.
+- `bound_fields: dict[str, tuple[type[Model], "queryset" | "get"]]`: `"Type.field"` to its generated binding.
+- `custom_resolvers: dict[str, Callable]`: `"Type.field"` to the registered resolver.
+
+Methods:
+
+- `resolver(path: str)`: decorator registering `func(source, info, **args)` for
+  `"Type.field"`. It replaces a generated resolver, evaluates returned querysets and
+  managers to lists, and returns the original function.
+- `execute(query, variables=None, *, operation_name=None, context=None, root=None) -> graphql.ExecutionResult`:
+  runs the query synchronously.
+- `check() -> list[SchemaIssue]`: reports drift (see below).
+- `as_view(**initkwargs)`: a CSRF-exempt Django view (`GraphQLView`) for this schema.
+
+### `SchemaError(Exception)`
+
+Raised when the SDL cannot be bound to Django models.
+
+### `SchemaIssue(path: str, message: str)`
+
+A frozen dataclass. `path` is `"Type.field"` or `"Type.field(arg)"`, and
+`str(issue)` gives `"path: message"`. `schema.check()` reports:
+
+- a field on a `@model` type that is not a model field, reverse accessor, property
+  or method (camelCase is also tried as snake_case). Fields with a custom resolver
+  are skipped.
+- a `@queryset` / `@get` argument whose first lookup segment (`publisher` in
+  `publisher__name`) is not a model field or `pk`.
+
+### `register_django_check(schema, *, check_id="django_graphql.E001")`
+
+Registers a system check (tag `django_graphql`) that turns each `SchemaIssue` into a
+`checks.Error` with `obj=issue.path`.
+
+### `GraphQLView`
+
+A Django `View` with a class attribute `schema`. Usually you create it with
+`schema.as_view()`, or `GraphQLView.as_view(schema=schema)`.
+
+- `POST` accepts `application/json` `{"query", "variables", "operationName"}` or
+  form fields with the same names (`variables` as a JSON string).
+- `GET` accepts `?query=&variables=&operationName=`, for queries only. A mutation gets
+  `405` with `Allow: POST`.
+- The response is `{"data": ..., "errors": [...]}`. A malformed request, a syntax
+  error or a validation error returns `400`. An execution error returns `200` with
+  partial data, or `400` if `data` is entirely `null`.
+- `info.context` is the `HttpRequest`.
+
+### `default_field_resolver(source, info, **args)`
+
+The resolver used for every field without a generated or custom resolver. It reads
+`source.<name>` or `source.<snake_name>` (or the dict keys of the same names),
+calls callables with the field arguments, and evaluates managers and querysets to
+lists.
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[test]"
+.venv/bin/python -m pytest
+```
+
+The tests configure Django in `tests/conftest.py` (in-memory SQLite, no settings module).
+
+## License
+
+MIT

django_graphql-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+django_graphql/__init__.py,sha256=12eyG9TMJfvM6NbnDbmpbs3Wsa5pe7W74VR3aQFJ6_E,526
+django_graphql/checks.py,sha256=OOJsQEl6dW_zzdVvKRsz_5OVaKkUlJkD2qTyntkOs2A,3608
+django_graphql/directives.py,sha256=QNhSV7ddLwNTJlA1Il-hHw0NgQf67bd-1QLtL5rsEuE,1872
+django_graphql/naming.py,sha256=fhiz15Ai37_Uwkz1ZSj16Kj5pZc3T3VZETbLHjTrDb4,464
+django_graphql/optimizer.py,sha256=7L_neo-mvobAfENhoTv5uymH_pA2b6TzRP4ZrB6w9PM,3609
+django_graphql/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_graphql/resolvers.py,sha256=rn8G_MWVZdrXjM3ycyiy37aB94ZwlfSz2YrMw6ihXIg,4481
+django_graphql/schema.py,sha256=qAsNuXHFXemHzr9Qio6EGzVJOuBOW0wPfPk9mX8WXWU,7499
+django_graphql/views.py,sha256=boWC-MpHh62zDuslU8fbj0az1P-iDpUwrjfBxfNqTog,4873
+django_graphql-0.1.0.dist-info/licenses/LICENSE,sha256=pAfYREEW9GAy7cnK20OXjDn7ofJahYny9GCuIZQTDAA,1061
+django_graphql-0.1.0.dist-info/METADATA,sha256=4NJo-dsJRIzQTJh1BzqSWlPIQ78YWt32hmVo0gebCvM,9448
+django_graphql-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+django_graphql-0.1.0.dist-info/top_level.txt,sha256=DEt-rZk23o8WotPE9wEQozOI-BiOrjSQRlDAPZlhLGo,15
+django_graphql-0.1.0.dist-info/RECORD,,

django_graphql-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_graphql-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nehz
+
+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.

django_graphql-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+django_graphql