diff options
| -rw-r--r-- | docs/api-guide/relations.md | 12 | ||||
| -rw-r--r-- | rest_framework/relations.py | 4 |
2 files changed, 14 insertions, 2 deletions
diff --git a/docs/api-guide/relations.md b/docs/api-guide/relations.md index 7d19eba2..17009bbc 100644 --- a/docs/api-guide/relations.md +++ b/docs/api-guide/relations.md @@ -245,7 +245,7 @@ For example, the following serializer: fields = ('order', 'title') class AlbumSerializer(serializers.ModelSerializer): - tracks = TrackSerializer(many=True) + tracks = TrackSerializer(many=True, read_only=True) class Meta: model = Album @@ -305,6 +305,16 @@ This custom field would then serialize to the following representation. # Further notes +## The `queryset` argument + +The `queryset` argument is only ever required for *writable* relationship field, in which case it is used for performing the model instance lookup, that maps from the primitive user input, into a model instance. + +In version 2.x a serializer class could *sometimes* automatically determine the `queryset` argument *if* a `ModelSerializer` class was being used. + +This behavior is now replaced with *always* using an explicit `queryset` argument for writable relational fields. + +Doing so reduces the amount of hidden 'magic' that `ModelSerializer` provides, makes the behavior of the field more clear, and ensures that it is trivial to move between using the `ModelSerializer` shortcut, or using fully explicit `Serializer` classes. + ## Reverse relations Note that reverse relationships are not automatically included by the `ModelSerializer` and `HyperlinkedModelSerializer` classes. To include a reverse relationship, you must explicitly add it to the fields list. For example: diff --git a/rest_framework/relations.py b/rest_framework/relations.py index 5a3403f5..d1ea497a 100644 --- a/rest_framework/relations.py +++ b/rest_framework/relations.py @@ -321,7 +321,9 @@ class ManyRelatedField(Field): The `ManyRelatedField` class is responsible for handling iterating through the values and passing each one to the child relationship. - You shouldn't need to be using this class directly yourself. + This class is treated as private API. + You shouldn't generally need to be using this class directly yourself, + and should instead simply set 'many=True' on the relationship. """ initial = [] default_empty_html = [] |