Merge pull request #2095 from tomchristie/3.0-beta

3.0 beta

Author: tomchristie

docs/topics/3.0-announcement.md

@@ -1,10 +1,12 @@
 ## Pre-release notes:
 
-The 3.0 release is now ready for some tentative testing and upgrades for early adopters. You can install the development version directly from GitHub like so:
+The 3.0 release is now in beta and ready for final testing. You can install the development version directly from GitHub like so:
 
-    pip install https://github.com/tomchristie/django-rest-framework/archive/master.zip
+    pip install https://github.com/tomchristie/django-rest-framework/archive/3.0-beta.zip
 
-See the [Version 3.0 GitHub issue](https://github.com/tomchristie/django-rest-framework/pull/1800) for more details on remaining work.
+Currently the only known remaining blockers are documentation issues and tickets. Any critical bugs raised in the next week or two will be resolved for the 3.0 release, but otherwise consider this as code-complete.
+
+Please work through this document throughly in order to understand the API differences that exist between 2.4 and 3.0.
 
 **Your feedback on the upgrade process and 3.0 changes is hugely important!**
 
@@ -32,6 +34,9 @@ Notable features of this new release include:
 * Support for overriding how validation errors are handled by your API.
 * A metadata API that allows you to customize how `OPTIONS` requests are handled by your API.
 * A more compact JSON output with unicode style encoding turned on by default.
+* Templated based HTML form rendering for serializers. This will be finalized as  public API in the upcoming 3.1 release.
+
+Significant new functionality continues to be planned for the 3.1 and 3.2 releases. These releases will correspond to the two [Kickstarter stretch goals](https://www.kickstarter.com/projects/tomchristie/django-rest-framework-3) - "Feature improvements" and "Admin interface". Further 3.x releases will present simple upgrades, without the same level of fundamental API changes necessary for the 3.0 release.
 
 Below is an in-depth guide to the API changes and migration notes for 3.0.
 
@@ -140,6 +145,16 @@ The corresponding code would now look like this:
         logging.info('Creating ticket "%s"' % name)
         serializer.save(user=request.user)  # Include the user when saving.
 
+#### Using `.is_valid(raise_exception=True)`
+
+The `.is_valid()` method now takes an optional boolean flag, `raise_exception`.
+
+Calling `.is_valid(raise_exception=True)` will cause a `ValidationError` to be raised if the serializer data contains validation errors. This error will be handled by REST framework's default exception handler, allowing you to remove error response handling from your view code.
+
+The handling and formatting of error responses may be altered globally by using the `EXCEPTION_HANDLER` settings key.
+
+This change also means it's now possible to alter the style of error responses used by the built-in generic views, without having to include mixin classes or other overrides.
+
 #### Using `serializers.ValidationError`.
 
 Previously `serializers.ValidationError` error was simply a synonym for `django.core.exceptions.ValidationError`. This has now been altered so that it inherits from the standard `APIException` base class.
@@ -351,6 +366,8 @@ The `ListSerializer` class has now been added, and allows you to create base ser
 
 You can also still use the `many=True` argument to serializer classes. It's worth noting that `many=True` argument transparently creates a `ListSerializer` instance, allowing the validation logic for list and non-list data to be cleanly separated in the REST framework codebase. 
 
+You will typically want to *continue to use the existing `many=True` flag* rather than declaring `ListSerializer` classes explicitly, but declaring the classes explicitly can be useful if you need to write custom `create` or `update` methods for bulk updates, or provide for other custom behavior.
+
 See also the new `ListField` class, which validates input in the same way, but does not include the serializer interfaces of `.is_valid()`, `.data`, `.save()` and so on.
 
 #### The `BaseSerializer` class.
@@ -668,7 +685,9 @@ The `UniqueTogetherValidator` should be applied to a serializer, and takes a `qu
 
 #### The `UniqueForDateValidator` classes.
 
-**TODO: Needs documenting.**
+REST framework also now includes explicit validator classes for validating the `unique_for_date`, `unique_for_month`, and `unique_for_year` model field constraints. These are used internally instead of calling into `Model.full_clean()`.
+
+These classes are documented in the [Validators](../api-guide/validators.md) section of the documentation.
 
 ## Generic views
 
@@ -726,7 +745,34 @@ This makes it far easier to use a different style for `OPTIONS` responses throug
 
 ## Serializers as HTML forms
 
-**TODO: Document this.**
+REST framework 3.0 includes templated HTML form rendering for serializers.
+
+This API should not yet be considered finalized, and will only be promoted to public API for the 3.1 release.
+
+Significant changes that you do need to be aware of include:
+
+* Nested HTML forms are now supported, for example, a `UserSerializer` with a nested `ProfileSerializer` will now render a nested `fieldset` when used in the browsable API.
+* Nested lists of HTML forms are not yet supported, but are planned for 3.1.
+* Because we now use templated HTML form generation, **the `widget` option is no longer available for serializer fields**. You can instead control the template that is used for a given field, by using the `style` dictionary.
+
+#### The `style` keyword argument for serializer fields.
+
+The `style` keyword argument can be used to pass through additional information from a serializer field, to the renderer class. In particular, the `HTMLFormRenderer` uses the `base_template` key to determine which template to render the field with.
+
+For example, to use a `textarea` control instead of the default `input` control, you would use the following…
+
+    additional_notes = serializers.CharField(
+        style={'base_template': 'text_area.html'}
+    )
+
+Similarly, to use a radio button control instead of the default `select` control, you would use the following…
+
+    color_channel = serializers.ChoiceField(
+        choices=['red', 'blue', 'green'],
+        style={'base_template': 'radio.html'}
+    )
+
+This API should be considered provisional, and there may be minor alterations with the incoming 3.1 release.
 
 ## API style
 

rest_framework/renderers.py

@@ -562,7 +562,7 @@ def get_rendered_html_form(self, data, view, method, request):
                 serializer.data,
                 self.accepted_media_type,
                 dict(
-                    self.renderer_context.items() +
+                    list(self.renderer_context.items()) +
                     [('template', 'rest_framework/api_form.html')]
                 )
             )