From 062f5caef3dcb76e19f9eed59779f45849a166a1 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 1 Nov 2012 23:40:34 +0000 Subject: Tweaks fields docs, and fix 2.0.1 version. --- docs/api-guide/fields.md | 42 +++++++++++++++++++++++------------------- 1 file changed, 23 insertions(+), 19 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 8c3df067..86460b4b 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -235,44 +235,48 @@ Then an example output format for a Bookmark instance would be: 'url': u'https://www.djangoproject.com/' } -## PrimaryKeyRelatedField +## PrimaryKeyRelatedField / ManyPrimaryKeyRelatedField -This field can be applied to any "to-one" relationship, such as a `ForeignKey` field. +`PrimaryKeyRelatedField` and `ManyPrimaryKeyRelatedField` will represent the target of the relationship using it's primary key. -`PrimaryKeyRelatedField` will represent the target of the field using it's primary key. +Be default these fields read-write, although you can change this behaviour using the `read_only` flag. -Be default, `PrimaryKeyRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. +**Arguments**: -## ManyPrimaryKeyRelatedField +* `queryset` - All relational fields must either set a queryset, or set `read_only=True` -This field can be applied to any "to-many" relationship, such as a `ManyToManyField` field, or a reverse `ForeignKey` relationship. +## SlugRelatedField / ManySlugRelatedField -`PrimaryKeyRelatedField` will represent the targets of the field using their primary key. +`SlugRelatedField` and `ManySlugRelatedField` will represent the target of the relationship using a unique slug. -Be default, `ManyPrimaryKeyRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. +Be default these fields read-write, although you can change this behaviour using the `read_only` flag. -## HyperlinkedRelatedField +**Arguments**: -This field can be applied to any "to-one" relationship, such as a `ForeignKey` field. +* `slug_field` - The field on the target that should used as the representation. This should be a field that uniquely identifies any given instance. For example, `username`. +* `queryset` - All relational fields must either set a queryset, or set `read_only=True` -`HyperlinkedRelatedField` will represent the target of the field using a hyperlink. You must include a named URL pattern in your URL conf, with a name like `'{model-name}-detail'` that corresponds to the target of the hyperlink. +## HyperlinkedRelatedField / ManyHyperlinkedRelatedField -Be default, `HyperlinkedRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. - -## ManyHyperlinkedRelatedField +`HyperlinkedRelatedField` and `ManyHyperlinkedRelatedField` will represent the target of the relationship using a hyperlink. -This field can be applied to any "to-many" relationship, such as a `ManyToManyField` field, or a reverse `ForeignKey` relationship. +Be default, `HyperlinkedRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. -`ManyHyperlinkedRelatedField` will represent the targets of the field using hyperlinks. You must include a named URL pattern in your URL conf, with a name like `'{model-name}-detail'` that corresponds to the target of the hyperlink. +**Arguments**: -Be default, `ManyHyperlinkedRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. +* `view_name` - The view name that should be used as the target of the relationship. **required**. +* `format` - If using format suffixes, hyperlinked fields will use the same format suffix for the target unless overridden by using the `format` argument. +* `queryset` - All relational fields must either set a queryset, or set `read_only=True` ## HyperLinkedIdentityField This field can be applied as an identity relationship, such as the `'url'` field on a HyperlinkedModelSerializer. -You must include a named URL pattern in your URL conf, with a name like `'{model-name}-detail'` that corresponds to the model. - This field is always read-only. +**Arguments**: + +* `view_name` - The view name that should be used as the target of the relationship. **required**. +* `format` - If using format suffixes, hyperlinked fields will use the same format suffix for the target unless overridden by using the `format` argument. + [cite]: http://www.python.org/dev/peps/pep-0020/ -- cgit v1.2.3 From b7b942c5991e677e7df621c00befb075d06edd61 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 5 Nov 2012 10:53:20 +0000 Subject: Swap position of `instance` and `data` keyword arguments. --- docs/api-guide/serializers.md | 29 ++++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index c88b9b0c..ee7f72dd 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -47,7 +47,7 @@ The first part of serializer class defines the fields that get serialized/deseri We can now use `CommentSerializer` to serialize a comment, or list of comments. Again, using the `Serializer` class looks a lot like using a `Form` class. - serializer = CommentSerializer(instance=comment) + serializer = CommentSerializer(comment) serializer.data # {'email': u'leila@example.com', 'content': u'foo bar', 'created': datetime.datetime(2012, 8, 22, 16, 20, 9, 822774)} @@ -65,20 +65,29 @@ Deserialization is similar. First we parse a stream into python native datatype ...then we restore those native datatypes into a fully populated object instance. - serializer = CommentSerializer(data) + serializer = CommentSerializer(data=data) serializer.is_valid() # True serializer.object # >>> serializer.deserialize('json', stream) +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` + ## Validation When deserializing data, you always need to call `is_valid()` before attempting to access the deserialized object. If any validation errors occur, the `.errors` and `.non_field_errors` properties will contain the resulting error messages. ### Field-level validation -You can specify custom field-level validation by adding `validate_()` methods to your `Serializer` subclass. These are analagous to `clean_` methods on Django forms, but accept slightly different arguments. They take a dictionary of deserialized attributes as a first argument, and the field name in that dictionary as a second argument (which will be either the name of the field or the value of the `source` argument to the field, if one was provided). Your `validate_` methods should either just return the attrs dictionary or raise a `ValidationError`. For example: +You can specify custom field-level validation by adding `.validate_` methods to your `Serializer` subclass. These are analagous to `.clean_` methods on Django forms, but accept slightly different arguments. + +They take a dictionary of deserialized attributes as a first argument, and the field name in that dictionary as a second argument (which will be either the name of the field or the value of the `source` argument to the field, if one was provided). + +Your `validate_` methods should either just return the `attrs` dictionary or raise a `ValidationError`. For example: from rest_framework import serializers @@ -88,16 +97,22 @@ You can specify custom field-level validation by adding `validate_()` def validate_title(self, attrs, source): """ - Check that the blog post is about Django + Check that the blog post is about Django. """ value = attrs[source] - if "Django" not in value: + if "django" not in value.lower(): raise serializers.ValidationError("Blog post is not about Django") return attrs -### Final cross-field validation +### Object-level validation + +To do any other validation that requires access to multiple fields, add a method called `.validate()` to your `Serializer` subclass. This method takes a single argument, which is the `attrs` dictionary. It should raise a `ValidationError` if necessary, or just return `attrs`. + +## Saving object state + +Serializers also include a `.save()` method that you can override if you want to provide a method of persisting the state of a deserialized object. The default behavior of the method is to simply call `.save()` on the deserialized object instance. -To do any other validation that requires access to multiple fields, add a method called `validate` to your `Serializer` subclass. This method takes a single argument, which is the `attrs` dictionary. It should raise a `ValidationError` if necessary, or just return `attrs`. +The generic views provided by REST framework call the `.save()` method when updating or creating entities. ## Dealing with nested objects -- cgit v1.2.3 From 85b176cf47cd0d4f392ee0a4bae971c709dbfddc Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Mon, 5 Nov 2012 16:51:49 +0100 Subject: added docs --- 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 86460b4b..3126c0c2 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -267,6 +267,8 @@ Be default, `HyperlinkedRelatedField` is read-write, although you can change thi * `view_name` - The view name that should be used as the target of the relationship. **required**. * `format` - If using format suffixes, hyperlinked fields will use the same format suffix for the target unless overridden by using the `format` argument. * `queryset` - All relational fields must either set a queryset, or set `read_only=True` +* `slug_url_kwarg` - The named url parameter for the slug field lookup. Default is `slug` +* `slug_field` - The field on the target that should be used for the lookup. Default is `slug` ## HyperLinkedIdentityField -- cgit v1.2.3 From 1418d104a86a0c861a9d3b9831f7bb98b0891f57 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 5 Nov 2012 16:44:26 +0000 Subject: Tweak related field docs now that queryset is no longer required. --- docs/api-guide/fields.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 3126c0c2..fe621335 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -243,7 +243,7 @@ Be default these fields read-write, although you can change this behaviour using **Arguments**: -* `queryset` - All relational fields must either set a queryset, or set `read_only=True` +* `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`. ## SlugRelatedField / ManySlugRelatedField @@ -254,7 +254,7 @@ Be default these fields read-write, although you can change this behaviour using **Arguments**: * `slug_field` - The field on the target that should used as the representation. This should be a field that uniquely identifies any given instance. For example, `username`. -* `queryset` - All relational fields must either set a queryset, or set `read_only=True` +* `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`. ## HyperlinkedRelatedField / ManyHyperlinkedRelatedField @@ -266,9 +266,9 @@ Be default, `HyperlinkedRelatedField` is read-write, although you can change thi * `view_name` - The view name that should be used as the target of the relationship. **required**. * `format` - If using format suffixes, hyperlinked fields will use the same format suffix for the target unless overridden by using the `format` argument. -* `queryset` - All relational fields must either set a queryset, or set `read_only=True` -* `slug_url_kwarg` - The named url parameter for the slug field lookup. Default is `slug` -* `slug_field` - The field on the target that should be used for the lookup. Default is `slug` +* `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`. +* `slug_field` - The field on the target that should be used for the lookup. Default is `'slug'`. +* `slug_url_kwarg` - The named url parameter for the slug field lookup. Default is to use the same value as given for `slug_field`. ## HyperLinkedIdentityField -- cgit v1.2.3 From 455a8cedcf5aa1f265ae95d4f3bff359d51910c0 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 5 Nov 2012 17:03:22 +0000 Subject: Tweaks --- docs/api-guide/fields.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index fe621335..411f7944 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -239,7 +239,7 @@ Then an example output format for a Bookmark instance would be: `PrimaryKeyRelatedField` and `ManyPrimaryKeyRelatedField` will represent the target of the relationship using it's primary key. -Be default these fields read-write, although you can change this behaviour using the `read_only` flag. +By default these fields are read-write, although you can change this behaviour using the `read_only` flag. **Arguments**: @@ -249,18 +249,18 @@ Be default these fields read-write, although you can change this behaviour using `SlugRelatedField` and `ManySlugRelatedField` will represent the target of the relationship using a unique slug. -Be default these fields read-write, although you can change this behaviour using the `read_only` flag. +By default these fields read-write, although you can change this behaviour using the `read_only` flag. **Arguments**: -* `slug_field` - The field on the target that should used as the representation. This should be a field that uniquely identifies any given instance. For example, `username`. +* `slug_field` - The field on the target that should be used to represent it. This should be a field that uniquely identifies any given instance. For example, `username`. * `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`. ## HyperlinkedRelatedField / ManyHyperlinkedRelatedField `HyperlinkedRelatedField` and `ManyHyperlinkedRelatedField` will represent the target of the relationship using a hyperlink. -Be default, `HyperlinkedRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. +By default, `HyperlinkedRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. **Arguments**: -- cgit v1.2.3