Types API Reference¶

This section provides detailed API documentation for GraphQL type classes in django-graphex.

DjangoObjectType¶

Enhanced Django model GraphQL type with filtering and pagination support.

class DjangoObjectType(ObjectType)

Meta Configuration¶

The DjangoObjectType is configured through a nested Meta class:

class UserType(DjangoObjectType):
    class Meta:
        model = User
        only_fields = ('id', 'username', 'email')
        filter_fields = {'username': ('exact', 'icontains')}

Meta Options¶

Methods¶

resolve_id(info)¶

Resolve the ID field for the object.

Returns: Primary key value of the model instance

is_type_of(root, info) (classmethod)¶

Check if the root object is of this type.

Parameters: - root (Any): Object to check - info (ResolveInfo): GraphQL resolve info

Returns: bool - True if object matches this type

get_queryset(queryset, info) (classmethod)¶

Override to customize the queryset used for this type.

Parameters: - queryset (QuerySet): Base queryset - info (ResolveInfo): GraphQL resolve info

Returns: Modified QuerySet

get_node(info, id) (classmethod)¶

Get a single node by ID.

Parameters: - info (ResolveInfo): GraphQL resolve info - id (Any): Object identifier

Returns: Model instance or None

Example Usage¶

from django_graphex import DjangoObjectType
from .models import User

class UserType(DjangoObjectType):
    class Meta:
        model = User
        description = "User account type"

class UserType(DjangoObjectType):
    class Meta:
        model = User
        filter_fields = {
            'username': ('exact', 'icontains'),
            'email': ('exact', 'icontains'),
            'is_active': ('exact',),
            'date_joined': ('gte', 'lte'),
        }

class UserType(DjangoObjectType):
    class Meta:
        model = User
        only_fields = ('id', 'username', 'email', 'first_name', 'last_name')
        # Alternative: exclude_fields = ('password', 'user_permissions')

class UserType(DjangoObjectType):
    class Meta:
        model = User

    @classmethod
    def get_queryset(cls, queryset, info):
        return queryset.select_related('profile').prefetch_related('posts')

DjangoInputObjectType¶

Django model GraphQL input type for mutations and arguments.

class DjangoInputObjectType(InputObjectType)

Meta Configuration¶

Configure input types through the Meta class:

class UserInput(DjangoInputObjectType):
    class Meta:
        model = User
        input_for = 'create'
        only_fields = ('username', 'email', 'first_name', 'last_name')

Meta Options¶

Methods¶

get_type() (classmethod)¶

Get the type when the unmounted type is mounted.

Returns: The input type class

Example Usage¶

from django_graphex import DjangoInputObjectType

class UserCreateInput(DjangoInputObjectType):
    class Meta:
        model = User
        input_for = 'create'
        only_fields = ('username', 'email', 'first_name', 'last_name', 'password')

class UserUpdateInput(DjangoInputObjectType):
    class Meta:
        model = User
        input_for = 'update'
        exclude_fields = ('password', 'date_joined')

class UserInput(DjangoInputObjectType):
    class Meta:
        model = User
        input_for = 'create'
        # field names to expand as nested input objects
        nested_fields = ('profile', 'addresses')

DjangoListObjectType¶

GraphQL type for paginated lists of Django objects with count and results.

class DjangoListObjectType(ObjectType)

Meta Configuration¶

Configure list types with pagination and filtering:

class UserListType(DjangoListObjectType):
    class Meta:
        model = User
        pagination = LimitOffsetGraphqlPagination(default_limit=25)

Meta Options¶

Generated Fields¶

A DjangoListObjectType automatically generates these fields:

Pagination and ordering arguments (limit, offset, page, pageSize, first, ordering, cursor arguments) are placed on the results(...) subfield. totalCount (and pageInfo, for cursor pagination) are siblings of results. Filter arguments are placed on the list field itself.

Methods¶

ListField(**kwargs) (classmethod)¶

Create a field for this list type.

Parameters: - **kwargs: Additional field arguments

Returns: DjangoListObjectField instance

RetrieveField(**kwargs) (classmethod)¶

Create a field for retrieving a single object from this list type.

Parameters: - **kwargs: Additional field arguments

Returns: DjangoObjectField instance

BaseType() (classmethod)¶

Return the base DjangoObjectType wrapped by this list type.

Returns: The base object type class

Example Usage¶

from django_graphex import (
    DjangoListObjectType,
    LimitOffsetGraphqlPagination
)

class UserListType(DjangoListObjectType):
    class Meta:
        model = User
        description = "Paginated list of users"
        pagination = LimitOffsetGraphqlPagination(default_limit=20)

from django_graphex import PageGraphqlPagination

class PostListType(DjangoListObjectType):
    class Meta:
        model = Post
        pagination = PageGraphqlPagination(
            page_size=15,
            page_size_query_param='pageSize'
        )
        filter_fields = {
            'title': ('icontains',),
            'status': ('exact',),
            'author__username': ('icontains',),
        }

import graphene
from django_graphex import DjangoListObjectField

class UserListType(DjangoListObjectType):
    class Meta:
        model = User
        pagination = LimitOffsetGraphqlPagination(default_limit=25)

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

    def resolve_active_users(self, info, **kwargs):
        # A `resolve_<field>` returning a QuerySet is honored by
        # `queryset_factory`, scoping the list's base queryset.
        return User.objects.filter(is_active=True).select_related('profile')

import graphene
from django_graphex import DjangoListObjectField

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

    # Or use the shorthand method
    users = UserListType.ListField()
    user = UserListType.RetrieveField()

schema = graphene.Schema(query=Query)

GraphQL Response Structure¶

