Docs update for version 2.3.11

api-guide/fields.html

@@ -222,7 +222,10 @@
 <p>The value <code>source='*'</code> 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 <code>PaginationSerializer</code> class for an example.)</p>
 <p>Defaults to the name of the field.</p>
 <h3 id="read_only"><code>read_only</code></h3>
-<p>Set this to <code>True</code> to ensure that the field is used when serializing a representation, but is not used when updating an instance during deserialization.</p>
+<p>Set this to <code>True</code> to ensure that the field is used when serializing a representation, but is not used when creating or updating an instance during deserialization.</p>
+<p>Defaults to <code>False</code></p>
+<h3 id="write_only"><code>write_only</code></h3>
+<p>Set this to <code>True</code> to ensure that the field may be used when updating or creating an instance, but is not included when serializing the representation.</p>
 <p>Defaults to <code>False</code></p>
 <h3 id="required"><code>required</code></h3>
 <p>Normally an error will be raised if a field is not supplied during deserialization.
@@ -313,10 +316,10 @@ or <code>django.db.models.fields.TextField</code>.</p>
 <p><strong>Signature:</strong> <code>CharField(max_length=None, min_length=None)</code></p>
 <h2 id="urlfield">URLField</h2>
 <p>Corresponds to <code>django.db.models.fields.URLField</code>.  Uses Django's <code>django.core.validators.URLValidator</code> for validation.</p>
-<p><strong>Signature:</strong> <code>CharField(max_length=200, min_length=None)</code></p>
+<p><strong>Signature:</strong> <code>URLField(max_length=200, min_length=None)</code></p>
 <h2 id="slugfield">SlugField</h2>
 <p>Corresponds to <code>django.db.models.fields.SlugField</code>.</p>
-<p><strong>Signature:</strong> <code>CharField(max_length=50, min_length=None)</code></p>
+<p><strong>Signature:</strong> <code>SlugField(max_length=50, min_length=None)</code></p>
 <h2 id="choicefield">ChoiceField</h2>
 <p>A field that can accept a value out of a limited set of choices.</p>
 <h2 id="emailfield">EmailField</h2>

api-guide/serializers.html

@@ -181,6 +181,7 @@
 <li><a href="#specifying-which-fields-should-be-included">Specifying which fields should be included</a></li>
 <li><a href="#specifying-nested-serialization">Specifying nested serialization</a></li>
 <li><a href="#specifying-which-fields-should-be-read-only">Specifying which fields should be read-only</a></li>
+<li><a href="#specifying-which-fields-should-be-write-only">Specifying which fields should be write-only</a></li>
 <li><a href="#specifying-fields-explicitly">Specifying fields explicitly</a></li>
 <li><a href="#relational-fields">Relational fields</a></li>
 <li class="main"><a href="#hyperlinkedmodelserializer">HyperlinkedModelSerializer</a></li>
@@ -284,10 +285,10 @@ serializer.object
 </code></pre>
 <p>When deserializing data, we can either create a new instance, or update an existing instance.</p>
 <pre class="prettyprint lang-py"><code>serializer = CommentSerializer(data=data)           # Create new instance
-serializer = CommentSerializer(comment, data=data)  # Update `instance`
+serializer = CommentSerializer(comment, data=data)  # Update `comment`
 </code></pre>
 <p>By default, serializers must be passed values for all required fields or they will throw validation errors.  You can use the <code>partial</code> argument in order to allow partial updates.</p>
-<pre class="prettyprint lang-py"><code>serializer = CommentSerializer(comment, data={'content': u'foo bar'}, partial=True)  # Update `instance` with partial data
+<pre class="prettyprint lang-py"><code>serializer = CommentSerializer(comment, data={'content': u'foo bar'}, partial=True)  # Update `comment` with partial data
 </code></pre>
 <h2 id="validation">Validation</h2>
 <p>When deserializing data, you always need to call <code>is_valid()</code> before attempting to access the deserialized object.  If any validation errors occur, the <code>.errors</code> property will contain a dictionary representing the resulting error messages.  For example:</p>
@@ -368,7 +369,7 @@ class CommentSerializer(serializers.Serializer):
     created = serializers.DateTimeField()
 </code></pre>
 <p>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.</p>
-<pre class="prettyprint lang-py"><code>serializer = CommentSerializer(comment, data={'user': {'email': 'foobar', 'username': 'doe'}, 'content': 'baz'})
+<pre class="prettyprint lang-py"><code>serializer = CommentSerializer(data={'user': {'email': 'foobar', 'username': 'doe'}, 'content': 'baz'})
 serializer.is_valid()
 # False
 serializer.errors
@@ -494,6 +495,23 @@ The <code>ModelSerializer</code> class lets you automatically create a Serialize
         read_only_fields = ('account_name',)
 </code></pre>
 <p>Model fields which have <code>editable=False</code> set, and <code>AutoField</code> fields will be set to read-only by default, and do not need to be added to the <code>read_only_fields</code> option. </p>
+<h2 id="specifying-which-fields-should-be-write-only">Specifying which fields should be write-only</h2>
+<p>You may wish to specify multiple fields as write-only.  Instead of adding each field explicitly with the <code>write_only=True</code> attribute, you may use the <code>write_only_fields</code> Meta option, like so:</p>
+<pre class="prettyprint lang-py"><code>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
+</code></pre>
 <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>
 <pre class="prettyprint lang-py"><code>class AccountSerializer(serializers.ModelSerializer):

topics/release-notes.html

@@ -225,8 +225,11 @@
 </code></pre>
 <hr />
 <h2 id="23x-series">2.3.x series</h2>
-<h3 id="master">Master</h3>
+<h3 id="2311">2.3.11</h3>
+<p><strong>Date</strong>: 14th January 2014</p>
 <ul>
+<li>Added <code>write_only</code> serializer field argument.</li>
+<li>Added <code>write_only_fields</code> option to <code>ModelSerializer</code> classes.</li>
 <li>JSON renderer now deals with objects that implement a dict-like interface.</li>
 <li>Fix compatiblity with newer versions of <code>django-oauth-plus</code>.</li>
 <li>Bugfix: Refine behavior that calls model manager <code>all()</code> across nested serializer relationships, preventing erronous behavior with some non-ORM objects, and preventing unneccessary queryset re-evaluations.</li>