Quickstart¶
We’re going to create a simple service to allow clients to retrieve and edit the users in the system.
Project setup¶
Create a new Django project named quickstart
, then start a new app called
account
:
# Create a virtual environment
python3 -m venv env
source env/bin/activate
# Install Django and Django gRPC framework
pip install django
pip install djangorestframework
pip install djangogrpcframework
pip install grpcio
pip install grpcio-tools
# Create a new project and a new application
django-admin startproject quickstart
cd quickstart
django-admin startapp account
Now sync the database:
python manage.py migrate
Update settings¶
Add django_grpc_framework
to INSTALLED_APPS
, settings module is in
quickstart/settings.py
:
INSTALLED_APPS = [
...
'django_grpc_framework',
]
Defining protos¶
Our first step is to define the gRPC service and messages, create a file
quickstart/account.proto
next to quickstart/manage.py
:
syntax = "proto3";
package account;
import "google/protobuf/empty.proto";
service UserController {
rpc List(UserListRequest) returns (stream User) {}
rpc Create(User) returns (User) {}
rpc Retrieve(UserRetrieveRequest) returns (User) {}
rpc Update(User) returns (User) {}
rpc Destroy(User) returns (google.protobuf.Empty) {}
}
message User {
int32 id = 1;
string username = 2;
string email = 3;
repeated int32 groups = 4;
}
message UserListRequest {
}
message UserRetrieveRequest {
int32 id = 1;
}
Or you can generate it automatically based on User
model:
python manage.py generateproto --model django.contrib.auth.models.User --fields id,username,email,groups --file account.proto
Next we need to generate gRPC code, from the quickstart
directory, run:
python -m grpc_tools.protoc --proto_path=./ --python_out=./ --grpc_python_out=./ ./account.proto
Writing serializers¶
Then we’re going to define a serializer, let’s create a new module named
account/serializers.py
:
from django.contrib.auth.models import User
from django_grpc_framework import proto_serializers
import account_pb2
class UserProtoSerializer(proto_serializers.ModelProtoSerializer):
class Meta:
model = User
proto_class = account_pb2.User
fields = ['id', 'username', 'email', 'groups']
Writing services¶
Now we’d write some a service, create account/services.py
:
from django.contrib.auth.models import User
from django_grpc_framework import generics
from account.serializers import UserProtoSerializer
class UserService(generics.ModelService):
"""
gRPC service that allows users to be retrieved or updated.
"""
queryset = User.objects.all().order_by('-date_joined')
serializer_class = UserProtoSerializer
Register handlers¶
Ok, let’s wire up the gRPC handlers, edit quickstart/urls.py
:
import account_pb2_grpc
from account.services import UserService
urlpatterns = []
def grpc_handlers(server):
account_pb2_grpc.add_UserControllerServicer_to_server(UserService.as_servicer(), server)
We’re done, the project layout should look like:
.
./quickstart
./quickstart/asgi.py
./quickstart/__init__.py
./quickstart/settings.py
./quickstart/urls.py
./quickstart/wsgi.py
./manage.py
./account
./account/migrations
./account/migrations/__init__.py
./account/services.py
./account/models.py
./account/serializers.py
./account/__init__.py
./account/apps.py
./account/admin.py
./account/tests.py
./account.proto
./account_pb2_grpc.py
./account_pb2.py
Calling our service¶
Fire up the server with development mode:
python manage.py grpcrunserver --dev
We can now access our service from the gRPC client:
import grpc
import account_pb2
import account_pb2_grpc
with grpc.insecure_channel('localhost:50051') as channel:
stub = account_pb2_grpc.UserControllerStub(channel)
for user in stub.List(account_pb2.UserListRequest()):
print(user, end='')