encode/django-rest-framework
1
1
Fork 0
mirror of https://github.com/encode/django-rest-framework.git synced 2024-12-04 23:44:07 +03:00
Code Issues Packages Projects Releases Wiki Activity

Docs tweaks

Browse Source
This commit is contained in:
Tom Christie 2012-10-09 17:53:21 +01:00
parent 216e9bfe95
commit 830fce9074
1 changed files with 16 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
api-guide/serializers.html
View File

@ -228,7 +228,7 @@ class CommentSerializer(serializers.Serializer):
assert(red < 256 and green < 256 and blue < 256) assert(red < 256 and green < 256 and blue < 256)
self.red, self.green, self.blue = red, green, blue self.red, self.green, self.blue = red, green, blue
class ColourField(Field): class ColourField(serializers.WritableField):
""" """
Color objects are serialized into "rgb(#, #, #)" notation. Color objects are serialized into "rgb(#, #, #)" notation.
""" """
@ -243,7 +243,7 @@ class ColourField(Field):
</code></pre> </code></pre>
<p>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 <code>.field_to_native()</code> and/or <code>.field_from_native()</code>.</p> <p>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 <code>.field_to_native()</code> and/or <code>.field_from_native()</code>.</p>
<p>As an example, let's create a field that can be used represent the class name of the object being serialized:</p> <p>As an example, let's create a field that can be used represent the class name of the object being serialized:</p>
<pre class="prettyprint lang-py"><code>class ClassNameField(Field): <pre class="prettyprint lang-py"><code>class ClassNameField(serializers.WritableField):
def field_to_native(self, obj, field_name): def field_to_native(self, obj, field_name):
""" """
Serialize the object's class name, not an attribute of the object. Serialize the object's class name, not an attribute of the object.
@ -260,14 +260,14 @@ class ColourField(Field):
<h1 id="modelserializers">ModelSerializers</h1> <h1 id="modelserializers">ModelSerializers</h1>
<p>Often you'll want serializer classes that map closely to model definitions. <p>Often you'll want serializer classes that map closely to model definitions.
The <code>ModelSerializer</code> class lets you automatically create a Serializer class with fields that corrospond to the Model fields.</p> The <code>ModelSerializer</code> class lets you automatically create a Serializer class with fields that corrospond to the Model fields.</p>
<pre class="prettyprint lang-py"><code>class AccountSerializer(ModelSerializer): <pre class="prettyprint lang-py"><code>class AccountSerializer(serializers.ModelSerializer):
class Meta: class Meta:
model = Account model = Account
</code></pre> </code></pre>
<p><strong>[TODO: Explain model field to serializer field mapping in more detail]</strong></p> <p><strong>[TODO: Explain model field to serializer field mapping in more detail]</strong></p>
<h2 id="specifying-fields-explicitly">Specifying fields explicitly</h2> <h2 id="specifying-fields-explicitly">Specifying fields explicitly</h2>
<p>You can add extra fields to a <code>ModelSerializer</code> or override the default fields by declaring fields on the class, just as you would for a <code>Serializer</code> class.</p> <p>You can add extra fields to a <code>ModelSerializer</code> or override the default fields by declaring fields on the class, just as you would for a <code>Serializer</code> class.</p>
<pre class="prettyprint lang-py"><code>class AccountSerializer(ModelSerializer): <pre class="prettyprint lang-py"><code>class AccountSerializer(serializers.ModelSerializer):
url = CharField(source='get_absolute_url', readonly=True) url = CharField(source='get_absolute_url', readonly=True)
group = NaturalKeyField() group = NaturalKeyField()
@ -278,23 +278,21 @@ The <code>ModelSerializer</code> class lets you automatically create a Serialize
<h2 id="relational-fields">Relational fields</h2> <h2 id="relational-fields">Relational fields</h2>
<p>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.</p> <p>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.</p>
<p>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.</p> <p>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.</p>
<p>The <code>PrimaryKeyField</code> and <code>NaturalKeyField</code> fields provide alternative flat representations.</p> <p>The <code>PrimaryKeyRelatedField</code> and <code>HyperlinkedRelatedField</code> fields provide alternative flat representations.</p>
<p>The <code>ModelSerializer</code> class can itself be used as a field, in order to serialize relationships using nested representations.</p> <p>The <code>ModelSerializer</code> class can itself be used as a field, in order to serialize relationships using nested representations.</p>
<p>The <code>RelatedField</code> class may be subclassed to create a custom represenation of a relationship. The subclass should override <code>.to_native()</code>, and optionally <code>.from_native()</code> if deserialization is supported.</p> <p>The <code>RelatedField</code> class may be subclassed to create a custom represenation of a relationship. The subclass should override <code>.to_native()</code>, and optionally <code>.from_native()</code> if deserialization is supported.</p>
<p>All the relational fields may be used for any relationship or reverse relationship on a model.</p> <p>All the relational fields may be used for any relationship or reverse relationship on a model.</p>
<h2 id="specifying-which-fields-should-be-included">Specifying which fields should be included</h2> <h2 id="specifying-which-fields-should-be-included">Specifying which fields should be included</h2>
<p>If you only want a subset of the default fields to be used in a model serializer, you can do so using <code>fields</code> or <code>exclude</code> options, just as you would with a <code>ModelForm</code>.</p> <p>If you only want a subset of the default fields to be used in a model serializer, you can do so using <code>fields</code> or <code>exclude</code> options, just as you would with a <code>ModelForm</code>.</p>
<p>For example:</p> <p>For example:</p>
<pre class="prettyprint lang-py"><code>class AccountSerializer(ModelSerializer): <pre class="prettyprint lang-py"><code>class AccountSerializer(serializers.ModelSerializer):
class Meta: class Meta:
model = Account model = Account
exclude = ('id',) exclude = ('id',)
</code></pre> </code></pre>
<p>The <code>fields</code> and <code>exclude</code> options may also be set by passing them to the <code>serialize()</code> method.</p>
<p><strong>[TODO: Possibly only allow .serialize(fields=…) in FixtureSerializer for backwards compatability, but remove for ModelSerializer]</strong></p>
<h2 id="specifiying-nested-serialization">Specifiying nested serialization</h2> <h2 id="specifiying-nested-serialization">Specifiying nested serialization</h2>
<p>The default <code>ModelSerializer</code> uses primary keys for relationships, but you can also easily generate nested representations using the <code>nested</code> option:</p> <p>The default <code>ModelSerializer</code> uses primary keys for relationships, but you can also easily generate nested representations using the <code>nested</code> option:</p>
<pre class="prettyprint lang-py"><code>class AccountSerializer(ModelSerializer): <pre class="prettyprint lang-py"><code>class AccountSerializer(serializers.ModelSerializer):
class Meta: class Meta:
model = Account model = Account
exclude = ('id',) exclude = ('id',)
@ -302,24 +300,25 @@ The <code>ModelSerializer</code> class lets you automatically create a Serialize
</code></pre> </code></pre>
<p>The <code>nested</code> option may be set to either <code>True</code>, <code>False</code>, 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.</p> <p>The <code>nested</code> option may be set to either <code>True</code>, <code>False</code>, 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.</p>
<p>When serializing objects using a nested representation any occurances of recursion will be recognised, and will fall back to using a flat representation.</p> <p>When serializing objects using a nested representation any occurances of recursion will be recognised, and will fall back to using a flat representation.</p>
<p>The <code>nested</code> option may also be set by passing it to the <code>serialize()</code> method.</p>
<p><strong>[TODO: Possibly only allow .serialize(nested=…) in FixtureSerializer]</strong></p>
<h2 id="customising-the-default-fields-used-by-a-modelserializer">Customising the default fields used by a ModelSerializer</h2> <h2 id="customising-the-default-fields-used-by-a-modelserializer">Customising the default fields used by a ModelSerializer</h2>
<pre class="prettyprint lang-py"><code>class AccountSerializer(ModelSerializer): <pre class="prettyprint lang-py"><code>class AccountSerializer(serializers.ModelSerializer):
class Meta: class Meta:
model = Account model = Account
def get_pk_field(self, model_field): def get_pk_field(self, model_field):
return Field(readonly=True) return serializers.Field(readonly=True)
def get_nested_field(self, model_field): def get_nested_field(self, model_field):
return ModelSerializer() return serializers.ModelSerializer()
def get_related_field(self, model_field): def get_related_field(self, model_field, to_many=False):
return NaturalKeyField() 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): def get_field(self, model_field):
return Field() return serializers.ModelField(model_field=model_field)
</code></pre> </code></pre>
</div><!--/span--> </div><!--/span-->
</div><!--/row--> </div><!--/row-->