From c45fe115b872dd4fce24e930fcf6386894786dc9 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 14 Jan 2014 11:28:20 +0000 Subject: [PATCH] Docs update for version 2.3.11 --- api-guide/fields.html | 9 ++++++--- api-guide/serializers.html | 24 +++++++++++++++++++++--- topics/release-notes.html | 5 ++++- 3 files changed, 31 insertions(+), 7 deletions(-) diff --git a/api-guide/fields.html b/api-guide/fields.html index c9a61c214..2a8dd3cbc 100644 --- a/api-guide/fields.html +++ b/api-guide/fields.html @@ -222,7 +222,10 @@

The value source='*' has a special meaning, and is used to indicate that the entire object should be passed through to the field. This can be useful for creating nested representations. (See the implementation of the PaginationSerializer class for an example.)

Defaults to the name of the field.

read_only

-

Set this to True to ensure that the field is used when serializing a representation, but is not used when updating an instance during deserialization.

+

Set this to True to ensure that the field is used when serializing a representation, but is not used when creating or updating an instance during deserialization.

+

Defaults to False

+

write_only

+

Set this to True to ensure that the field may be used when updating or creating an instance, but is not included when serializing the representation.

Defaults to False

required

Normally an error will be raised if a field is not supplied during deserialization. @@ -313,10 +316,10 @@ or django.db.models.fields.TextField.

Signature: CharField(max_length=None, min_length=None)

URLField

Corresponds to django.db.models.fields.URLField. Uses Django's django.core.validators.URLValidator for validation.

-

Signature: CharField(max_length=200, min_length=None)

+

Signature: URLField(max_length=200, min_length=None)

SlugField

Corresponds to django.db.models.fields.SlugField.

-

Signature: CharField(max_length=50, min_length=None)

+

Signature: SlugField(max_length=50, min_length=None)

ChoiceField

A field that can accept a value out of a limited set of choices.

EmailField

diff --git a/api-guide/serializers.html b/api-guide/serializers.html index a2794bd68..898b6ea4a 100644 --- a/api-guide/serializers.html +++ b/api-guide/serializers.html @@ -181,6 +181,7 @@
  • Specifying which fields should be included
  • Specifying nested serialization
  • Specifying which fields should be read-only
    • +
  • Specifying which fields should be write-only
  • Specifying fields explicitly
  • Relational fields
  • HyperlinkedModelSerializer
    • @@ -284,10 +285,10 @@ serializer.object

    When deserializing data, we can either create a new instance, or update an existing instance.

    serializer = CommentSerializer(data=data)           # Create new instance
-serializer = CommentSerializer(comment, data=data)  # Update `instance`
+serializer = CommentSerializer(comment, data=data)  # Update `comment`

    By default, serializers must be passed values for all required fields or they will throw validation errors. You can use the partial argument in order to allow partial updates.

    -
    serializer = CommentSerializer(comment, data={'content': u'foo bar'}, partial=True)  # Update `instance` with partial data
+
    serializer = CommentSerializer(comment, data={'content': u'foo bar'}, partial=True)  # Update `comment` with partial data
 
    
 
    Validation
    
 
    When deserializing data, you always need to call is_valid() before attempting to access the deserialized object.  If any validation errors occur, the .errors property will contain a dictionary representing the resulting error messages.  For example:
    
@@ -368,7 +369,7 @@ class CommentSerializer(serializers.Serializer):
     created = serializers.DateTimeField()

    Validation of nested objects will work the same as before. Errors with nested objects will be nested under the field name of the nested object.

    -
    serializer = CommentSerializer(comment, data={'user': {'email': 'foobar', 'username': 'doe'}, 'content': 'baz'})
+
    serializer = CommentSerializer(data={'user': {'email': 'foobar', 'username': 'doe'}, 'content': 'baz'})
 serializer.is_valid()
 # False
 serializer.errors
@@ -494,6 +495,23 @@ The ModelSerializer class lets you automatically create a Serialize
         read_only_fields = ('account_name',)
 
    
 
    Model fields which have editable=False set, and AutoField fields will be set to read-only by default, and do not need to be added to the read_only_fields option. 
    
+
    Specifying which fields should be write-only
    
+
    You may wish to specify multiple fields as write-only.  Instead of adding each field explicitly with the write_only=True attribute, you may use the write_only_fields Meta option, like so:
    
+
    class CreateUserSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = User
+        fields = ('email', 'username', 'password')
+        write_only_fields = ('password',)  # Note: Password field is write-only
+
+def restore_object(self, attrs, instance=None):
+    """
+    Instantiate a new User instance.
+    """
+    assert instance is None, 'Cannot update users with CreateUserSerializer'                                
+    user = User(email=attrs['email'], username=attrs['username'])
+    user.set_password(attrs['password'])
+    return user
+
    
 
    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(serializers.ModelSerializer):
diff --git a/topics/release-notes.html b/topics/release-notes.html
index b0d98f731..e6797a764 100644
--- a/topics/release-notes.html
+++ b/topics/release-notes.html
@@ -225,8 +225,11 @@
 
    
 
    
 
    2.3.x series
    
-
    Master
    
+
    2.3.11
    
+
    Date: 14th January 2014
    
 
      
+
    • Added write_only serializer field argument.
      • 
+
    • Added write_only_fields option to ModelSerializer classes.
      • 
 
    • JSON renderer now deals with objects that implement a dict-like interface.
      • 
 
    • Fix compatiblity with newer versions of django-oauth-plus.
      • 
 
    • Bugfix: Refine behavior that calls model manager all() across nested serializer relationships, preventing erronous behavior with some non-ORM objects, and preventing unneccessary queryset re-evaluations.
      •