From d24ea39a4e4131486d45492339dcbbfefb6a933b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 23 Dec 2013 14:29:22 +0000 Subject: Added note on view_name in hyperlinked relationships. Closes #1221 --- docs/api-guide/relations.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/relations.md b/docs/api-guide/relations.md index 1b089c54..4bee75af 100644 --- a/docs/api-guide/relations.md +++ b/docs/api-guide/relations.md @@ -134,7 +134,7 @@ By default this field is read-write, although you can change this behavior using **Arguments**: -* `view_name` - The view name that should be used as the target of the relationship. **required**. +* `view_name` - The view name that should be used as the target of the relationship. If you're using [the standard router classes][routers] this wil be a string with the format `-detail`. **required**. * `many` - If applied to a to-many relationship, you should set this argument to `True`. * `required` - If set to `False`, the field will accept values of `None` or the empty-string for nullable relationships. * `queryset` - By default `ModelSerializer` classes will use the default queryset for the relationship. `Serializer` classes must either set a queryset explicitly, or set `read_only=True`. @@ -202,7 +202,7 @@ This field is always read-only. **Arguments**: -* `view_name` - The view name that should be used as the target of the relationship. **required**. +* `view_name` - The view name that should be used as the target of the relationship. If you're using [the standard router classes][routers] this wil be a string with the format `-detail`. **required**. * `lookup_field` - The field on the target that should be used for the lookup. Should correspond to a URL keyword argument on the referenced view. Default is `'pk'`. * `format` - If using format suffixes, hyperlinked fields will use the same format suffix for the target unless overridden by using the `format` argument. @@ -454,6 +454,7 @@ The [drf-nested-routers package][drf-nested-routers] provides routers and relati [cite]: http://lwn.net/Articles/193245/ [reverse-relationships]: https://docs.djangoproject.com/en/dev/topics/db/queries/#following-relationships-backward +[routers]: http://django-rest-framework.org/api-guide/routers#defaultrouter [generic-relations]: https://docs.djangoproject.com/en/dev/ref/contrib/contenttypes/#id1 [2.2-announcement]: ../topics/2.2-announcement.md [drf-nested-routers]: https://github.com/alanjds/drf-nested-routers -- cgit v1.2.3 From 75e872473197f9b810c9daf348cb452faadac476 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 23 Dec 2013 14:38:51 +0000 Subject: Fuller notes on the 'base_name' argument. Closes #1160. --- docs/api-guide/routers.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/routers.md b/docs/api-guide/routers.md index 895589db..7efc140a 100644 --- a/docs/api-guide/routers.md +++ b/docs/api-guide/routers.md @@ -37,6 +37,18 @@ The example above would generate the following URL patterns: * URL pattern: `^accounts/$` Name: `'account-list'` * URL pattern: `^accounts/{pk}/$` Name: `'account-detail'` +--- + +**Note**: The `base_name` argument is used to specify the initial part of the view name pattern. In the example above, that's the `user` or `account` part. + +Typically you won't *need* to specify the `base-name` argument, but if you have a viewset where you've defined a custom `get_queryset` method, then the viewset may not have any `.model` or `.queryset` attribute set. If you try to register that viewset you'll see an error like this: + + 'base_name' argument not specified, and could not automatically determine the name from the viewset, as it does not have a '.model' or '.queryset' attribute. + +This means you'll need to explicitly set the `base_name` argument when registering the viewset, as it could not be automatically determined from the model name. + +--- + ### Extra link and actions Any methods on the viewset decorated with `@link` or `@action` will also be routed. -- cgit v1.2.3 From 78494401c5c45d16d632bb2fa9629678e47a98bc Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 8 Jan 2014 15:22:41 +0000 Subject: Use www.django-rest-framework.org for docs instead of django-rest-framework.org due to issues with naked domains --- 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 4bee75af..cc4f5585 100644 --- a/docs/api-guide/relations.md +++ b/docs/api-guide/relations.md @@ -454,7 +454,7 @@ The [drf-nested-routers package][drf-nested-routers] provides routers and relati [cite]: http://lwn.net/Articles/193245/ [reverse-relationships]: https://docs.djangoproject.com/en/dev/topics/db/queries/#following-relationships-backward -[routers]: http://django-rest-framework.org/api-guide/routers#defaultrouter +[routers]: http://www.django-rest-framework.org/api-guide/routers#defaultrouter [generic-relations]: https://docs.djangoproject.com/en/dev/ref/contrib/contenttypes/#id1 [2.2-announcement]: ../topics/2.2-announcement.md [drf-nested-routers]: https://github.com/alanjds/drf-nested-routers -- cgit v1.2.3 From 052e236fde3453b33a4e651293da84e7d302cefb Mon Sep 17 00:00:00 2001 From: Yuri Prezument Date: Thu, 9 Jan 2014 18:12:30 +0200 Subject: Fix URL/Slug Field signatures in docs --- docs/api-guide/fields.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index e05c0306..91866664 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -167,13 +167,13 @@ or `django.db.models.fields.TextField`. 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 -- cgit v1.2.3 From 4b8d1b66ab2184166192e0c1ffea9b5f11fff8d3 Mon Sep 17 00:00:00 2001 From: Paul Melnikow Date: Fri, 10 Jan 2014 08:22:47 -0500 Subject: serializers.md: Fix typos --- docs/api-guide/serializers.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 6fc25f57..04439092 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -103,11 +103,11 @@ Deserialization is similar. First we parse a stream into Python native datatype 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 @@ -208,7 +208,7 @@ Similarly if a nested representation should be a list of items, you should pass 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 -- cgit v1.2.3 From 85d74fc86a934309359a437dd487193013055977 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 14 Jan 2014 11:25:44 +0000 Subject: Added write_only and write_only_fields. Refs #1306 --- docs/api-guide/fields.md | 8 +++++++- docs/api-guide/serializers.md | 19 +++++++++++++++++++ 2 files changed, 26 insertions(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 91866664..c136509b 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -28,7 +28,13 @@ 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` diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 04439092..b05acfd5 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -373,6 +373,25 @@ You may wish to specify multiple fields as read-only. Instead of adding each fi 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. -- cgit v1.2.3 From d20c49da4ae6f569d3acc243169e3c13c89a95fe Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 14 Jan 2014 20:34:33 +0000 Subject: More HyperlinkedModelSerializer docs --- docs/api-guide/serializers.md | 23 +++++++++++++++++++++++ docs/api-guide/settings.md | 6 ++++++ 2 files changed, 29 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index b05acfd5..e8369c20 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -464,6 +464,29 @@ For more specific requirements such as specifying a different lookup for each fi model = Account fields = ('url', 'account_name', 'users', 'created') +## Overiding the URL field behavior + +The name of the URL field defaults to 'url'. You can override this globally, by using the `URL_FIELD_NAME` setting. + +You can also override this on a per-serializer basis by using the `url_field_name` option on the serializer, like so: + + class AccountSerializer(serializers.HyperlinkedModelSerializer): + class Meta: + model = Account + fields = ('account_url', 'account_name', 'users', 'created') + url_field_name = 'account_url' + +**Note**: The generic view implementations normally generate a `Location` header in response to successful `POST` requests. Serializers using `url_field_name` option will not have this header automatically included by the view. If you need to do so you will ned to also override the view's `get_success_headers()` method. + +You can also overide the URL field's view name and lookup field without overriding the field explicitly, by using the `view_name` and `lookup_field` options, like so: + + class AccountSerializer(serializers.HyperlinkedModelSerializer): + class Meta: + model = Account + fields = ('account_url', 'account_name', 'users', 'created') + view_name = 'account_detail' + lookup_field='account_name' + --- # Advanced serializer usage diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 13f96f9a..5aee52aa 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -353,6 +353,12 @@ This should be a function with the following signature: Default: `'rest_framework.views.exception_handler'` +#### URL_FIELD_NAME + +A string representing the key that should be used for the URL fields generated by `HyperlinkedModelSerializer`. + +Default: `'url'` + #### FORMAT_SUFFIX_KWARG The name of a parameter in the URL conf that may be used to provide a format suffix. -- cgit v1.2.3 From 71c03b9db97edbde228777981de0ac7b664302de Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 15 Jan 2014 14:27:41 +0000 Subject: Security update to OrderingFilter --- docs/api-guide/filtering.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md index 0e02a2a7..07420d84 100644 --- a/docs/api-guide/filtering.md +++ b/docs/api-guide/filtering.md @@ -282,13 +282,37 @@ Multiple orderings may also be specified: http://example.com/api/users?ordering=account,username +### Specifying which fields may be ordered against + +It's recommended that you explicitly specify which fields the API should allowing in the ordering filter. You can do this by setting an `ordering_fields` attribute on the view, like so: + + class UserListView(generics.ListAPIView): + queryset = User.objects.all() + serializer_class = UserSerializer + filter_backends = (filters.OrderingFilter,) + ordering_fields = ('username', 'email') + +This helps prevent unexpected data leakage, such as allowing users to order against a password hash field or other sensitive data. + +If you *don't* specify an `ordering_fields` attribute on the view, the filter class will default to allowing the user to filter on any readable fields on the serializer specified by the `serializer_class` attribute. + +If you are confident that the queryset being used by the view doesn't contain any sensitive data, you can also explicitly specify that a view should allow ordering on *any* model field or queryset aggregate, by using the special value `'__all__'`. + + class BookingsListView(generics.ListAPIView): + queryset = Booking.objects.all() + serializer_class = BookingSerializer + filter_backends = (filters.OrderingFilter,) + ordering_fields = '__all__' + +### Specifying a default ordering + If an `ordering` attribute is set on the view, this will be used as the default ordering. Typically you'd instead control this by setting `order_by` on the initial queryset, but using the `ordering` parameter on the view allows you to specify the ordering in a way that it can then be passed automatically as context to a rendered template. This makes it possible to automatically render column headers differently if they are being used to order the results. class UserListView(generics.ListAPIView): queryset = User.objects.all() - serializer = UserSerializer + serializer_class = UserSerializer filter_backends = (filters.OrderingFilter,) ordering = ('username',) -- cgit v1.2.3 From 37cd49cac98dfb5b79c4e4df0f42e782280172ce Mon Sep 17 00:00:00 2001 From: Miroslav Shubernetskiy Date: Sat, 18 Jan 2014 22:31:36 -0500 Subject: Added docs for bulk views from django-rest-framework-bulk. --- docs/api-guide/generic-views.md | 49 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 83c3e45f..11b55063 100755 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -362,6 +362,54 @@ If you are using a mixin across multiple views, you can take this a step further Using custom base classes is a good option if you have custom behavior that consistently needs to be repeated across a large number of views throughout your project. +# Third party packages + +The following third party packages provide additional generic view implementations. + +## Django REST Framework bulk + +The [django-rest-framework-bulk package][django-rest-framework-bulk] implements generic view mixins as well as some common concrete generic views to allow to apply bulk operations via API requests. + +### Mixins + +As with Django Rest Framework standard mixins, each mixin defines a specific behavior which allows to composite multiple mixins (either with other bulk mixins or standard mixins) for more functionality. + +#### BulkCreateModelMixin + +Provides a `.create(request, *args, **kwargs)` method, that implements creating either a single or multiple objects depending on the `request.DATA` data-type (list or object). + +If any object(s) is/are created, as with the standard `CreateModelMixin`, `201 Created` response is returned with the serialization of created object(s). If any errors occur while validating the provided data, `400 Bad Request` is returned with error details for each attempted creation object. + +#### BulkUpdateModelMixin + +Provides a `.bulk_update(request, *args, **kwargs)` method, that implements updating multiple objects at the same time. Since each object needs to be identified, each object within `request.DATA` must provide its identity as per serializer's `.get_identity()`. + +Also provides a `.partial_bulk_update(request, *args, **kwargs)` method, which is similar to the `bulk_update`, except that all fields for all resources will be optional. + +If all objects are updated, `200 OK` response is returned with the serialized representation of all updated objects. If any validation errors occur, `400 Bad Request` is returned. + +#### BulkDestroyModelMixin + +Provides a `.bulk_destroy(request, *args, **kwargs)` method, that implements deletion of all objects within a queryset. Since that can potentially be very dangerous, this mixin also provides an `.allow_bulk_destroy(queryset, filtered)` hook to determine if the bulk delete should be allowed. By default it allows the request if the queryset was filtered. + +If the objects are deleted this returns `204 No Content` response or `400 Bad Request` if the request is not allowed as per `allow_bulk_destroy`. + +### Concrete View Classes + +In addition to the bulk mixins, this package also implements some of the most common bulk concrete view classes. Those include: + +* `BulkCreateAPIView` +* `BulkUpdateAPIView` +* `BulkDestroyAPIView` +* `ListBulkCreateAPIView` +* `ListCreateBulkUpdateAPIView` +* `ListCreateBulkUpdateDestroyAPIView` +* `ListBulkCreateUpdateAPIView` +* `ListBulkCreateUpdateDestroyAPIView` + +To create custom concrete view classes, you can also composite the mixins manually as explained in **Creating custom base classes** of Django Rest Framework documentation. + + [cite]: https://docs.djangoproject.com/en/dev/ref/class-based-views/#base-vs-generic-views [GenericAPIView]: #genericapiview @@ -370,3 +418,4 @@ Using custom base classes is a good option if you have custom behavior that cons [RetrieveModelMixin]: #retrievemodelmixin [UpdateModelMixin]: #updatemodelmixin [DestroyModelMixin]: #destroymodelmixin +[django-rest-framework-bulk]: https://github.com/miki725/django-rest-framework-bulk -- cgit v1.2.3 From 1c34051f5edcb7cddae63fc02b0a21d6e5fc1143 Mon Sep 17 00:00:00 2001 From: José Padilla Date: Sat, 18 Jan 2014 23:51:18 -0500 Subject: Include the djangorestframework-jwt package --- docs/api-guide/authentication.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 53efc49a..dc8e2099 100755 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -389,6 +389,10 @@ The [Django OAuth Toolkit][django-oauth-toolkit] package provides OAuth 2.0 supp The [Django OAuth2 Consumer][doac] library from [Rediker Software][rediker] is another package that provides [OAuth 2.0 support for REST framework][doac-rest-framework]. The package includes token scoping permissions on tokens, which allows finer-grained access to your API. +## JSON Web Token Authentication + +JSON Web Token is a fairly new standard which can be used for token-based authentication. Unlike the built-in TokenAuthentication scheme, JWT Authentication doesn't need to use a database to validate a token. [Blimp][blimp] maintains the [djangorestframework-jwt][djangorestframework-jwt] package which provides a JWT Authentication class as well as a mechanism for clients to obtain a JWT given the username and password. + [cite]: http://jacobian.org/writing/rest-worst-practices/ [http401]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2 [http403]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4 @@ -413,3 +417,5 @@ The [Django OAuth2 Consumer][doac] library from [Rediker Software][rediker] is a [doac]: https://github.com/Rediker-Software/doac [rediker]: https://github.com/Rediker-Software [doac-rest-framework]: https://github.com/Rediker-Software/doac/blob/master/docs/integrations.md# +[blimp]: https://github.com/GetBlimp +[djangorestframework-jwt]: https://github.com/GetBlimp/django-rest-framework-jwt -- cgit v1.2.3 From e3c5a134510c8e364bd278dc5033ccb5515927d7 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sun, 19 Jan 2014 21:09:49 +0000 Subject: Drop django-rest-framework-bulk API descriptions --- docs/api-guide/generic-views.md | 40 ---------------------------------------- 1 file changed, 40 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 11b55063..e23b2c74 100755 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -370,48 +370,8 @@ The following third party packages provide additional generic view implementatio The [django-rest-framework-bulk package][django-rest-framework-bulk] implements generic view mixins as well as some common concrete generic views to allow to apply bulk operations via API requests. -### Mixins - -As with Django Rest Framework standard mixins, each mixin defines a specific behavior which allows to composite multiple mixins (either with other bulk mixins or standard mixins) for more functionality. - -#### BulkCreateModelMixin - -Provides a `.create(request, *args, **kwargs)` method, that implements creating either a single or multiple objects depending on the `request.DATA` data-type (list or object). - -If any object(s) is/are created, as with the standard `CreateModelMixin`, `201 Created` response is returned with the serialization of created object(s). If any errors occur while validating the provided data, `400 Bad Request` is returned with error details for each attempted creation object. - -#### BulkUpdateModelMixin - -Provides a `.bulk_update(request, *args, **kwargs)` method, that implements updating multiple objects at the same time. Since each object needs to be identified, each object within `request.DATA` must provide its identity as per serializer's `.get_identity()`. - -Also provides a `.partial_bulk_update(request, *args, **kwargs)` method, which is similar to the `bulk_update`, except that all fields for all resources will be optional. - -If all objects are updated, `200 OK` response is returned with the serialized representation of all updated objects. If any validation errors occur, `400 Bad Request` is returned. - -#### BulkDestroyModelMixin - -Provides a `.bulk_destroy(request, *args, **kwargs)` method, that implements deletion of all objects within a queryset. Since that can potentially be very dangerous, this mixin also provides an `.allow_bulk_destroy(queryset, filtered)` hook to determine if the bulk delete should be allowed. By default it allows the request if the queryset was filtered. - -If the objects are deleted this returns `204 No Content` response or `400 Bad Request` if the request is not allowed as per `allow_bulk_destroy`. - -### Concrete View Classes - -In addition to the bulk mixins, this package also implements some of the most common bulk concrete view classes. Those include: - -* `BulkCreateAPIView` -* `BulkUpdateAPIView` -* `BulkDestroyAPIView` -* `ListBulkCreateAPIView` -* `ListCreateBulkUpdateAPIView` -* `ListCreateBulkUpdateDestroyAPIView` -* `ListBulkCreateUpdateAPIView` -* `ListBulkCreateUpdateDestroyAPIView` - -To create custom concrete view classes, you can also composite the mixins manually as explained in **Creating custom base classes** of Django Rest Framework documentation. - [cite]: https://docs.djangoproject.com/en/dev/ref/class-based-views/#base-vs-generic-views - [GenericAPIView]: #genericapiview [ListModelMixin]: #listmodelmixin [CreateModelMixin]: #createmodelmixin -- cgit v1.2.3 From 77ced39e6c02cd375ac6df0c00f78846ac5cbec5 Mon Sep 17 00:00:00 2001 From: Paul Melnikow Date: Fri, 31 Jan 2014 12:26:45 -0500 Subject: Fix doc for custom exception sample The way to provide a default detail for APIException is to define a `default_detail` attribute on the subclass. Defining a `detail` attribute without `default_detail` will not work, and will result in empty detail instead. --- docs/api-guide/exceptions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md index 221df679..4e8b823c 100644 --- a/docs/api-guide/exceptions.md +++ b/docs/api-guide/exceptions.md @@ -94,7 +94,7 @@ For example, if your API relies on a third party service that may sometimes be u class ServiceUnavailable(APIException): status_code = 503 - detail = 'Service temporarily unavailable, try again later.' + default_detail = 'Service temporarily unavailable, try again later.' ## ParseError -- cgit v1.2.3 From e437854a44249806478c40f1e36244863e5ded3d Mon Sep 17 00:00:00 2001 From: meoooh Date: Sat, 1 Feb 2014 15:02:11 +0900 Subject: Update fields.md --- docs/api-guide/fields.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index c136509b..0b50aa95 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -104,6 +104,7 @@ A serializer definition that looked like this: expired = serializers.Field(source='has_expired') class Meta: + model = Account fields = ('url', 'owner', 'name', 'expired') Would produce output similar to: -- cgit v1.2.3 From a33eb4177e78a65d9e07cec18198b48fa11acca1 Mon Sep 17 00:00:00 2001 From: Jeff Fein-Worton Date: Sun, 2 Feb 2014 21:21:08 -0800 Subject: fixed typo (wrong "its") --- docs/api-guide/fields.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 0b50aa95..93f992e6 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -126,7 +126,7 @@ A field that supports both read and write operations. By itself `WritableField` ## ModelField -A generic field that can be tied to any arbitrary model field. The `ModelField` class delegates the task of serialization/deserialization to it's associated model field. This field can be used to create serializer fields for custom model fields, without having to create a new custom serializer field. +A generic field that can be tied to any arbitrary model field. The `ModelField` class delegates the task of serialization/deserialization to its associated model field. This field can be used to create serializer fields for custom model fields, without having to create a new custom serializer field. The `ModelField` class is generally intended for internal use, but can be used by your API if needed. In order to properly instantiate a `ModelField`, it must be passed a field that is attached to an instantiated model. For example: `ModelField(model_field=MyModel()._meta.get_field('custom_field'))` @@ -308,7 +308,7 @@ Django's regular [FILE_UPLOAD_HANDLERS] are used for handling uploaded files. If you want to create a custom field, you'll probably want to override either one or both of the `.to_native()` and `.from_native()` methods. These two methods are used to convert between the initial datatype, and a primitive, serializable datatype. Primitive datatypes may be any of a number, string, date/time/datetime or None. They may also be any list or dictionary like object that only contains other primitive objects. -The `.to_native()` method is called to convert the initial datatype into a primitive, serializable datatype. The `from_native()` method is called to restore a primitive datatype into it's initial representation. +The `.to_native()` method is called to convert the initial datatype into a primitive, serializable datatype. The `from_native()` method is called to restore a primitive datatype into its initial representation. ## Examples -- cgit v1.2.3 From 40b148a2e427ffbedbc04c47235f07bf98d7e520 Mon Sep 17 00:00:00 2001 From: Charlie Denton Date: Mon, 3 Feb 2014 14:54:44 +0000 Subject: Viewsets docs typo The docstring in the example said "update" instead of "create".--- docs/api-guide/viewsets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md index 4fdd9364..23b16575 100644 --- a/docs/api-guide/viewsets.md +++ b/docs/api-guide/viewsets.md @@ -225,7 +225,7 @@ To create a base viewset class that provides `create`, `list` and `retrieve` ope mixins.RetrieveModelMixin, viewsets.GenericViewSet): """ - A viewset that provides `retrieve`, `update`, and `list` actions. + A viewset that provides `retrieve`, `create`, and `list` actions. To use it, override the class and set the `.queryset` and `.serializer_class` attributes. -- cgit v1.2.3 From ba8a0bac538adc8d6897ece14648e03ce7441b24 Mon Sep 17 00:00:00 2001 From: RicterZ Date: Tue, 4 Feb 2014 23:41:13 +0800 Subject: Fixed a bug backticks fix you may optionally exclude the ``self.check_object_permissions, and simply return the object from the `get_object_or_404` lookup. to you may optionally exclude the `self.check_object_permissions`, and simply return the object from the `get_object_or_404` lookup.--- docs/api-guide/generic-views.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index e23b2c74..fb927ea8 100755 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -119,7 +119,7 @@ For example: self.check_object_permissions(self.request, obj) return obj -Note that if your API doesn't include any object level permissions, you may optionally exclude the ``self.check_object_permissions, and simply return the object from the `get_object_or_404` lookup. +Note that if your API doesn't include any object level permissions, you may optionally exclude the `self.check_object_permissions`, and simply return the object from the `get_object_or_404` lookup. #### `get_filter_backends(self)` -- cgit v1.2.3 From 97b7c25987c3bfa096a084dc671fc24816b08f87 Mon Sep 17 00:00:00 2001 From: Hassan Shamim Date: Mon, 10 Feb 2014 12:54:56 -0600 Subject: Replace 'detail' with 'default_detail' in Exceptions guide and APIException class docstring. --- docs/api-guide/exceptions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md index 4e8b823c..66e18173 100644 --- a/docs/api-guide/exceptions.md +++ b/docs/api-guide/exceptions.md @@ -18,7 +18,7 @@ The handled exceptions are: In each case, REST framework will return a response with an appropriate status code and content-type. The body of the response will include any additional details regarding the nature of the error. -By default all error responses will include a key `details` in the body of the response, but other keys may also be included. +By default all error responses will include a key `detail` in the body of the response, but other keys may also be included. For example, the following request: @@ -86,7 +86,7 @@ Note that the exception handler will only be called for responses generated by r The **base class** for all exceptions raised inside REST framework. -To provide a custom exception, subclass `APIException` and set the `.status_code` and `.detail` properties on the class. +To provide a custom exception, subclass `APIException` and set the `.status_code` and `.default_detail` properties on the class. For example, if your API relies on a third party service that may sometimes be unreachable, you might want to implement an exception for the "503 Service Unavailable" HTTP response code. You could do this like so: -- cgit v1.2.3 From 821f8488023cb5161eb0f69b9121f6d956c39baf Mon Sep 17 00:00:00 2001 From: Vita Smid Date: Fri, 14 Feb 2014 10:44:02 +0100 Subject: Minor typos fixed in api-guide/testing.md (request -> response). --- docs/api-guide/testing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/testing.md b/docs/api-guide/testing.md index 4a8a9168..72c33961 100644 --- a/docs/api-guide/testing.md +++ b/docs/api-guide/testing.md @@ -218,12 +218,12 @@ You can use any of REST framework's test case classes as you would for the regul When checking the validity of test responses it's often more convenient to inspect the data that the response was created with, rather than inspecting the fully rendered response. -For example, it's easier to inspect `request.data`: +For example, it's easier to inspect `response.data`: response = self.client.get('/users/4/') self.assertEqual(response.data, {'id': 4, 'username': 'lauren'}) -Instead of inspecting the result of parsing `request.content`: +Instead of inspecting the result of parsing `response.content`: response = self.client.get('/users/4/') self.assertEqual(json.loads(response.content), {'id': 4, 'username': 'lauren'}) -- cgit v1.2.3 From 6f4c2c6f0536bdf596534c295e411e17be14aab7 Mon Sep 17 00:00:00 2001 From: Bo Peng Date: Fri, 14 Feb 2014 13:47:06 -0600 Subject: Update throttling.md Added comma to make DEFAULT_THROTTLE_CLASSES a tuple in example, for copy&paste to work nicely.--- docs/api-guide/throttling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md index fc1525df..b7c320f0 100644 --- a/docs/api-guide/throttling.md +++ b/docs/api-guide/throttling.md @@ -150,7 +150,7 @@ For example, given the following views... REST_FRAMEWORK = { 'DEFAULT_THROTTLE_CLASSES': ( - 'rest_framework.throttling.ScopedRateThrottle' + 'rest_framework.throttling.ScopedRateThrottle', ), 'DEFAULT_THROTTLE_RATES': { 'contacts': '1000/day', -- cgit v1.2.3 From b3aa512d35b7f3e432bb41bf9de9ac7db7a1ed4c Mon Sep 17 00:00:00 2001 From: Saurabh Kumar Date: Tue, 18 Feb 2014 20:39:39 +0530 Subject: fix(docs): fix code indentation in serializers.md It fixes the indentation of `restore_object()` in the section "Specifying which fields should be write-only" serializers documentation.--- docs/api-guide/serializers.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index e8369c20..39fe61eb 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -383,14 +383,14 @@ You may wish to specify multiple fields as write-only. Instead of adding each f 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 + 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 -- cgit v1.2.3 From 1a4c6f075b33661e9b919c95575a5439aa924dcd Mon Sep 17 00:00:00 2001 From: Elvio Toccalino Date: Thu, 20 Feb 2014 01:07:39 -0300 Subject: include djangorestframework-httpsignature in the docs --- docs/api-guide/authentication.md | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index dc8e2099..f992b0ce 100755 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -393,6 +393,10 @@ The [Django OAuth2 Consumer][doac] library from [Rediker Software][rediker] is a JSON Web Token is a fairly new standard which can be used for token-based authentication. Unlike the built-in TokenAuthentication scheme, JWT Authentication doesn't need to use a database to validate a token. [Blimp][blimp] maintains the [djangorestframework-jwt][djangorestframework-jwt] package which provides a JWT Authentication class as well as a mechanism for clients to obtain a JWT given the username and password. +## HTTP Signature Authentication + +HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a way to achieve origin authentication and message integrity for HTTP messages. Similar to [Amazon's HTTP Signature scheme][amazon-http-signature], used by many of its services, it permits stateless, per-request authentication. [Elvio Toccalino][etoccalino] maintains the [djangorestframework-httpsignature][djangorestframework-httpsignature] package which provides an easy to use HTTP Signature Authentication mechanism. + [cite]: http://jacobian.org/writing/rest-worst-practices/ [http401]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2 [http403]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4 @@ -419,3 +423,7 @@ JSON Web Token is a fairly new standard which can be used for token-based authen [doac-rest-framework]: https://github.com/Rediker-Software/doac/blob/master/docs/integrations.md# [blimp]: https://github.com/GetBlimp [djangorestframework-jwt]: https://github.com/GetBlimp/django-rest-framework-jwt +[etoccalino]: https://github.com/etoccalino/ +[djangorestframework-httpsignature]: https://github.com/etoccalino/django-rest-framework-httpsignature +[amazon-http-signature]: http://docs.aws.amazon.com/general/latest/gr/signature-version-4.html +[http-signature-ietf-draft]: https://datatracker.ietf.org/doc/draft-cavage-http-signatures/ -- cgit v1.2.3 From 98410693738aa81528bef2016a69e87560ae4ae3 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 20 Feb 2014 14:54:17 +0000 Subject: Link to DRF-extensions. Refs #1430 --- docs/api-guide/pagination.md | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md index 0829589f..efc4ae7f 100644 --- a/docs/api-guide/pagination.md +++ b/docs/api-guide/pagination.md @@ -147,4 +147,14 @@ Alternatively, to set your custom pagination serializer on a per-view basis, use pagination_serializer_class = CustomPaginationSerializer paginate_by = 10 +# Third party packages + +The following third party packages are also available. + +## DRF-extensions + +The [`DRF-extensions` package][drf-extensions] includes a [`PaginateByMaxMixin` mixin class][paginate-by-max-mixin] that allows your API clients to specify `?page_size=max` to obtain the maximum allowed page size. + [cite]: https://docs.djangoproject.com/en/dev/topics/pagination/ +[drf-extensions]: http://chibisov.github.io/drf-extensions/docs/ +[paginate-by-max-mixin]: http://chibisov.github.io/drf-extensions/docs/#paginatebymaxmixin \ No newline at end of file -- cgit v1.2.3 From c3967c08ab48a8129b7d7fdc00175fd203aea6c8 Mon Sep 17 00:00:00 2001 From: Charlie Denton Date: Fri, 21 Feb 2014 14:23:33 +0000 Subject: Minor docs example fix Dates are smaller when they happen before.--- docs/api-guide/serializers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 39fe61eb..7ee060af 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -161,7 +161,7 @@ To do any other validation that requires access to multiple fields, add a method """ Check that the start is before the stop. """ - if attrs['start'] < attrs['finish']: + if attrs['start'] > attrs['finish']: raise serializers.ValidationError("finish must occur after start") return attrs -- cgit v1.2.3 From a4470c42765004825ed6c09ae434dfd7dd969d1e Mon Sep 17 00:00:00 2001 From: Kumar McMillan Date: Fri, 28 Feb 2014 16:51:32 -0600 Subject: Fix trailing whitespace Sorry, my editor does this automatically --- docs/api-guide/authentication.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index f992b0ce..59bea733 100755 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -93,7 +93,7 @@ Note that if deploying to [Apache using mod_wsgi][mod_wsgi_official], the author If you are deploying to Apache, and using any non-session based authentication, you will need to explicitly configure mod_wsgi to pass the required headers through to the application. This can be done by specifying the `WSGIPassAuthorization` directive in the appropriate context and setting it to `'On'`. - # this can go in either server config, virtual host, directory or .htaccess + # this can go in either server config, virtual host, directory or .htaccess WSGIPassAuthorization On --- @@ -117,7 +117,7 @@ Unauthenticated responses that are denied permission will result in an `HTTP 401 ## TokenAuthentication -This authentication scheme uses a simple token-based HTTP Authentication scheme. Token authentication is appropriate for client-server setups, such as native desktop and mobile clients. +This authentication scheme uses a simple token-based HTTP Authentication scheme. Token authentication is appropriate for client-server setups, such as native desktop and mobile clients. To use the `TokenAuthentication` scheme, include `rest_framework.authtoken` in your `INSTALLED_APPS` setting: @@ -125,7 +125,7 @@ To use the `TokenAuthentication` scheme, include `rest_framework.authtoken` in y ... 'rest_framework.authtoken' ) - + Make sure to run `manage.py syncdb` after changing your settings. The `authtoken` database tables are managed by south (see [Schema migrations](#schema-migrations) below). You'll also need to create tokens for your users. @@ -209,7 +209,7 @@ You can do so by inserting a `needed_by` attribute in your user migration: needed_by = ( ('authtoken', '0001_initial'), ) - + def forwards(self): ... @@ -282,7 +282,7 @@ Note that the `namespace='oauth2'` argument is required. Finally, sync your database. python manage.py syncdb - python manage.py migrate + python manage.py migrate --- @@ -368,7 +368,7 @@ The following example will authenticate any incoming request as the user given b user = User.objects.get(username=username) except User.DoesNotExist: raise exceptions.AuthenticationFailed('No such user') - + return (user, None) --- -- cgit v1.2.3 From c2cd610b15e97979be23e4c7e713028ef7f2e23a Mon Sep 17 00:00:00 2001 From: Kumar McMillan Date: Fri, 28 Feb 2014 16:51:58 -0600 Subject: Adds HawkREST to 3rd party auth docs --- docs/api-guide/authentication.md | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 59bea733..88a7a011 100755 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -393,6 +393,10 @@ The [Django OAuth2 Consumer][doac] library from [Rediker Software][rediker] is a JSON Web Token is a fairly new standard which can be used for token-based authentication. Unlike the built-in TokenAuthentication scheme, JWT Authentication doesn't need to use a database to validate a token. [Blimp][blimp] maintains the [djangorestframework-jwt][djangorestframework-jwt] package which provides a JWT Authentication class as well as a mechanism for clients to obtain a JWT given the username and password. +## Hawk HTTP Authentication + +The [HawkREST][hawkrest] library builds on the [Mohawk][mohawk] library to let you work with [Hawk][hawk] signed requests and responses in your API. [Hawk][hawk] lets two parties securely communicate with each other using messages signed by a shared key. It is based on [HTTP MAC access authentication][mac] (which was based on parts of [OAuth 1.0][oauth-1.0a]). + ## HTTP Signature Authentication HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a way to achieve origin authentication and message integrity for HTTP messages. Similar to [Amazon's HTTP Signature scheme][amazon-http-signature], used by many of its services, it permits stateless, per-request authentication. [Elvio Toccalino][etoccalino] maintains the [djangorestframework-httpsignature][djangorestframework-httpsignature] package which provides an easy to use HTTP Signature Authentication mechanism. @@ -427,3 +431,7 @@ HTTP Signature (currently a [IETF draft][http-signature-ietf-draft]) provides a [djangorestframework-httpsignature]: https://github.com/etoccalino/django-rest-framework-httpsignature [amazon-http-signature]: http://docs.aws.amazon.com/general/latest/gr/signature-version-4.html [http-signature-ietf-draft]: https://datatracker.ietf.org/doc/draft-cavage-http-signatures/ +[hawkrest]: http://hawkrest.readthedocs.org/en/latest/ +[hawk]: https://github.com/hueniverse/hawk +[mohawk]: http://mohawk.readthedocs.org/en/latest/ +[mac]: http://tools.ietf.org/html/draft-hammer-oauth-v2-mac-token-05 -- cgit v1.2.3 From 2353878951b0607a95d539c27c362d0353c53119 Mon Sep 17 00:00:00 2001 From: Peter Inglesby Date: Thu, 6 Mar 2014 21:39:44 +0000 Subject: Add SEARCH_PARAM and ORDERING_PARAM to settings Fixes #1434--- docs/api-guide/filtering.md | 6 +++++- docs/api-guide/settings.md | 12 ++++++++++++ 2 files changed, 17 insertions(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md index 07420d84..d6c4b1c1 100644 --- a/docs/api-guide/filtering.md +++ b/docs/api-guide/filtering.md @@ -264,13 +264,17 @@ For example: search_fields = ('=username', '=email') +By default, the search parameter is named `'search`', but this may be overridden with the `SEARCH_PARAM` setting. + For more details, see the [Django documentation][search-django-admin]. --- ## OrderingFilter -The `OrderingFilter` class supports simple query parameter controlled ordering of results. To specify the result order, set a query parameter named `'ordering'` to the required field name. For example: +The `OrderingFilter` class supports simple query parameter controlled ordering of results. By default, the query parameter is named `'ordering'`, but this may by overridden with the `ORDERING_PARAM` setting. + +For example, to order users by username: http://example.com/api/users?ordering=username diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 5aee52aa..c979019f 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -158,6 +158,18 @@ A client request like the following would return a paginated list of up to 100 i Default: `None` +### SEARCH_PARAM + +The name of a query paramater, which can be used to specify the search term used by `SearchFilter`. + +Default: `search` + +#### ORDERING_PARAM + +The name of a query paramater, which can be used to specify the ordering of results returned by `OrderingFilter`. + +Default: `ordering` + --- ## Authentication settings -- cgit v1.2.3 From c779dce3e4bba8fc453e0abe51f6fb5b2f005721 Mon Sep 17 00:00:00 2001 From: Steven Cummings Date: Sun, 16 Mar 2014 18:55:21 -0500 Subject: Serializer fields section for 3rd-party packages * Add new section to serializer fields page where we can list and link 3rd-party packages that provide more field types * Add an entry for drf-compound-fields --- docs/api-guide/fields.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 93f992e6..89606798 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -2,7 +2,7 @@ # Serializer fields -> Each field in a Form class is responsible not only for validating data, but also for "cleaning" it — normalizing it to a consistent format. +> Each field in a Form class is responsible not only for validating data, but also for "cleaning" it — normalizing it to a consistent format. > > — [Django documentation][cite] @@ -47,7 +47,7 @@ Defaults to `True`. ### `default` -If set, this gives the default value that will be used for the field if no input value is supplied. If not set the default behavior is to not populate the attribute at all. +If set, this gives the default value that will be used for the field if no input value is supplied. If not set the default behavior is to not populate the attribute at all. May be set to a function or other callable, in which case the value will be evaluated each time it is used. @@ -92,7 +92,7 @@ For example, using the following model. name = models.CharField(max_length=100) created = models.DateTimeField(auto_now_add=True) payment_expiry = models.DateTimeField() - + def has_expired(self): return now() > self.payment_expiry @@ -102,7 +102,7 @@ A serializer definition that looked like this: class AccountSerializer(serializers.HyperlinkedModelSerializer): expired = serializers.Field(source='has_expired') - + class Meta: model = Account fields = ('url', 'owner', 'name', 'expired') @@ -112,7 +112,7 @@ Would produce output similar to: { 'url': 'http://example.com/api/accounts/3/', 'owner': 'http://example.com/api/users/12/', - 'name': 'FooCorp business account', + 'name': 'FooCorp business account', 'expired': True } @@ -224,7 +224,7 @@ In the case of JSON this means the default datetime representation uses the [ECM **Signature:** `DateTimeField(format=None, input_formats=None)` -* `format` - A string representing the output format. If not specified, this defaults to `None`, which indicates that Python `datetime` objects should be returned by `to_native`. In this case the datetime encoding will be determined by the renderer. +* `format` - A string representing the output format. If not specified, this defaults to `None`, which indicates that Python `datetime` objects should be returned by `to_native`. In this case the datetime encoding will be determined by the renderer. * `input_formats` - A list of strings representing the input formats which may be used to parse the date. If not specified, the `DATETIME_INPUT_FORMATS` setting will be used, which defaults to `['iso-8601']`. DateTime format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style datetimes should be used. (eg `'2013-01-29T12:34:56.000000Z'`) @@ -284,7 +284,7 @@ Corresponds to `django.forms.fields.FileField`. **Signature:** `FileField(max_length=None, allow_empty_file=False)` - `max_length` designates the maximum length for the file name. - + - `allow_empty_file` designates if empty files are allowed. ## ImageField @@ -329,12 +329,12 @@ Let's look at an example of serializing a class that represents an RGB color val """ def to_native(self, obj): return "rgb(%d, %d, %d)" % (obj.red, obj.green, obj.blue) - + def from_native(self, data): data = data.strip('rgb(').rstrip(')') red, green, blue = [int(col) for col in data.split(',')] return Color(red, green, blue) - + By default field values are treated as mapping to an attribute on the object. If you need to customize how the field value is accessed and set you need to override `.field_to_native()` and/or `.field_from_native()`. @@ -347,6 +347,14 @@ As an example, let's create a field that can be used represent the class name of """ return obj.__class__ +# More fields from 3rd-party packages + +## [drf-compound-fields](http://drf-compound-fields.readthedocs.org) + +Provides "compound" serializer fields, such as lists of simple values, which can be described by +other fields rather than serializers with the `many=True` option. Also provided are fields for +typed dictionaries and values that can be either a specific type or a list of items of that type. + [cite]: https://docs.djangoproject.com/en/dev/ref/forms/api/#django.forms.Form.cleaned_data [FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS [ecma262]: http://ecma-international.org/ecma-262/5.1/#sec-15.9.1.15 -- cgit v1.2.3 From dddbff59319bdefbf235f8a37af5b6ac20c4fec1 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 17 Mar 2014 08:33:18 +0000 Subject: Tweak DRF compound fields docs --- docs/api-guide/fields.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 89606798..b3d5b55a 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -347,16 +347,15 @@ As an example, let's create a field that can be used represent the class name of """ return obj.__class__ -# More fields from 3rd-party packages +# Third party packages -## [drf-compound-fields](http://drf-compound-fields.readthedocs.org) +## DRF Compound Fields -Provides "compound" serializer fields, such as lists of simple values, which can be described by -other fields rather than serializers with the `many=True` option. Also provided are fields for -typed dictionaries and values that can be either a specific type or a list of items of that type. +The [drf-compound-fields][drf-compound-fields] package provides "compound" serializer fields, such as lists of simple values, which can be described by other fields rather than serializers with the `many=True` option. Also provided are fields for typed dictionaries and values that can be either a specific type or a list of items of that type. [cite]: https://docs.djangoproject.com/en/dev/ref/forms/api/#django.forms.Form.cleaned_data [FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS [ecma262]: http://ecma-international.org/ecma-262/5.1/#sec-15.9.1.15 [strftime]: http://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior [iso8601]: http://www.w3.org/TR/NOTE-datetime +[drf-compound-fields]: http://drf-compound-fields.readthedocs.org -- cgit v1.2.3 From abe14c06f78de3b1ab20ed73f0ee5691f5224f94 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 17 Mar 2014 08:36:13 +0000 Subject: Minor docs tweak --- 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 b3d5b55a..67fa65d2 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -349,6 +349,8 @@ As an example, let's create a field that can be used represent the class name of # Third party packages +The following third party packages are also available. + ## DRF Compound Fields The [drf-compound-fields][drf-compound-fields] package provides "compound" serializer fields, such as lists of simple values, which can be described by other fields rather than serializers with the `many=True` option. Also provided are fields for typed dictionaries and values that can be either a specific type or a list of items of that type. -- cgit v1.2.3 From 3234a5dd6b0c090dd25a716e7b1c2567d8fee89b Mon Sep 17 00:00:00 2001 From: Craig Date: Tue, 8 Apr 2014 22:56:07 -0400 Subject: Fix python syntax in filtering docs --- docs/api-guide/filtering.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md index d6c4b1c1..6a8a267b 100644 --- a/docs/api-guide/filtering.md +++ b/docs/api-guide/filtering.md @@ -24,7 +24,7 @@ For example: from myapp.serializers import PurchaseSerializer from rest_framework import generics - class PurchaseList(generics.ListAPIView) + class PurchaseList(generics.ListAPIView): serializer_class = PurchaseSerializer def get_queryset(self): @@ -46,7 +46,7 @@ For example if your URL config contained an entry like this: You could then write a view that returned a purchase queryset filtered by the username portion of the URL: - class PurchaseList(generics.ListAPIView) + class PurchaseList(generics.ListAPIView): serializer_class = PurchaseSerializer def get_queryset(self): @@ -63,7 +63,7 @@ A final example of filtering the initial queryset would be to determine the init We can override `.get_queryset()` to deal with URLs such as `http://example.com/api/purchases?username=denvercoder9`, and filter the queryset only if the `username` parameter is included in the URL: - class PurchaseList(generics.ListAPIView) + class PurchaseList(generics.ListAPIView): serializer_class = PurchaseSerializer def get_queryset(self): -- cgit v1.2.3