{
  "data": {
    "allUsers": {
      "totalCount": 150,
      "results": [
        {
          "id": "1",
          "username": "john_doe",
          "email": "john@example.com"
        },
        {
          "id": "2",
          "username": "jane_smith",
          "email": "jane@example.com"
        }
      ]
    }
  }
}

DjangoModelType¶

GraphQL type with automatic CRUD operations driven directly by a Django model.

class DjangoModelType(ObjectType)

Meta Configuration¶

Configure model types with automatic CRUD operations:

class UserType(DjangoModelType):
    class Meta:
        model = User
        pagination = LimitOffsetGraphqlPagination(default_limit=25)

Meta Options¶

Generated Methods¶

QueryFields(**kwargs) (classmethod)¶

Generate both single object and list query fields.

Returns: Tuple of (single_field, list_field)

ListField(**kwargs) (classmethod)¶

Create a list field for this model type.

Returns: DjangoListObjectField instance

RetrieveField(**kwargs) (classmethod)¶

Create a retrieve field for single objects.

Returns: DjangoObjectField instance

MutationFields(**kwargs) (classmethod)¶

Generate the create, delete and update mutation fields.

Returns: Tuple of (create_field, delete_field, update_field)

CreateField(**kwargs) / DeleteField(**kwargs) / UpdateField(**kwargs) (classmethod)¶

Create the individual mutation fields wired to the create, delete and update resolvers respectively.

Returns: Field instance

Override Hooks¶

DjangoModelType exposes hooks you can override on your subclass to scope querysets and enforce authorization across all CRUD operations:

get_queryset(manager, info, **kwargs) (classmethod)¶

Return the base queryset for retrieve, list and mutation responses. The default uses Meta.queryset (falling back to the model's default manager) and applies filter_queryset. Override to add select_related/annotate, etc.

filter_queryset(qs, info, **kwargs) (classmethod)¶

Per-request scoping hook. The default returns qs unchanged.

authorize(info, action, **kwargs) (classmethod)¶

Authorization hook called by every CRUD method before it runs. The default delegates to check_permissions using the configured permission_classes, raising GraphQLError when denied. Override to customize.

permission_classes (class attribute)¶

Tuple of permission classes checked per action. Empty (the default) means no checks. See django_graphex.permissions.

Example Usage¶

from django_graphex import DjangoModelType
from .models import User

class UserType(DjangoModelType):
    class Meta:
        model = User
        description = "User type"

class UserType(DjangoModelType):
    class Meta:
        model = User
        pagination = LimitOffsetGraphqlPagination(default_limit=30)
        filter_fields = {
            'username': ('exact', 'icontains'),
            'email': ('exact', 'icontains'),
            'is_active': ('exact',),
        }

import graphene

class Query(graphene.ObjectType):
    # Generate both fields automatically
    user, users = UserType.QueryFields()

    # Or create individual fields
    user_list = UserType.ListField()
    single_user = UserType.RetrieveField()

schema = graphene.Schema(query=Query)

Type Registration¶

All types are automatically registered in a global registry for reuse and relationship resolution.

Registry Operations¶

from django_graphex.registry import get_global_registry

# Get the global registry
registry = get_global_registry()

# Check if a type is registered
user_type = registry.get_type_for_model(User)

# Register a type manually
registry.register(CustomUserType)

Custom Registry¶

from django_graphex import Registry

# Create custom registry
custom_registry = Registry()

class UserType(DjangoObjectType):
    class Meta:
        model = User
        registry = custom_registry

Advanced Usage¶

Custom Field Resolvers¶

import graphene

class UserType(DjangoObjectType):
    full_name = graphene.String()
    post_count = graphene.Int()

    class Meta:
        model = User

    def resolve_full_name(self, info):
        return f"{self.first_name} {self.last_name}"

    def resolve_post_count(self, info):
        return self.posts.count()

Dynamic Field Generation¶

class UserType(DjangoObjectType):
    class Meta:
        model = User

    @classmethod
    def __init_subclass_with_meta__(cls, **options):
        # Add dynamic fields before calling super
        cls.custom_field = graphene.String()
        super().__init_subclass_with_meta__(**options)

Performance Optimization¶

class UserType(DjangoObjectType):
    class Meta:
        model = User
        filter_fields = {
            'username': ('exact', 'icontains'),
            'email': ('exact',),
        }

    @classmethod
    def get_queryset(cls, queryset, info):
        # Optimize queries with select_related and prefetch_related
        return queryset.select_related(
            'profile'
        ).prefetch_related(
            'posts',
            'posts__comments'
        )

Error Handling¶

Type Validation¶

class UserType(DjangoObjectType):
    class Meta:
        model = User

    @classmethod
    def is_type_of(cls, root, info):
        # Custom type checking logic
        if hasattr(root, 'user_type'):
            return root.user_type == 'standard'
        return super().is_type_of(root, info)

Field Resolution Errors¶

class UserType(DjangoObjectType):
    avatar_url = graphene.String()

    class Meta:
        model = User

    def resolve_avatar_url(self, info):
        try:
            if self.profile and self.profile.avatar:
                return self.profile.avatar.url
            return None
        except AttributeError:
            return None

Best Practices¶

Security Considerations¶

class UserType(DjangoObjectType):
    class Meta:
        model = User
        # Don't expose sensitive fields
        exclude_fields = (
            'password', 'user_permissions',
            'groups', 'is_superuser'
        )

    @classmethod
    def get_queryset(cls, queryset, info):
        # Apply security filters
        if not info.context.user.is_staff:
            return queryset.filter(is_active=True)
        return queryset

This comprehensive API reference covers all type classes in django-graphex, providing developers with the knowledge needed to effectively create and customize GraphQL types for their Django applications.