Generic services

The generic services provided by gRPC framework allow you to quickly build gRPC services that map closely to your database models. If the generic services don’t suit your needs, use the regular Service class, or reuse the mixins and base classes used by the generic services to compose your own set of ressable generic services.

For example:

from blog.models import Post
from blog.serializers import PostProtoSerializer
from django_grpc_framework import generics


class PostService(generics.ModelService):
   queryset = Post.objects.all()
   serializer_class = PostProtoSerializer

GenericService

This class extends Service class, adding commonly required behavior for standard list and detail services. All concrete generic services is built by composing GenericService, with one or more mixin classes.

Attributes

Basic settings:

The following attributes control the basic service behavior:

• queryset - The queryset that should be used for returning objects from this service. You must set this or override the get_queryset method, you should call get_queryset instead of accessing this property directly, as queryset will get evaluated once, and those results will be cached for all subsequent requests.
• serializer_class - The serializer class that should be used for validating and deserializing input, and for serializing output. You must either set this attribute, or override the get_serializer_class() method.
• lookup_field - The model field that should be used to for performing object lookup of individual model instances. Defaults to primary key field name.
• lookup_request_field - The request field that should be used for object lookup. If unset this defaults to using the same value as lookup_field.

Methods

class django_grpc_framework.generics.GenericService(**kwargs)

Base class for all other generic services.

filter_queryset(queryset)

Given a queryset, filter it, returning a new queryset.

get_object()

Returns an object instance that should be used for detail services. Defaults to using the lookup_field parameter to filter the base queryset.

get_queryset()

Get the list of items for this service. This must be an iterable, and may be a queryset. Defaults to using self.queryset.

If you are overriding a handler method, it is important that you call get_queryset() instead of accessing the queryset attribute as queryset will get evaluated only once.

Override this to provide dynamic behavior, for example:

def get_queryset(self):
    if self.action == 'ListSpecialUser':
        return SpecialUser.objects.all()
    return super().get_queryset()

get_serializer(*args, **kwargs)

Return the serializer instance that should be used for validating and deserializing input, and for serializing output.

get_serializer_class()

Return the class to use for the serializer. Defaults to using self.serializer_class.

get_serializer_context()

Extra context provided to the serializer class. Defaults to including grpc_request, grpc_context, and service keys.

Mixins

The mixin classes provide the actions that are used to privide the basic service behavior. The mixin classes can be imported from django_grpc_framework.mixins.

class django_grpc_framework.mixins.ListModelMixin

List(request, context)

List a queryset. This sends a sequence of messages of serializer.Meta.proto_class to the client.

Note

This is a server streaming RPC.

class django_grpc_framework.mixins.CreateModelMixin

Create(request, context)

Create a model instance.

The request should be a proto message of serializer.Meta.proto_class. If an object is created this returns a proto message of serializer.Meta.proto_class.

perform_create(serializer)

Save a new object instance.

class django_grpc_framework.mixins.RetrieveModelMixin

Retrieve(request, context)

Retrieve a model instance.

The request have to include a field corresponding to lookup_request_field. If an object can be retrieved this returns a proto message of serializer.Meta.proto_class.

class django_grpc_framework.mixins.UpdateModelMixin

Update(request, context)

Update a model instance.

The request should be a proto message of serializer.Meta.proto_class. If an object is updated this returns a proto message of serializer.Meta.proto_class.

perform_update(serializer)

Save an existing object instance.

class django_grpc_framework.mixins.DestroyModelMixin

Destroy(request, context)

Destroy a model instance.

The request have to include a field corresponding to lookup_request_field. If an object is deleted this returns a proto message of google.protobuf.empty_pb2.Empty.

perform_destroy(instance)

Delete an object instance.

Concrete service classes

The following classes are the concrete generic services. They can be imported from django_grpc_framework.generics.

class django_grpc_framework.generics.CreateService(**kwargs)

Concrete service for creating a model instance that provides a Create() handler.

class django_grpc_framework.generics.ListService(**kwargs)

Concrete service for listing a queryset that provides a List() handler.

class django_grpc_framework.generics.RetrieveService(**kwargs)

Concrete service for retrieving a model instance that provides a Retrieve() handler.

class django_grpc_framework.generics.DestroyService(**kwargs)

Concrete service for deleting a model instance that provides a Destroy() handler.

class django_grpc_framework.generics.UpdateService(**kwargs)

Concrete service for updating a model instance that provides a Update() handler.

class django_grpc_framework.generics.ReadOnlyModelService(**kwargs)

Concrete service that provides default List() and Retrieve() handlers.

class django_grpc_framework.generics.ModelService(**kwargs)

Concrete service that provides default Create(), Retrieve(), Update(), Destroy() and List() handlers.

You may need to provide custom classes that have certain actions, to create a base class that provides List() and Create() handlers, inherit from GenericService and mixin the required handlers:

from django_grpc_framework import mixins
from django_grpc_framework import generics

class ListCreateService(mixins.CreateModelMixin,
                        mixins.ListModelMixin,
                        GenericService):
    """
    Concrete service that provides ``Create()`` and ``List()`` handlers.
    """
    pass