From d71ef9c6d810115bfe0de6327139c6886932cdb8 Mon Sep 17 00:00:00 2001 From: José Padilla Date: Mon, 15 Dec 2014 21:48:31 -0400 Subject: Closes #2281 --- docs/api-guide/relations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/relations.md b/docs/api-guide/relations.md index a79b6ea5..e56db229 100644 --- a/docs/api-guide/relations.md +++ b/docs/api-guide/relations.md @@ -397,7 +397,7 @@ We could define a custom field that could be used to serialize tagged instances, return 'Note: ' + value.text raise Exception('Unexpected type of tagged object') -If you need the target of the relationship to have a nested representation, you can use the required serializers inside the `.to_native()` method: +If you need the target of the relationship to have a nested representation, you can use the required serializers inside the `.to_representation()` method: def to_representation(self, value): """ -- cgit v1.2.3 From c6137bbf5aa7ca800e4afc06657e5196b2e0e481 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 17 Dec 2014 14:14:51 +0000 Subject: Serializer API restrictions. --- docs/api-guide/serializers.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 5fe6b4c2..137cc9d5 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -240,6 +240,12 @@ Serializer classes can also include reusable validators that are applied to the For more information see the [validators documentation](validators.md). +## Accessing the initial data and instance + +When passing an initial object or queryset to a serializer instance, the object will be made available as `.instance`. If no initial object is passed then the `.instance` attribute will be `None`. + +When passing data to a serializer instance, the unmodified data will be made available as `.initial_data`. If the data keyword argument is not passed then the `.initial_data` attribute will not exist. + ## Partial updates By default, serializers must be passed values for all required fields or they will raise validation errors. You can use the `partial` argument in order to allow partial updates. -- cgit v1.2.3 From 3fff5cb6e0960b7ff8abd9f13a075f1f057de0a7 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 17 Dec 2014 15:13:48 +0000 Subject: Fix empty HTML values when a default is provided. --- docs/api-guide/fields.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index e4ef1d4a..f06db56c 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -112,6 +112,8 @@ Two options are currently used in HTML form generation, `'input_type'` and `'bas A boolean representation. +When using HTML encoded form input be aware that omitting a value will always be treated as setting a field to `False`, even if it has a `default=True` option specified. This is because HTML checkbox inputs represent the unchecked state by omitting the value, so REST framework treats omission as if it is an empty checkbox input. + Corresponds to `django.db.models.fields.BooleanField`. **Signature:** `BooleanField()` -- cgit v1.2.3 From c9a2ce07037475359712104a8a68624e99bdfeb1 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 17 Dec 2014 16:19:02 +0000 Subject: Expand permissions docs. Closes #2223. --- docs/api-guide/permissions.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md index ddcefadb..743ca435 100644 --- a/docs/api-guide/permissions.md +++ b/docs/api-guide/permissions.md @@ -10,12 +10,24 @@ Together with [authentication] and [throttling], permissions determine whether a Permission checks are always run at the very start of the view, before any other code is allowed to proceed. Permission checks will typically use the authentication information in the `request.user` and `request.auth` properties to determine if the incoming request should be permitted. +Permissions are used to grant or deny access different classes of users to different parts of the API. + +The simplest style of permission would be to allow access to any authenticated user, and deny access to any unauthenticated user. This corresponds the `IsAuthenticated` class in REST framework. + +A slightly less strict style of permission would be to allow full access to authenticated users, but allow read-only access to unauthenticated users. This corresponds to the `IsAuthenticatedOrReadOnly` class in REST framework. + ## How permissions are determined Permissions in REST framework are always defined as a list of permission classes. Before running the main body of the view each permission in the list is checked. -If any permission check fails an `exceptions.PermissionDenied` exception will be raised, and the main body of the view will not run. +If any permission check fails an `exceptions.PermissionDenied` or `exceptions.NotAuthenticated` exception will be raised, and the main body of the view will not run. + +When the permissions checks fail either a "403 Forbidden" or a "401 Unauthorized" response will be returned, according to the following rules: + +* The request was successfully authenticated, but permission was denied. *— An HTTP 403 Forbidden response will be returned.* +* The request was not successfully authenticated, and the highest priority authentication class *does not* use `WWW-Authenticate` headers. *— An HTTP 403 Forbidden response will be returned.* +* The request was not successfully authenticated, and the highest priority authentication class *does* use `WWW-Authenticate` headers. *— An HTTP 401 Unauthorized response, with an appropriate `WWW-Authenticate` header will be returned.* ## Object level permissions -- cgit v1.2.3 From eeb6e340644eba70b2fd41100db34b159ae6f091 Mon Sep 17 00:00:00 2001 From: Tymur Maryokhin Date: Wed, 17 Dec 2014 17:28:11 +0100 Subject: Docs/tutorial import fixes. Refs #2296 --- docs/api-guide/serializers.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 137cc9d5..b9f0e7bc 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -22,11 +22,13 @@ The serializers in REST framework work very similarly to Django's `Form` and `Mo Let's start by creating a simple object we can use for example purposes: + from datetime import datetime + class Comment(object): def __init__(self, email, content, created=None): self.email = email self.content = content - self.created = created or datetime.datetime.now() + self.created = created or datetime.now() comment = Comment(email='leila@example.com', content='foo bar') @@ -61,10 +63,10 @@ At this point we've translated the model instance into Python native datatypes. Deserialization is similar. First we parse a stream into Python native datatypes... - from StringIO import StringIO + from django.utils.six import BytesIO from rest_framework.parsers import JSONParser - stream = StringIO(json) + stream = BytesIO(json) data = JSONParser().parse(stream) ...then we restore those native datatypes into a dictionary of validated data. -- cgit v1.2.3