Fill in TODOs for 3.0 beta release notes

This commit is contained in:
Tom Christie 2014-11-20 14:22:53 +00:00
parent 6a2023a362
commit 071c064d25

View File

@ -36,7 +36,7 @@ Notable features of this new release include:
* 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 present simple upgrades, without the same level of fundamental API changes necessary for the 3.0 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.
@ -145,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.
@ -356,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.
@ -673,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
@ -731,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