Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit e77a585

Browse files
fengspfengsp
committed
Added docs for ProtoSerializer.
1 parent 850172b commit e77a585

File tree

14 files changed

+125
-29
lines changed

14 files changed

+125
-29
lines changed

‎README.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,12 +73,12 @@ Now edit the ``demo/urls.py`` module:
7373
.. code-block:: python
7474
7575
from django.contrib.auth.models import User
76-
from django_grpc_framework import generics, serializers
76+
from django_grpc_framework import generics, proto_serializers
7777
import demo_pb2
7878
import demo_pb2_grpc
7979
8080
81-
class UserProtoSerializer(serializers.ModelProtoSerializer):
81+
class UserProtoSerializer(proto_serializers.ModelProtoSerializer):
8282
class Meta:
8383
model = User
8484
proto_class = demo_pb2.User

‎TODO‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
TODO
22
====
33

4-
- add docs for serializer
54
- relationships
65
- error handling
76
- add BulkCreate\BulkDestroy\BulkUpdate with stream-unary mode ?

‎django_grpc_framework/serializers.py‎ renamed to ‎django_grpc_framework/proto_serializers.py‎

File renamed without changes.

‎docs/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ instructions for building services.
1919
tutorial/index
2020
services
2121
generics
22-
serializers
22+
proto_serializers
2323
protos
2424
server
2525
testing

‎docs/patterns/null_support.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,13 +52,13 @@ The client example::
5252
The service implementation::
5353

5454
from django_grpc_framework import generics, mixins
55-
from django_grpc_framework import serializers
55+
from django_grpc_framework import proto_serializers
5656
from snippets.models import Snippet
5757
import snippets_pb2
5858
from google.protobuf.struct_pb2 import NullValue
5959

6060

61-
class SnippetProtoSerializer(serializers.ModelProtoSerializer):
61+
class SnippetProtoSerializer(proto_serializers.ModelProtoSerializer):
6262
class Meta:
6363
model = Snippet
6464
fields = '__all__'

‎docs/proto_serializers.rst‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
.. _proto_serializers:
2+
3+
Proto Serializers
4+
=================
5+
6+
The serializers work almost exactly the same with REST framework's ``Serializer``
7+
class and ``ModelSerializer``, but use ``message`` instead of ``data`` as
8+
input and output.
9+
10+
11+
Declaring serializers
12+
---------------------
13+
14+
Declaring a serializer looks very similar to declaring a rest framework
15+
serializer::
16+
17+
from rest_framework import serializers
18+
from django_grpc_framework import proto_serializers
19+
20+
class PersonProtoSerializer(proto_serializers.ProtoSerializer):
21+
name = serializers.CharField(max_length=100)
22+
email = serializers.EmailField(max_length=100)
23+
24+
class Meta:
25+
proto_class = hrm_pb2.Person
26+
27+
28+
Overriding serialization and deserialization behavior
29+
-----------------------------------------------------
30+
31+
A proto serializer is the same as one rest framework serializer, but we are
32+
adding the following logic:
33+
34+
- Protobuf message -> Dict of python primitive datatypes.
35+
- Protobuf message <- Dict of python primitive datatypes.
36+
37+
If you need to alter the convert behavior of a serializer class, you can do so
38+
by overriding the ``.message_to_data()`` or ``.data_to_message`` methods.
39+
40+
Here is the default implementation::
41+
42+
from google.protobuf.json_format import MessageToDict, ParseDict
43+
44+
class ProtoSerializer(BaseProtoSerializer, Serializer):
45+
def message_to_data(self, message):
46+
"""Protobuf message -> Dict of python primitive datatypes.
47+
"""
48+
return MessageToDict(
49+
message, including_default_value_fields=True,
50+
preserving_proto_field_name=True
51+
)
52+
53+
def data_to_message(self, data):
54+
"""Protobuf message <- Dict of python primitive datatypes."""
55+
return ParseDict(
56+
data, self.Meta.proto_class(),
57+
ignore_unknown_fields=True
58+
)
59+
60+
The default behavior requires you to provide ``ProtoSerializer.Meta.proto_class``,
61+
it is the protobuf class that should be used for create output proto message
62+
object. You must either set this attribute, or override the
63+
``data_to_message()`` method.
64+
65+
66+
Serializing objects
67+
-------------------
68+
69+
We can now use ``PersonProtoSerializer`` to serialize a person object::
70+
71+
>>> serializer = PersonProtoSerializer(person)
72+
>>> serializer.message
73+
name: "amy"
74+
email: "[email protected]"
75+
>>> type(serializer.message)
76+
<class 'hrm_pb2.Person'>
77+
78+
79+
Deserializing objects
80+
---------------------
81+
82+
Deserialization is similar::
83+
84+
>>> serializer = PersonProtoSerializer(message=message)
85+
>>> serializer.is_valid()
86+
True
87+
>>> serializer.validated_data
88+
OrderedDict([('name', 'amy'), ('email', '[email protected]')])
89+
90+
91+
ModelProtoSerializer
92+
--------------------
93+
94+
This is the same as a rest framework ``ModelSerializer``::
95+
96+
from django_grpc_framework import proto_serializers
97+
from hrm.models import Person
98+
import hrm_pb2
99+
100+
101+
class PersonProtoSerializer(proto_serializers.ModelProtoSerializer):
102+
class Meta:
103+
model = Person
104+
proto_class = hrm_pb2.Person
105+
fields = '__all__'

‎docs/quickstart.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,11 +96,11 @@ Then we're going to define a serializer, let's create a new module named
9696
``account/serializers.py``::
9797

9898
from django.contrib.auth.models import User
99-
from django_grpc_framework import serializers
99+
from django_grpc_framework import proto_serializers
100100
import account_pb2
101101

102102

103-
class UserProtoSerializer(serializers.ModelProtoSerializer):
103+
class UserProtoSerializer(proto_serializers.ModelProtoSerializer):
104104
class Meta:
105105
model = User
106106
proto_class = account_pb2.User

‎docs/serializers.rst‎

Lines changed: 0 additions & 8 deletions
This file was deleted.

‎docs/tutorial/building_services.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -125,12 +125,12 @@ and deserializing the post instances into protocol buffer messages. We can
125125
do this by declaring serializers, create a file in the ``blog`` directory
126126
named ``serializers.py`` and add the following::
127127

128-
from django_grpc_framework import serializers
128+
from django_grpc_framework import proto_serializerss
129129
from blog.models import Post
130130
from blog_proto import post_pb2
131131

132132

133-
class PostProtoSerializer(serializers.ModelProtoSerializer):
133+
class PostProtoSerializer(proto_serializers.ModelProtoSerializer):
134134
class Meta:
135135
model = Post
136136
proto_class = post_pb2.Post

‎examples/demo/demo/urls.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
from django.contrib.auth.models import User
2-
from django_grpc_framework import generics, serializers
2+
from django_grpc_framework import generics, proto_serializers
33
import demo_pb2
44
import demo_pb2_grpc
55

66

7-
class UserProtoSerializer(serializers.ModelProtoSerializer):
7+
class UserProtoSerializer(proto_serializers.ModelProtoSerializer):
88
class Meta:
99
model = User
1010
proto_class = demo_pb2.User
@@ -20,4 +20,4 @@ class UserService(generics.ModelService):
2020

2121

2222
def grpc_handlers(server):
23-
demo_pb2_grpc.add_UserControllerServicer_to_server(UserService.as_servicer(), server)
23+
demo_pb2_grpc.add_UserControllerServicer_to_server(UserService.as_servicer(), server)

0 commit comments

Comments
 (0)