From 830fce9074cbeeb6de44149cfce225ce90cc8bf3 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 9 Oct 2012 17:53:21 +0100 Subject: [PATCH] Docs tweaks --- api-guide/serializers.html | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/api-guide/serializers.html b/api-guide/serializers.html index 7ffb47274..6b61965c9 100644 --- a/api-guide/serializers.html +++ b/api-guide/serializers.html @@ -228,7 +228,7 @@ class CommentSerializer(serializers.Serializer): assert(red < 256 and green < 256 and blue < 256) self.red, self.green, self.blue = red, green, blue -class ColourField(Field): +class ColourField(serializers.WritableField): """ Color objects are serialized into "rgb(#, #, #)" notation. """ @@ -243,7 +243,7 @@ class ColourField(Field):

By default field values are treated as mapping to an attribute on the object. If you need to customize how the field value is accessed and set you need to override .field_to_native() and/or .field_from_native().

As an example, let's create a field that can be used represent the class name of the object being serialized:

-
class ClassNameField(Field):
+
class ClassNameField(serializers.WritableField):
     def field_to_native(self, obj, field_name):
         """
         Serialize the object's class name, not an attribute of the object.
@@ -260,14 +260,14 @@ class ColourField(Field):
 
ModelSerializers

 
Often you'll want serializer classes that map closely to model definitions.
 The ModelSerializer class lets you automatically create a Serializer class with fields that corrospond to the Model fields.

-
class AccountSerializer(ModelSerializer):
+
class AccountSerializer(serializers.ModelSerializer):
     class Meta:
         model = Account
 

 
[TODO: Explain model field to serializer field mapping in more detail]

 
Specifying fields explicitly

 
You can add extra fields to a ModelSerializer or override the default fields by declaring fields on the class, just as you would for a Serializer class.

-
class AccountSerializer(ModelSerializer):
+
class AccountSerializer(serializers.ModelSerializer):
     url = CharField(source='get_absolute_url', readonly=True)
     group = NaturalKeyField()
 
@@ -278,23 +278,21 @@ The ModelSerializer class lets you automatically create a Serialize
 
Relational fields

 
When serializing model instances, there are a number of different ways you might choose to represent relationships.  The default representation is to use the primary keys of the related instances.

 
Alternative representations include serializing using natural keys, serializing complete nested representations, or serializing using a custom representation, such as a URL that uniquely identifies the model instances.

-
The PrimaryKeyField and NaturalKeyField fields provide alternative flat representations.

+
The PrimaryKeyRelatedField and HyperlinkedRelatedField fields provide alternative flat representations.

 
The ModelSerializer class can itself be used as a field, in order to serialize relationships using nested representations.

 
The RelatedField class may be subclassed to create a custom represenation of a relationship.  The subclass should override .to_native(), and optionally .from_native() if deserialization is supported.

 
All the relational fields may be used for any relationship or reverse relationship on a model.

 
Specifying which fields should be included

 
If you only want a subset of the default fields to be used in a model serializer, you can do so using fields or exclude options, just as you would with a ModelForm.

 
For example:

-
class AccountSerializer(ModelSerializer):
+
class AccountSerializer(serializers.ModelSerializer):
     class Meta:
         model = Account
         exclude = ('id',)
 

-
The fields and exclude options may also be set by passing them to the serialize() method.

-
[TODO: Possibly only allow .serialize(fields=…) in FixtureSerializer for backwards compatability, but remove for ModelSerializer]

 
Specifiying nested serialization

 
The default ModelSerializer uses primary keys for relationships, but you can also easily generate nested representations using the nested option:

-
class AccountSerializer(ModelSerializer):
+
class AccountSerializer(serializers.ModelSerializer):
     class Meta:
         model = Account
         exclude = ('id',)
@@ -302,24 +300,25 @@ The ModelSerializer class lets you automatically create a Serialize
 

 
The nested option may be set to either True, False, or an integer value.  If given an integer value it indicates the depth of relationships that should be traversed before reverting to a flat representation.

 
When serializing objects using a nested representation any occurances of recursion will be recognised, and will fall back to using a flat representation.

-
The nested option may also be set by passing it to the serialize() method.

-
[TODO: Possibly only allow .serialize(nested=…) in FixtureSerializer]

 
Customising the default fields used by a ModelSerializer

-
class AccountSerializer(ModelSerializer):
+
class AccountSerializer(serializers.ModelSerializer):
     class Meta:
         model = Account
 
     def get_pk_field(self, model_field):
-        return Field(readonly=True)
+        return serializers.Field(readonly=True)
 
     def get_nested_field(self, model_field):
-        return ModelSerializer()
+        return serializers.ModelSerializer()
 
-    def get_related_field(self, model_field):
-        return NaturalKeyField()
+    def get_related_field(self, model_field, to_many=False):
+        queryset = model_field.rel.to._default_manager
+        if to_many:
+            return return serializers.ManyRelatedField(queryset=queryset)
+        return serializers.RelatedField(queryset=queryset)
 
     def get_field(self, model_field):
-        return Field()
+        return serializers.ModelField(model_field=model_field)