<ahref="#customizing-the-html-display">Customizing the HTML display</a>
</li>
<li>
<ahref="#reverse-relations">Reverse relations</a>
<ahref="#reverse-relations">Reverse relations</a>
</li>
</li>
...
@@ -806,6 +810,13 @@ class CustomerHyperlink(serializers.HyperlinkedRelatedField):
...
@@ -806,6 +810,13 @@ class CustomerHyperlink(serializers.HyperlinkedRelatedField):
<p>In version 2.x a serializer class could <em>sometimes</em> automatically determine the <code>queryset</code> argument <em>if</em> a <code>ModelSerializer</code> class was being used.</p>
<p>In version 2.x a serializer class could <em>sometimes</em> automatically determine the <code>queryset</code> argument <em>if</em> a <code>ModelSerializer</code> class was being used.</p>
<p>This behavior is now replaced with <em>always</em> using an explicit <code>queryset</code> argument for writable relational fields.</p>
<p>This behavior is now replaced with <em>always</em> using an explicit <code>queryset</code> argument for writable relational fields.</p>
<p>Doing so reduces the amount of hidden 'magic' that <code>ModelSerializer</code> provides, makes the behavior of the field more clear, and ensures that it is trivial to move between using the <code>ModelSerializer</code> shortcut, or using fully explicit <code>Serializer</code> classes.</p>
<p>Doing so reduces the amount of hidden 'magic' that <code>ModelSerializer</code> provides, makes the behavior of the field more clear, and ensures that it is trivial to move between using the <code>ModelSerializer</code> shortcut, or using fully explicit <code>Serializer</code> classes.</p>
<h2id="customizing-the-html-display">Customizing the HTML display</h2>
<p>The built-in <code>__str__</code> method of the model will be used to generate string representations of the objects used to populate the <code>choices</code> property. These choices are used to populate select HTML inputs in the browsable API.</p>
<p>To provide customized representations for such inputs, override <code>display_value()</code> of a <code>RelatedField</code> subclass. This method will receive a model object, and should return a string suitable for representing it. For example:</p>
<p>Note that reverse relationships are not automatically included by the <code>ModelSerializer</code> and <code>HyperlinkedModelSerializer</code> classes. To include a reverse relationship, you must explicitly add it to the fields list. For example:</p>
<p>Note that reverse relationships are not automatically included by the <code>ModelSerializer</code> and <code>HyperlinkedModelSerializer</code> classes. To include a reverse relationship, you must explicitly add it to the fields list. For example:</p>
<p><code>request.query_params</code> is a more correctly named synonym for <code>request.GET</code>.</p>
<p><code>request.query_params</code> is a more correctly named synonym for <code>request.GET</code>.</p>
<p>For clarity inside your code, we recommend using <code>request.query_params</code> instead of the Django's standard <code>request.GET</code>. Doing so will help keep your codebase more correct and obvious - any HTTP method type may include query parameters, not just <code>GET</code> requests.</p>
<p>For clarity inside your code, we recommend using <code>request.query_params</code> instead of the Django's standard <code>request.GET</code>. Doing so will help keep your codebase more correct and obvious - any HTTP method type may include query parameters, not just <code>GET</code> requests.</p>
<h2id="data-and-files">.DATA and .FILES</h2>
<p>The old-style version 2.x <code>request.DATA</code> and <code>request.FILES</code> attributes are still available, but are now pending deprecation in favor of the unified <code>request.data</code> attribute.</p>
<h2id="query_params_1">.QUERY_PARAMS</h2>
<p>The old-style version 2.x <code>request.QUERY_PARAMS</code> attribute is still available, but is now pending deprecation in favor of the more pythonic <code>request.query_params</code>.</p>
<h2id="parsers">.parsers</h2>
<h2id="parsers">.parsers</h2>
<p>The <code>APIView</code> class or <code>@api_view</code> decorator will ensure that this property is automatically set to a list of <code>Parser</code> instances, based on the <code>parser_classes</code> set on the view or based on the <code>DEFAULT_PARSER_CLASSES</code> setting.</p>
<p>The <code>APIView</code> class or <code>@api_view</code> decorator will ensure that this property is automatically set to a list of <code>Parser</code> instances, based on the <code>parser_classes</code> set on the view or based on the <code>DEFAULT_PARSER_CLASSES</code> setting.</p>
<p>You won't typically need to access this property.</p>
<p>You won't typically need to access this property.</p>
"text":"Requests\n\n\n\n\nIf you're doing REST-based web service stuff ... you should ignore request.POST.\n\n\n Malcom Tredinnick, \nDjango developers group\n\n\n\n\nREST framework's \nRequest\n class extends the standard \nHttpRequest\n, adding support for REST framework's flexible request parsing and request authentication.\n\n\n\n\nRequest parsing\n\n\nREST framework's Request objects provide flexible request parsing that allows you to treat requests with JSON data or other media types in the same way that you would normally deal with form data.\n\n\n.data\n\n\nrequest.data\n returns the parsed content of the request body. This is similar to the standard \nrequest.POST\n and \nrequest.FILES\n attributes except that:\n\n\n\n\nIt includes all parsed content, including \nfile and non-file\n inputs.\n\n\nIt supports parsing the content of HTTP methods other than \nPOST\n, meaning that you can access the content of \nPUT\n and \nPATCH\n requests.\n\n\nIt supports REST framework's flexible request parsing, rather than just supporting form data. For example you can handle incoming JSON data in the same way that you handle incoming form data.\n\n\n\n\nFor more details see the \nparsers documentation\n.\n\n\n.query_params\n\n\nrequest.query_params\n is a more correctly named synonym for \nrequest.GET\n.\n\n\nFor clarity inside your code, we recommend using \nrequest.query_params\n instead of the Django's standard \nrequest.GET\n. Doing so will help keep your codebase more correct and obvious - any HTTP method type may include query parameters, not just \nGET\n requests.\n\n\n.DATA and .FILES\n\n\nThe old-style version 2.x \nrequest.DATA\n and \nrequest.FILES\n attributes are still available, but are now pending deprecation in favor of the unified \nrequest.data\n attribute.\n\n\n.QUERY_PARAMS\n\n\nThe old-style version 2.x \nrequest.QUERY_PARAMS\n attribute is still available, but is now pending deprecation in favor of the more pythonic \nrequest.query_params\n.\n\n\n.parsers\n\n\nThe \nAPIView\n class or \n@api_view\n decorator will ensure that this property is automatically set to a list of \nParser\n instances, based on the \nparser_classes\n set on the view or based on the \nDEFAULT_PARSER_CLASSES\n setting.\n\n\nYou won't typically need to access this property.\n\n\n\n\nNote:\n If a client sends malformed content, then accessing \nrequest.data\n may raise a \nParseError\n. By default REST framework's \nAPIView\n class or \n@api_view\n decorator will catch the error and return a \n400 Bad Request\n response.\n\n\nIf a client sends a request with a content-type that cannot be parsed then a \nUnsupportedMediaType\n exception will be raised, which by default will be caught and return a \n415 Unsupported Media Type\n response.\n\n\n\n\nContent negotiation\n\n\nThe request exposes some properties that allow you to determine the result of the content negotiation stage. This allows you to implement behaviour such as selecting a different serialisation schemes for different media types.\n\n\n.accepted_renderer\n\n\nThe renderer instance what was selected by the content negotiation stage.\n\n\n.accepted_media_type\n\n\nA string representing the media type that was accepted by the content negotiation stage.\n\n\n\n\nAuthentication\n\n\nREST framework provides flexible, per-request authentication, that gives you the ability to:\n\n\n\n\nUse different authentication policies for different parts of your API.\n\n\nSupport the use of multiple authentication policies.\n\n\nProvide both user and token information associated with the incoming request.\n\n\n\n\n.user\n\n\nrequest.user\n typically returns an instance of \ndjango.contrib.auth.models.User\n, although the behavior depends on the authentication policy being used.\n\n\nIf the request is unauthenticated the default value of \nrequest.user\n is an instance of \ndjango.contrib.auth.models.AnonymousUser\n.\n\n\nFor more details see the \nauthentication documentation\n.\n\n\n.auth\n\n\nrequest.auth\n returns any additional authentication context. The exact behavior of \nrequest.auth\n depends on the authentication policy being used, but it may typically be an instance of the token that the request was authenticated against.\n\n\nIf the request is unauthenticated, or if no additional context is present, the default value of \nrequest.auth\n is \nNone\n.\n\n\nFor more details see the \nauthentication documentation\n.\n\n\n.authenticators\n\n\nThe \nAPIView\n class or \n@api_view\n decorator will ensure that this property is automatically set to a list of \nAuthentication\n instances, based on the \nauthentication_classes\n set on the view or based on the \nDEFAULT_AUTHENTICATORS\n setting.\n\n\nYou won't typically need to access this property.\n\n\n\n\nBrowser enhancements\n\n\nREST framework supports a few browser enhancements such as browser-based \nPUT\n, \nPATCH\n and \nDELETE\n forms.\n\n\n.method\n\n\nrequest.method\n returns the \nuppercased\n string representation of the request's HTTP method.\n\n\nBrowser-based \nPUT\n, \nPATCH\n and \nDELETE\n forms are transparently supported.\n\n\nFor more information see the \nbrowser enhancements documentation\n.\n\n\n.content_type\n\n\nrequest.content_type\n, returns a string object representing the media type of the HTTP request's body, or an empty string if no media type was provided.\n\n\nYou won't typically need to directly access the request's content type, as you'll normally rely on REST framework's default request parsing behavior.\n\n\nIf you do need to access the content type of the request you should use the \n.content_type\n property in preference to using \nrequest.META.get('HTTP_CONTENT_TYPE')\n, as it provides transparent support for browser-based non-form content.\n\n\nFor more information see the \nbrowser enhancements documentation\n.\n\n\n.stream\n\n\nrequest.stream\n returns a stream representing the content of the request body.\n\n\nYou won't typically need to directly access the request's content, as you'll normally rely on REST framework's default request parsing behavior.\n\n\nIf you do need to access the raw content directly, you should use the \n.stream\n property in preference to using \nrequest.content\n, as it provides transparent support for browser-based non-form content.\n\n\nFor more information see the \nbrowser enhancements documentation\n.\n\n\n\n\nStandard HttpRequest attributes\n\n\nAs REST framework's \nRequest\n extends Django's \nHttpRequest\n, all the other standard attributes and methods are also available. For example the \nrequest.META\n and \nrequest.session\n dictionaries are available as normal.\n\n\nNote that due to implementation reasons the \nRequest\n class does not inherit from \nHttpRequest\n class, but instead extends the class using composition.",
"text":"Requests\n\n\n\n\nIf you're doing REST-based web service stuff ... you should ignore request.POST.\n\n\n Malcom Tredinnick, \nDjango developers group\n\n\n\n\nREST framework's \nRequest\n class extends the standard \nHttpRequest\n, adding support for REST framework's flexible request parsing and request authentication.\n\n\n\n\nRequest parsing\n\n\nREST framework's Request objects provide flexible request parsing that allows you to treat requests with JSON data or other media types in the same way that you would normally deal with form data.\n\n\n.data\n\n\nrequest.data\n returns the parsed content of the request body. This is similar to the standard \nrequest.POST\n and \nrequest.FILES\n attributes except that:\n\n\n\n\nIt includes all parsed content, including \nfile and non-file\n inputs.\n\n\nIt supports parsing the content of HTTP methods other than \nPOST\n, meaning that you can access the content of \nPUT\n and \nPATCH\n requests.\n\n\nIt supports REST framework's flexible request parsing, rather than just supporting form data. For example you can handle incoming JSON data in the same way that you handle incoming form data.\n\n\n\n\nFor more details see the \nparsers documentation\n.\n\n\n.query_params\n\n\nrequest.query_params\n is a more correctly named synonym for \nrequest.GET\n.\n\n\nFor clarity inside your code, we recommend using \nrequest.query_params\n instead of the Django's standard \nrequest.GET\n. Doing so will help keep your codebase more correct and obvious - any HTTP method type may include query parameters, not just \nGET\n requests.\n\n\n.parsers\n\n\nThe \nAPIView\n class or \n@api_view\n decorator will ensure that this property is automatically set to a list of \nParser\n instances, based on the \nparser_classes\n set on the view or based on the \nDEFAULT_PARSER_CLASSES\n setting.\n\n\nYou won't typically need to access this property.\n\n\n\n\nNote:\n If a client sends malformed content, then accessing \nrequest.data\n may raise a \nParseError\n. By default REST framework's \nAPIView\n class or \n@api_view\n decorator will catch the error and return a \n400 Bad Request\n response.\n\n\nIf a client sends a request with a content-type that cannot be parsed then a \nUnsupportedMediaType\n exception will be raised, which by default will be caught and return a \n415 Unsupported Media Type\n response.\n\n\n\n\nContent negotiation\n\n\nThe request exposes some properties that allow you to determine the result of the content negotiation stage. This allows you to implement behaviour such as selecting a different serialisation schemes for different media types.\n\n\n.accepted_renderer\n\n\nThe renderer instance what was selected by the content negotiation stage.\n\n\n.accepted_media_type\n\n\nA string representing the media type that was accepted by the content negotiation stage.\n\n\n\n\nAuthentication\n\n\nREST framework provides flexible, per-request authentication, that gives you the ability to:\n\n\n\n\nUse different authentication policies for different parts of your API.\n\n\nSupport the use of multiple authentication policies.\n\n\nProvide both user and token information associated with the incoming request.\n\n\n\n\n.user\n\n\nrequest.user\n typically returns an instance of \ndjango.contrib.auth.models.User\n, although the behavior depends on the authentication policy being used.\n\n\nIf the request is unauthenticated the default value of \nrequest.user\n is an instance of \ndjango.contrib.auth.models.AnonymousUser\n.\n\n\nFor more details see the \nauthentication documentation\n.\n\n\n.auth\n\n\nrequest.auth\n returns any additional authentication context. The exact behavior of \nrequest.auth\n depends on the authentication policy being used, but it may typically be an instance of the token that the request was authenticated against.\n\n\nIf the request is unauthenticated, or if no additional context is present, the default value of \nrequest.auth\n is \nNone\n.\n\n\nFor more details see the \nauthentication documentation\n.\n\n\n.authenticators\n\n\nThe \nAPIView\n class or \n@api_view\n decorator will ensure that this property is automatically set to a list of \nAuthentication\n instances, based on the \nauthentication_classes\n set on the view or based on the \nDEFAULT_AUTHENTICATORS\n setting.\n\n\nYou won't typically need to access this property.\n\n\n\n\nBrowser enhancements\n\n\nREST framework supports a few browser enhancements such as browser-based \nPUT\n, \nPATCH\n and \nDELETE\n forms.\n\n\n.method\n\n\nrequest.method\n returns the \nuppercased\n string representation of the request's HTTP method.\n\n\nBrowser-based \nPUT\n, \nPATCH\n and \nDELETE\n forms are transparently supported.\n\n\nFor more information see the \nbrowser enhancements documentation\n.\n\n\n.content_type\n\n\nrequest.content_type\n, returns a string object representing the media type of the HTTP request's body, or an empty string if no media type was provided.\n\n\nYou won't typically need to directly access the request's content type, as you'll normally rely on REST framework's default request parsing behavior.\n\n\nIf you do need to access the content type of the request you should use the \n.content_type\n property in preference to using \nrequest.META.get('HTTP_CONTENT_TYPE')\n, as it provides transparent support for browser-based non-form content.\n\n\nFor more information see the \nbrowser enhancements documentation\n.\n\n\n.stream\n\n\nrequest.stream\n returns a stream representing the content of the request body.\n\n\nYou won't typically need to directly access the request's content, as you'll normally rely on REST framework's default request parsing behavior.\n\n\nIf you do need to access the raw content directly, you should use the \n.stream\n property in preference to using \nrequest.content\n, as it provides transparent support for browser-based non-form content.\n\n\nFor more information see the \nbrowser enhancements documentation\n.\n\n\n\n\nStandard HttpRequest attributes\n\n\nAs REST framework's \nRequest\n extends Django's \nHttpRequest\n, all the other standard attributes and methods are also available. For example the \nrequest.META\n and \nrequest.session\n dictionaries are available as normal.\n\n\nNote that due to implementation reasons the \nRequest\n class does not inherit from \nHttpRequest\n class, but instead extends the class using composition.",
"title":"Requests"
"title":"Requests"
},
},
{
{
...
@@ -396,16 +396,6 @@
...
@@ -396,16 +396,6 @@
"title":".query_params"
"title":".query_params"
},
},
{
{
"location":"/api-guide/requests/#data-and-files",
"text":"The old-style version 2.x request.DATA and request.FILES attributes are still available, but are now pending deprecation in favor of the unified request.data attribute.",
"title":".DATA and .FILES"
},
{
"location":"/api-guide/requests/#query_params_1",
"text":"The old-style version 2.x request.QUERY_PARAMS attribute is still available, but is now pending deprecation in favor of the more pythonic request.query_params .",
"title":".QUERY_PARAMS"
},
{
"location":"/api-guide/requests/#parsers",
"location":"/api-guide/requests/#parsers",
"text":"The APIView class or @api_view decorator will ensure that this property is automatically set to a list of Parser instances, based on the parser_classes set on the view or based on the DEFAULT_PARSER_CLASSES setting. You won't typically need to access this property. Note: If a client sends malformed content, then accessing request.data may raise a ParseError . By default REST framework's APIView class or @api_view decorator will catch the error and return a 400 Bad Request response. If a client sends a request with a content-type that cannot be parsed then a UnsupportedMediaType exception will be raised, which by default will be caught and return a 415 Unsupported Media Type response.",
"text":"The APIView class or @api_view decorator will ensure that this property is automatically set to a list of Parser instances, based on the parser_classes set on the view or based on the DEFAULT_PARSER_CLASSES setting. You won't typically need to access this property. Note: If a client sends malformed content, then accessing request.data may raise a ParseError . By default REST framework's APIView class or @api_view decorator will catch the error and return a 400 Bad Request response. If a client sends a request with a content-type that cannot be parsed then a UnsupportedMediaType exception will be raised, which by default will be caught and return a 415 Unsupported Media Type response.",
"title":".parsers"
"title":".parsers"
...
@@ -1487,7 +1477,7 @@
...
@@ -1487,7 +1477,7 @@
},
},
{
{
"location":"/api-guide/relations/",
"location":"/api-guide/relations/",
"text":"Serializer relations\n\n\n\n\nBad programmers worry about the code.\nGood programmers worry about data structures and their relationships.\n\n\n\nLinus Torvalds\n\n\n\n\nRelational fields are used to represent model relationships. They can be applied to \nForeignKey\n, \nManyToManyField\n and \nOneToOneField\n relationships, as well as to reverse relationships, and custom relationships such as \nGenericForeignKey\n.\n\n\n\n\nNote:\n The relational fields are declared in \nrelations.py\n, but by convention you should import them from the \nserializers\n module, using \nfrom rest_framework import serializers\n and refer to fields as \nserializers.\nFieldName\n.\n\n\n\n\nInspecting automatically generated relationships.\n\n\nWhen using the \nModelSerializer\n class, serializer fields and relationships will be automatically generated for you. Inspecting these automatically generated fields can be a useful tool for determining how to customize the relationship style.\n\n\nTo do so, open the Django shell, using \npython manage.py shell\n, then import the serializer class, instantiate it, and print the object representation\u2026\n\n\n from myapp.serializers import AccountSerializer\n\n serializer = AccountSerializer()\n\n print repr(serializer) # Or `print(repr(serializer))` in Python 3.x.\nAccountSerializer():\n id = IntegerField(label='ID', read_only=True)\n name = CharField(allow_blank=True, max_length=100, required=False)\n owner = PrimaryKeyRelatedField(queryset=User.objects.all())\n\n\n\nAPI Reference\n\n\nIn order to explain the various types of relational fields, we'll use a couple of simple models for our examples. Our models will be for music albums, and the tracks listed on each album.\n\n\nclass Album(models.Model):\n album_name = models.CharField(max_length=100)\n artist = models.CharField(max_length=100)\n\nclass Track(models.Model):\n album = models.ForeignKey(Album, related_name='tracks')\n order = models.IntegerField()\n title = models.CharField(max_length=100)\n duration = models.IntegerField()\n\n class Meta:\n unique_together = ('album', 'order')\n ordering = ['order']\n\n def __unicode__(self):\n return '%d: %s' % (self.order, self.title)\n\n\n\nStringRelatedField\n\n\nStringRelatedField\n may be used to represent the target of the relationship using its \n__unicode__\n method.\n\n\nFor example, the following serializer.\n\n\nclass AlbumSerializer(serializers.ModelSerializer):\n tracks = serializers.StringRelatedField(many=True)\n\n class Meta:\n model = Album\n fields = ('album_name', 'artist', 'tracks')\n\n\n\nWould serialize to the following representation.\n\n\n{\n 'album_name': 'Things We Lost In The Fire',\n 'artist': 'Low',\n 'tracks': [\n '1: Sunflower',\n '2: Whitetail',\n '3: Dinosaur Act',\n ...\n ]\n}\n\n\n\nThis field is read only.\n\n\nArguments\n:\n\n\n\n\nmany\n - If applied to a to-many relationship, you should set this argument to \nTrue\n.\n\n\n\n\nPrimaryKeyRelatedField\n\n\nPrimaryKeyRelatedField\n may be used to represent the target of the relationship using its primary key.\n\n\nFor example, the following serializer:\n\n\nclass AlbumSerializer(serializers.ModelSerializer):\n tracks = serializers.PrimaryKeyRelatedField(many=True, read_only=True)\n\n class Meta:\n model = Album\n fields = ('album_name', 'artist', 'tracks')\n\n\n\nWould serialize to a representation like this:\n\n\n{\n 'album_name': 'The Roots',\n 'artist': 'Undun',\n 'tracks': [\n 89,\n 90,\n 91,\n ...\n ]\n}\n\n\n\nBy default this field is read-write, although you can change this behavior using the \nread_only\n flag.\n\n\nArguments\n:\n\n\n\n\nqueryset\n - The queryset used for model instance lookups when validating the field input. Relationships must either set a queryset explicitly, or set \nread_only=True\n.\n\n\nmany\n - If applied to a to-many relationship, you should set this argument to \nTrue\n.\n\n\nallow_null\n - If set to \nTrue\n, the field will accept values of \nNone\n or the empty string for nullable relationships. Defaults to \nFalse\n.\n\n\npk_field\n - Set to a field to control serialization/deserialization of the primary key's value. For example, \npk_field=UUIDField(format='hex')\n would serialize a UUID primary key into its compact hex representation.\n\n\n\n\nHyperlinkedRelatedField\n\n\nHyperlinkedRelatedField\n may be used to represent the target of the relationship using a hyperlink.\n\n\nFor example, the following serializer:\n\n\nclass AlbumSerializer(serializers.ModelSerializer):\n tracks = serializers.HyperlinkedRelatedField(\n many=True,\n read_only=True,\n view_name='track-detail'\n )\n\n class Meta:\n model = Album\n fields = ('album_name', 'artist', 'tracks')\n\n\n\nWould serialize to a representation like this:\n\n\n{\n 'album_name': 'Graceland',\n 'artist': 'Paul Simon',\n 'tracks': [\n 'http://www.example.com/api/tracks/45/',\n 'http://www.example.com/api/tracks/46/',\n 'http://www.example.com/api/tracks/47/',\n ...\n ]\n}\n\n\n\nBy default this field is read-write, although you can change this behavior using the \nread_only\n flag.\n\n\n\n\nNote\n: This field is designed for objects that map to a URL that accepts a single URL keyword argument, as set using the \nlookup_field\n and \nlookup_url_kwarg\n arguments.\n\n\nThis is suitable for URLs that contain a single primary key or slug argument as part of the URL.\n\n\nIf you require more complex hyperlinked representation you'll need to customize the field, as described in the \ncustom hyperlinked fields\n section, below.\n\n\n\n\nArguments\n:\n\n\n\n\nview_name\n - The view name that should be used as the target of the relationship. If you're using \nthe standard router classes\n this will be a string with the format \nmodelname\n-detail\n. \nrequired\n.\n\n\nqueryset\n - The queryset used for model instance lookups when validating the field input. Relationships must either set a queryset explicitly, or set \nread_only=True\n.\n\n\nmany\n - If applied to a to-many relationship, you should set this argument to \nTrue\n.\n\n\nallow_null\n - If set to \nTrue\n, the field will accept values of \nNone\n or the empty string for nullable relationships. Defaults to \nFalse\n.\n\n\nlookup_field\n - 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 \n'pk'\n.\n\n\nlookup_url_kwarg\n - The name of the keyword argument defined in the URL conf that corresponds to the lookup field. Defaults to using the same value as \nlookup_field\n.\n\n\nformat\n - If using format suffixes, hyperlinked fields will use the same format suffix for the target unless overridden by using the \nformat\n argument.\n\n\n\n\nSlugRelatedField\n\n\nSlugRelatedField\n may be used to represent the target of the relationship using a field on the target.\n\n\nFor example, the following serializer:\n\n\nclass AlbumSerializer(serializers.ModelSerializer):\n tracks = serializers.SlugRelatedField(\n many=True,\n read_only=True,\n slug_field='title'\n )\n\n class Meta:\n model = Album\n fields = ('album_name', 'artist', 'tracks')\n\n\n\nWould serialize to a representation like this:\n\n\n{\n 'album_name': 'Dear John',\n 'artist': 'Loney Dear',\n 'tracks': [\n 'Airport Surroundings',\n 'Everything Turns to You',\n 'I Was Only Going Out',\n ...\n ]\n}\n\n\n\nBy default this field is read-write, although you can change this behavior using the \nread_only\n flag.\n\n\nWhen using \nSlugRelatedField\n as a read-write field, you will normally want to ensure that the slug field corresponds to a model field with \nunique=True\n.\n\n\nArguments\n:\n\n\n\n\nslug_field\n - 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, \nusername\n. \nrequired\n\n\nqueryset\n - The queryset used for model instance lookups when validating the field input. Relationships must either set a queryset explicitly, or set \nread_only=True\n.\n\n\nmany\n - If applied to a to-many relationship, you should set this argument to \nTrue\n.\n\n\nallow_null\n - If set to \nTrue\n, the field will accept values of \nNone\n or the empty string for nullable relationships. Defaults to \nFalse\n.\n\n\n\n\nHyperlinkedIdentityField\n\n\nThis field can be applied as an identity relationship, such as the \n'url'\n field on a HyperlinkedModelSerializer. It can also be used for an attribute on the object. For example, the following serializer:\n\n\nclass AlbumSerializer(serializers.HyperlinkedModelSerializer):\n track_listing = serializers.HyperlinkedIdentityField(view_name='track-list')\n\n class Meta:\n model = Album\n fields = ('album_name', 'artist', 'track_listing')\n\n\n\nWould serialize to a representation like this:\n\n\n{\n 'album_name': 'The Eraser',\n 'artist': 'Thom Yorke',\n 'track_listing': 'http://www.example.com/api/track_list/12/',\n}\n\n\n\nThis field is always read-only.\n\n\nArguments\n:\n\n\n\n\nview_name\n - The view name that should be used as the target of the relationship. If you're using \nthe standard router classes\n this will be a string with the format \nmodel_name\n-detail\n. \nrequired\n.\n\n\nlookup_field\n - 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 \n'pk'\n.\n\n\nlookup_url_kwarg\n - The name of the keyword argument defined in the URL conf that corresponds to the lookup field. Defaults to using the same value as \nlookup_field\n.\n\n\nformat\n - If using format suffixes, hyperlinked fields will use the same format suffix for the target unless overridden by using the \nformat\n argument.\n\n\n\n\n\n\nNested relationships\n\n\nNested relationships can be expressed by using serializers as fields.\n\n\nIf the field is used to represent a to-many relationship, you should add the \nmany=True\n flag to the serializer field.\n\n\nExample\n\n\nFor example, the following serializer:\n\n\nclass TrackSerializer(serializers.ModelSerializer):\n class Meta:\n model = Track\n fields = ('order', 'title')\n\nclass AlbumSerializer(serializers.ModelSerializer):\n tracks = TrackSerializer(many=True, read_only=True)\n\n class Meta:\n model = Album\n fields = ('album_name', 'artist', 'tracks')\n\n\n\nWould serialize to a nested representation like this:\n\n\n album = Album.objects.create(album_name=\"The Grey Album\", artist='Danger Mouse')\n\n Track.objects.create(album=album, order=1, title='Public Service Announcement', duration=245)\n\nTrack: Track object\n\n\n Track.objects.create(album=album, order=2, title='What More Can I Say', duration=264)\n\nTrack: Track object\n\n\n Track.objects.create(album=album, order=3, title='Encore', duration=159)\n\nTrack: Track object\n\n\n serializer = AlbumSerializer(instance=album)\n\n serializer.data\n{\n 'album_name': 'The Grey Album',\n 'artist': 'Danger Mouse',\n 'tracks': [\n {'order': 1, 'title': 'Public Service Announcement', 'duration': 245},\n {'order': 2, 'title': 'What More Can I Say', 'duration': 264},\n {'order': 3, 'title': 'Encore', 'duration': 159},\n ...\n ],\n}\n\n\n\nWritable nested serializers\n\n\nBe default nested serializers are read-only. If you want to to support write-operations to a nested serializer field you'll need to create either or both of the \ncreate()\n and/or \nupdate()\n methods, in order to explicitly specify how the child relationships should be saved.\n\n\nclass TrackSerializer(serializers.ModelSerializer):\n class Meta:\n model = Track\n fields = ('order', 'title')\n\nclass AlbumSerializer(serializers.ModelSerializer):\n tracks = TrackSerializer(many=True)\n\n class Meta:\n model = Album\n fields = ('album_name', 'artist', 'tracks')\n\n def create(self, validated_data):\n tracks_data = validated_data.pop('tracks')\n album = Album.objects.create(**validated_data)\n for track_data in tracks_data:\n Track.objects.create(album=album, **track_data)\n return album\n\n\n data = {\n 'album_name': 'The Grey Album',\n 'artist': 'Danger Mouse',\n 'tracks': [\n {'order': 1, 'title': 'Public Service Announcement', 'duration': 245},\n {'order': 2, 'title': 'What More Can I Say', 'duration': 264},\n {'order': 3, 'title': 'Encore', 'duration': 159},\n ],\n}\n\n serializer = AlbumSerializer(data=data)\n\n serializer.is_valid()\nTrue\n\n serializer.save()\n\nAlbum: Album object\n\n\n\n\nCustom relational fields\n\n\nTo implement a custom relational field, you should override \nRelatedField\n, and implement the \n.to_representation(self, value)\n method. This method takes the target of the field as the \nvalue\n argument, and should return the representation that should be used to serialize the target. The \nvalue\n argument will typically be a model instance.\n\n\nIf you want to implement a read-write relational field, you must also implement the \n.to_internal_value(self, data)\n method.\n\n\nExample\n\n\nFor example, we could define a relational field to serialize a track to a custom string representation, using its ordering, title, and duration.\n\n\nimport time\n\nclass TrackListingField(serializers.RelatedField):\n def to_representation(self, value):\n duration = time.strftime('%M:%S', time.gmtime(value.duration))\n return 'Track %d: %s (%s)' % (value.order, value.name, duration)\n\nclass AlbumSerializer(serializers.ModelSerializer):\n tracks = TrackListingField(many=True)\n\n class Meta:\n model = Album\n fields = ('album_name', 'artist', 'tracks')\n\n\n\nThis custom field would then serialize to the following representation.\n\n\n{\n 'album_name': 'Sometimes I Wish We Were an Eagle',\n 'artist': 'Bill Callahan',\n 'tracks': [\n 'Track 1: Jim Cain (04:39)',\n 'Track 2: Eid Ma Clack Shaw (04:19)',\n 'Track 3: The Wind and the Dove (04:34)',\n ...\n ]\n}\n\n\n\n\n\nCustom hyperlinked fields\n\n\nIn some cases you may need to customize the behavior of a hyperlinked field, in order to represent URLs that require more than a single lookup field.\n\n\nYou can achieve this by overriding \nHyperlinkedRelatedField\n. There are two methods that may be overridden:\n\n\nget_url(self, obj, view_name, request, format)\n\n\nThe \nget_url\n method is used to map the object instance to its URL representation.\n\n\nMay raise a \nNoReverseMatch\n if the \nview_name\n and \nlookup_field\n\nattributes are not configured to correctly match the URL conf.\n\n\nget_object(self, queryset, view_name, view_args, view_kwargs)\n\n\nIf you want to support a writable hyperlinked field then you'll also want to override \nget_object\n, in order to map incoming URLs back to the object they represent. For read-only hyperlinked fields there is no need to override this method.\n\n\nThe return value of this method should the object that corresponds to the matched URL conf arguments.\n\n\nMay raise an \nObjectDoesNotExist\n exception.\n\n\nExample\n\n\nSay we have a URL for a customer object that takes two keyword arguments, like so:\n\n\n/api/\norganization_slug\n/customers/\ncustomer_pk\n/\n\n\n\nThis cannot be represented with the default implementation, which accepts only a single lookup field.\n\n\nIn this case we'd need to override \nHyperlinkedRelatedField\n to get the behavior we want:\n\n\nfrom rest_framework import serializers\nfrom rest_framework.reverse import reverse\n\nclass CustomerHyperlink(serializers.HyperlinkedRelatedField):\n # We define these as class attributes, so we don't need to pass them as arguments.\n view_name = 'customer-detail'\n queryset = Customer.objects.all()\n\n def get_url(self, obj, view_name, request, format):\n url_kwargs = {\n 'organization_slug': obj.organization.slug,\n 'customer_pk': obj.pk\n }\n return reverse(view_name, url_kwargs, request=request, format=format)\n\n def get_object(self, view_name, view_args, view_kwargs):\n lookup_kwargs = {\n 'organization__slug': view_kwargs['organization_slug'],\n 'pk': view_kwargs['customer_pk']\n }\n return self.get_queryset().get(**lookup_kwargs)\n\n\n\nNote that if you wanted to use this style together with the generic views then you'd also need to override \n.get_object\n on the view in order to get the correct lookup behavior.\n\n\nGenerally we recommend a flat style for API representations where possible, but the nested URL style can also be reasonable when used in moderation.\n\n\n\n\nFurther notes\n\n\nThe \nqueryset\n argument\n\n\nThe \nqueryset\n argument is only ever required for \nwritable\n 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.\n\n\nIn version 2.x a serializer class could \nsometimes\n automatically determine the \nqueryset\n argument \nif\n a \nModelSerializer\n class was being used.\n\n\nThis behavior is now replaced with \nalways\n using an explicit \nqueryset\n argument for writable relational fields.\n\n\nDoing so reduces the amount of hidden 'magic' that \nModelSerializer\n provides, makes the behavior of the field more clear, and ensures that it is trivial to move between using the \nModelSerializer\n shortcut, or using fully explicit \nSerializer\n classes.\n\n\nReverse relations\n\n\nNote that reverse relationships are not automatically included by the \nModelSerializer\n and \nHyperlinkedModelSerializer\n classes. To include a reverse relationship, you must explicitly add it to the fields list. For example:\n\n\nclass AlbumSerializer(serializers.ModelSerializer):\n class Meta:\n fields = ('tracks', ...)\n\n\n\nYou'll normally want to ensure that you've set an appropriate \nrelated_name\n argument on the relationship, that you can use as the field name. For example:\n\n\nclass Track(models.Model):\n album = models.ForeignKey(Album, related_name='tracks')\n ...\n\n\n\nIf you have not set a related name for the reverse relationship, you'll need to use the automatically generated related name in the \nfields\n argument. For example:\n\n\nclass AlbumSerializer(serializers.ModelSerializer):\n class Meta:\n fields = ('track_set', ...)\n\n\n\nSee the Django documentation on \nreverse relationships\n for more details.\n\n\nGeneric relationships\n\n\nIf you want to serialize a generic foreign key, you need to define a custom field, to determine explicitly how you want serialize the targets of the relationship.\n\n\nFor example, given the following model for a tag, which has a generic relationship with other arbitrary models:\n\n\nclass TaggedItem(models.Model):\n\"\"\"\n Tags arbitrary model instances using a generic relation.\n\n See: https://docs.djangoproject.com/en/dev/ref/contrib/contenttypes/\n\"\"\"\n tag_name = models.SlugField()\n content_type = models.ForeignKey(ContentType)\n object_id = models.PositiveIntegerField()\n tagged_object = GenericForeignKey('content_type', 'object_id')\n\n def __unicode__(self):\n return self.tag\n\n\n\nAnd the following two models, which may be have associated tags:\n\n\nclass Bookmark(models.Model):\n\"\"\"\n A bookmark consists of a URL, and 0 or more descriptive tags.\n\"\"\"\n url = models.URLField()\n tags = GenericRelation(TaggedItem)\n\n\nclass Note(models.Model):\n\"\"\"\n A note consists of some text, and 0 or more descriptive tags.\n\"\"\"\n text = models.CharField(max_length=1000)\n tags = GenericRelation(TaggedItem)\n\n\n\nWe could define a custom field that could be used to serialize tagged instances, using the type of each instance to determine how it should be serialized.\n\n\nclass TaggedObjectRelatedField(serializers.RelatedField):\n\"\"\"\n A custom field to use for the `tagged_object` generic relationship.\n\"\"\"\n\n def to_representation(self, value):\n\"\"\"\n Serialize tagged objects to a simple textual representation.\n\"\"\"\n if isinstance(value, Bookmark):\n return 'Bookmark: ' + value.url\n elif isinstance(value, Note):\n return 'Note: ' + value.text\n raise Exception('Unexpected type of tagged object')\n\n\n\nIf you need the target of the relationship to have a nested representation, you can use the required serializers inside the \n.to_representation()\n method:\n\n\n def to_representation(self, value):\n\"\"\"\n Serialize bookmark instances using a bookmark serializer,\n and note instances using a note serializer.\n\"\"\"\n if isinstance(value, Bookmark):\n serializer = BookmarkSerializer(value)\n elif isinstance(value, Note):\n serializer = NoteSerializer(value)\n else:\n raise Exception('Unexpected type of tagged object')\n\n return serializer.data\n\n\n\nNote that reverse generic keys, expressed using the \nGenericRelation\n field, can be serialized using the regular relational field types, since the type of the target in the relationship is always known.\n\n\nFor more information see \nthe Django documentation on generic relations\n.\n\n\nManyToManyFields with a Through Model\n\n\nBy default, relational fields that target a \nManyToManyField\n with a\n\nthrough\n model specified are set to read-only.\n\n\nIf you explicitly specify a relational field pointing to a\n\nManyToManyField\n with a through model, be sure to set \nread_only\n\nto \nTrue\n.\n\n\n\n\nThird Party Packages\n\n\nThe following third party packages are also available.\n\n\nDRF Nested Routers\n\n\nThe \ndrf-nested-routers package\n provides routers and relationship fields for working with nested resources.",
"text":"Serializer relations\n\n\n\n\nBad programmers worry about the code.\nGood programmers worry about data structures and their relationships.\n\n\n\nLinus Torvalds\n\n\n\n\nRelational fields are used to represent model relationships. They can be applied to \nForeignKey\n, \nManyToManyField\n and \nOneToOneField\n relationships, as well as to reverse relationships, and custom relationships such as \nGenericForeignKey\n.\n\n\n\n\nNote:\n The relational fields are declared in \nrelations.py\n, but by convention you should import them from the \nserializers\n module, using \nfrom rest_framework import serializers\n and refer to fields as \nserializers.\nFieldName\n.\n\n\n\n\nInspecting automatically generated relationships.\n\n\nWhen using the \nModelSerializer\n class, serializer fields and relationships will be automatically generated for you. Inspecting these automatically generated fields can be a useful tool for determining how to customize the relationship style.\n\n\nTo do so, open the Django shell, using \npython manage.py shell\n, then import the serializer class, instantiate it, and print the object representation\u2026\n\n\n from myapp.serializers import AccountSerializer\n\n serializer = AccountSerializer()\n\n print repr(serializer) # Or `print(repr(serializer))` in Python 3.x.\nAccountSerializer():\n id = IntegerField(label='ID', read_only=True)\n name = CharField(allow_blank=True, max_length=100, required=False)\n owner = PrimaryKeyRelatedField(queryset=User.objects.all())\n\n\n\nAPI Reference\n\n\nIn order to explain the various types of relational fields, we'll use a couple of simple models for our examples. Our models will be for music albums, and the tracks listed on each album.\n\n\nclass Album(models.Model):\n album_name = models.CharField(max_length=100)\n artist = models.CharField(max_length=100)\n\nclass Track(models.Model):\n album = models.ForeignKey(Album, related_name='tracks')\n order = models.IntegerField()\n title = models.CharField(max_length=100)\n duration = models.IntegerField()\n\n class Meta:\n unique_together = ('album', 'order')\n ordering = ['order']\n\n def __unicode__(self):\n return '%d: %s' % (self.order, self.title)\n\n\n\nStringRelatedField\n\n\nStringRelatedField\n may be used to represent the target of the relationship using its \n__unicode__\n method.\n\n\nFor example, the following serializer.\n\n\nclass AlbumSerializer(serializers.ModelSerializer):\n tracks = serializers.StringRelatedField(many=True)\n\n class Meta:\n model = Album\n fields = ('album_name', 'artist', 'tracks')\n\n\n\nWould serialize to the following representation.\n\n\n{\n 'album_name': 'Things We Lost In The Fire',\n 'artist': 'Low',\n 'tracks': [\n '1: Sunflower',\n '2: Whitetail',\n '3: Dinosaur Act',\n ...\n ]\n}\n\n\n\nThis field is read only.\n\n\nArguments\n:\n\n\n\n\nmany\n - If applied to a to-many relationship, you should set this argument to \nTrue\n.\n\n\n\n\nPrimaryKeyRelatedField\n\n\nPrimaryKeyRelatedField\n may be used to represent the target of the relationship using its primary key.\n\n\nFor example, the following serializer:\n\n\nclass AlbumSerializer(serializers.ModelSerializer):\n tracks = serializers.PrimaryKeyRelatedField(many=True, read_only=True)\n\n class Meta:\n model = Album\n fields = ('album_name', 'artist', 'tracks')\n\n\n\nWould serialize to a representation like this:\n\n\n{\n 'album_name': 'The Roots',\n 'artist': 'Undun',\n 'tracks': [\n 89,\n 90,\n 91,\n ...\n ]\n}\n\n\n\nBy default this field is read-write, although you can change this behavior using the \nread_only\n flag.\n\n\nArguments\n:\n\n\n\n\nqueryset\n - The queryset used for model instance lookups when validating the field input. Relationships must either set a queryset explicitly, or set \nread_only=True\n.\n\n\nmany\n - If applied to a to-many relationship, you should set this argument to \nTrue\n.\n\n\nallow_null\n - If set to \nTrue\n, the field will accept values of \nNone\n or the empty string for nullable relationships. Defaults to \nFalse\n.\n\n\npk_field\n - Set to a field to control serialization/deserialization of the primary key's value. For example, \npk_field=UUIDField(format='hex')\n would serialize a UUID primary key into its compact hex representation.\n\n\n\n\nHyperlinkedRelatedField\n\n\nHyperlinkedRelatedField\n may be used to represent the target of the relationship using a hyperlink.\n\n\nFor example, the following serializer:\n\n\nclass AlbumSerializer(serializers.ModelSerializer):\n tracks = serializers.HyperlinkedRelatedField(\n many=True,\n read_only=True,\n view_name='track-detail'\n )\n\n class Meta:\n model = Album\n fields = ('album_name', 'artist', 'tracks')\n\n\n\nWould serialize to a representation like this:\n\n\n{\n 'album_name': 'Graceland',\n 'artist': 'Paul Simon',\n 'tracks': [\n 'http://www.example.com/api/tracks/45/',\n 'http://www.example.com/api/tracks/46/',\n 'http://www.example.com/api/tracks/47/',\n ...\n ]\n}\n\n\n\nBy default this field is read-write, although you can change this behavior using the \nread_only\n flag.\n\n\n\n\nNote\n: This field is designed for objects that map to a URL that accepts a single URL keyword argument, as set using the \nlookup_field\n and \nlookup_url_kwarg\n arguments.\n\n\nThis is suitable for URLs that contain a single primary key or slug argument as part of the URL.\n\n\nIf you require more complex hyperlinked representation you'll need to customize the field, as described in the \ncustom hyperlinked fields\n section, below.\n\n\n\n\nArguments\n:\n\n\n\n\nview_name\n - The view name that should be used as the target of the relationship. If you're using \nthe standard router classes\n this will be a string with the format \nmodelname\n-detail\n. \nrequired\n.\n\n\nqueryset\n - The queryset used for model instance lookups when validating the field input. Relationships must either set a queryset explicitly, or set \nread_only=True\n.\n\n\nmany\n - If applied to a to-many relationship, you should set this argument to \nTrue\n.\n\n\nallow_null\n - If set to \nTrue\n, the field will accept values of \nNone\n or the empty string for nullable relationships. Defaults to \nFalse\n.\n\n\nlookup_field\n - 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 \n'pk'\n.\n\n\nlookup_url_kwarg\n - The name of the keyword argument defined in the URL conf that corresponds to the lookup field. Defaults to using the same value as \nlookup_field\n.\n\n\nformat\n - If using format suffixes, hyperlinked fields will use the same format suffix for the target unless overridden by using the \nformat\n argument.\n\n\n\n\nSlugRelatedField\n\n\nSlugRelatedField\n may be used to represent the target of the relationship using a field on the target.\n\n\nFor example, the following serializer:\n\n\nclass AlbumSerializer(serializers.ModelSerializer):\n tracks = serializers.SlugRelatedField(\n many=True,\n read_only=True,\n slug_field='title'\n )\n\n class Meta:\n model = Album\n fields = ('album_name', 'artist', 'tracks')\n\n\n\nWould serialize to a representation like this:\n\n\n{\n 'album_name': 'Dear John',\n 'artist': 'Loney Dear',\n 'tracks': [\n 'Airport Surroundings',\n 'Everything Turns to You',\n 'I Was Only Going Out',\n ...\n ]\n}\n\n\n\nBy default this field is read-write, although you can change this behavior using the \nread_only\n flag.\n\n\nWhen using \nSlugRelatedField\n as a read-write field, you will normally want to ensure that the slug field corresponds to a model field with \nunique=True\n.\n\n\nArguments\n:\n\n\n\n\nslug_field\n - 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, \nusername\n. \nrequired\n\n\nqueryset\n - The queryset used for model instance lookups when validating the field input. Relationships must either set a queryset explicitly, or set \nread_only=True\n.\n\n\nmany\n - If applied to a to-many relationship, you should set this argument to \nTrue\n.\n\n\nallow_null\n - If set to \nTrue\n, the field will accept values of \nNone\n or the empty string for nullable relationships. Defaults to \nFalse\n.\n\n\n\n\nHyperlinkedIdentityField\n\n\nThis field can be applied as an identity relationship, such as the \n'url'\n field on a HyperlinkedModelSerializer. It can also be used for an attribute on the object. For example, the following serializer:\n\n\nclass AlbumSerializer(serializers.HyperlinkedModelSerializer):\n track_listing = serializers.HyperlinkedIdentityField(view_name='track-list')\n\n class Meta:\n model = Album\n fields = ('album_name', 'artist', 'track_listing')\n\n\n\nWould serialize to a representation like this:\n\n\n{\n 'album_name': 'The Eraser',\n 'artist': 'Thom Yorke',\n 'track_listing': 'http://www.example.com/api/track_list/12/',\n}\n\n\n\nThis field is always read-only.\n\n\nArguments\n:\n\n\n\n\nview_name\n - The view name that should be used as the target of the relationship. If you're using \nthe standard router classes\n this will be a string with the format \nmodel_name\n-detail\n. \nrequired\n.\n\n\nlookup_field\n - 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 \n'pk'\n.\n\n\nlookup_url_kwarg\n - The name of the keyword argument defined in the URL conf that corresponds to the lookup field. Defaults to using the same value as \nlookup_field\n.\n\n\nformat\n - If using format suffixes, hyperlinked fields will use the same format suffix for the target unless overridden by using the \nformat\n argument.\n\n\n\n\n\n\nNested relationships\n\n\nNested relationships can be expressed by using serializers as fields.\n\n\nIf the field is used to represent a to-many relationship, you should add the \nmany=True\n flag to the serializer field.\n\n\nExample\n\n\nFor example, the following serializer:\n\n\nclass TrackSerializer(serializers.ModelSerializer):\n class Meta:\n model = Track\n fields = ('order', 'title')\n\nclass AlbumSerializer(serializers.ModelSerializer):\n tracks = TrackSerializer(many=True, read_only=True)\n\n class Meta:\n model = Album\n fields = ('album_name', 'artist', 'tracks')\n\n\n\nWould serialize to a nested representation like this:\n\n\n album = Album.objects.create(album_name=\"The Grey Album\", artist='Danger Mouse')\n\n Track.objects.create(album=album, order=1, title='Public Service Announcement', duration=245)\n\nTrack: Track object\n\n\n Track.objects.create(album=album, order=2, title='What More Can I Say', duration=264)\n\nTrack: Track object\n\n\n Track.objects.create(album=album, order=3, title='Encore', duration=159)\n\nTrack: Track object\n\n\n serializer = AlbumSerializer(instance=album)\n\n serializer.data\n{\n 'album_name': 'The Grey Album',\n 'artist': 'Danger Mouse',\n 'tracks': [\n {'order': 1, 'title': 'Public Service Announcement', 'duration': 245},\n {'order': 2, 'title': 'What More Can I Say', 'duration': 264},\n {'order': 3, 'title': 'Encore', 'duration': 159},\n ...\n ],\n}\n\n\n\nWritable nested serializers\n\n\nBe default nested serializers are read-only. If you want to to support write-operations to a nested serializer field you'll need to create either or both of the \ncreate()\n and/or \nupdate()\n methods, in order to explicitly specify how the child relationships should be saved.\n\n\nclass TrackSerializer(serializers.ModelSerializer):\n class Meta:\n model = Track\n fields = ('order', 'title')\n\nclass AlbumSerializer(serializers.ModelSerializer):\n tracks = TrackSerializer(many=True)\n\n class Meta:\n model = Album\n fields = ('album_name', 'artist', 'tracks')\n\n def create(self, validated_data):\n tracks_data = validated_data.pop('tracks')\n album = Album.objects.create(**validated_data)\n for track_data in tracks_data:\n Track.objects.create(album=album, **track_data)\n return album\n\n\n data = {\n 'album_name': 'The Grey Album',\n 'artist': 'Danger Mouse',\n 'tracks': [\n {'order': 1, 'title': 'Public Service Announcement', 'duration': 245},\n {'order': 2, 'title': 'What More Can I Say', 'duration': 264},\n {'order': 3, 'title': 'Encore', 'duration': 159},\n ],\n}\n\n serializer = AlbumSerializer(data=data)\n\n serializer.is_valid()\nTrue\n\n serializer.save()\n\nAlbum: Album object\n\n\n\n\nCustom relational fields\n\n\nTo implement a custom relational field, you should override \nRelatedField\n, and implement the \n.to_representation(self, value)\n method. This method takes the target of the field as the \nvalue\n argument, and should return the representation that should be used to serialize the target. The \nvalue\n argument will typically be a model instance.\n\n\nIf you want to implement a read-write relational field, you must also implement the \n.to_internal_value(self, data)\n method.\n\n\nExample\n\n\nFor example, we could define a relational field to serialize a track to a custom string representation, using its ordering, title, and duration.\n\n\nimport time\n\nclass TrackListingField(serializers.RelatedField):\n def to_representation(self, value):\n duration = time.strftime('%M:%S', time.gmtime(value.duration))\n return 'Track %d: %s (%s)' % (value.order, value.name, duration)\n\nclass AlbumSerializer(serializers.ModelSerializer):\n tracks = TrackListingField(many=True)\n\n class Meta:\n model = Album\n fields = ('album_name', 'artist', 'tracks')\n\n\n\nThis custom field would then serialize to the following representation.\n\n\n{\n 'album_name': 'Sometimes I Wish We Were an Eagle',\n 'artist': 'Bill Callahan',\n 'tracks': [\n 'Track 1: Jim Cain (04:39)',\n 'Track 2: Eid Ma Clack Shaw (04:19)',\n 'Track 3: The Wind and the Dove (04:34)',\n ...\n ]\n}\n\n\n\n\n\nCustom hyperlinked fields\n\n\nIn some cases you may need to customize the behavior of a hyperlinked field, in order to represent URLs that require more than a single lookup field.\n\n\nYou can achieve this by overriding \nHyperlinkedRelatedField\n. There are two methods that may be overridden:\n\n\nget_url(self, obj, view_name, request, format)\n\n\nThe \nget_url\n method is used to map the object instance to its URL representation.\n\n\nMay raise a \nNoReverseMatch\n if the \nview_name\n and \nlookup_field\n\nattributes are not configured to correctly match the URL conf.\n\n\nget_object(self, queryset, view_name, view_args, view_kwargs)\n\n\nIf you want to support a writable hyperlinked field then you'll also want to override \nget_object\n, in order to map incoming URLs back to the object they represent. For read-only hyperlinked fields there is no need to override this method.\n\n\nThe return value of this method should the object that corresponds to the matched URL conf arguments.\n\n\nMay raise an \nObjectDoesNotExist\n exception.\n\n\nExample\n\n\nSay we have a URL for a customer object that takes two keyword arguments, like so:\n\n\n/api/\norganization_slug\n/customers/\ncustomer_pk\n/\n\n\n\nThis cannot be represented with the default implementation, which accepts only a single lookup field.\n\n\nIn this case we'd need to override \nHyperlinkedRelatedField\n to get the behavior we want:\n\n\nfrom rest_framework import serializers\nfrom rest_framework.reverse import reverse\n\nclass CustomerHyperlink(serializers.HyperlinkedRelatedField):\n # We define these as class attributes, so we don't need to pass them as arguments.\n view_name = 'customer-detail'\n queryset = Customer.objects.all()\n\n def get_url(self, obj, view_name, request, format):\n url_kwargs = {\n 'organization_slug': obj.organization.slug,\n 'customer_pk': obj.pk\n }\n return reverse(view_name, url_kwargs, request=request, format=format)\n\n def get_object(self, view_name, view_args, view_kwargs):\n lookup_kwargs = {\n 'organization__slug': view_kwargs['organization_slug'],\n 'pk': view_kwargs['customer_pk']\n }\n return self.get_queryset().get(**lookup_kwargs)\n\n\n\nNote that if you wanted to use this style together with the generic views then you'd also need to override \n.get_object\n on the view in order to get the correct lookup behavior.\n\n\nGenerally we recommend a flat style for API representations where possible, but the nested URL style can also be reasonable when used in moderation.\n\n\n\n\nFurther notes\n\n\nThe \nqueryset\n argument\n\n\nThe \nqueryset\n argument is only ever required for \nwritable\n 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.\n\n\nIn version 2.x a serializer class could \nsometimes\n automatically determine the \nqueryset\n argument \nif\n a \nModelSerializer\n class was being used.\n\n\nThis behavior is now replaced with \nalways\n using an explicit \nqueryset\n argument for writable relational fields.\n\n\nDoing so reduces the amount of hidden 'magic' that \nModelSerializer\n provides, makes the behavior of the field more clear, and ensures that it is trivial to move between using the \nModelSerializer\n shortcut, or using fully explicit \nSerializer\n classes.\n\n\nCustomizing the HTML display\n\n\nThe built-in \n__str__\n method of the model will be used to generate string representations of the objects used to populate the \nchoices\n property. These choices are used to populate select HTML inputs in the browsable API.\n\n\nTo provide customized representations for such inputs, override \ndisplay_value()\n of a \nRelatedField\n subclass. This method will receive a model object, and should return a string suitable for representing it. For example:\n\n\nclass TrackPrimaryKeyRelatedField(serializers.PrimaryKeyRelatedField):\n def display_value(self, instance):\n return 'Track: %s' % (instance.title)\n\n\n\nReverse relations\n\n\nNote that reverse relationships are not automatically included by the \nModelSerializer\n and \nHyperlinkedModelSerializer\n classes. To include a reverse relationship, you must explicitly add it to the fields list. For example:\n\n\nclass AlbumSerializer(serializers.ModelSerializer):\n class Meta:\n fields = ('tracks', ...)\n\n\n\nYou'll normally want to ensure that you've set an appropriate \nrelated_name\n argument on the relationship, that you can use as the field name. For example:\n\n\nclass Track(models.Model):\n album = models.ForeignKey(Album, related_name='tracks')\n ...\n\n\n\nIf you have not set a related name for the reverse relationship, you'll need to use the automatically generated related name in the \nfields\n argument. For example:\n\n\nclass AlbumSerializer(serializers.ModelSerializer):\n class Meta:\n fields = ('track_set', ...)\n\n\n\nSee the Django documentation on \nreverse relationships\n for more details.\n\n\nGeneric relationships\n\n\nIf you want to serialize a generic foreign key, you need to define a custom field, to determine explicitly how you want serialize the targets of the relationship.\n\n\nFor example, given the following model for a tag, which has a generic relationship with other arbitrary models:\n\n\nclass TaggedItem(models.Model):\n\"\"\"\n Tags arbitrary model instances using a generic relation.\n\n See: https://docs.djangoproject.com/en/dev/ref/contrib/contenttypes/\n\"\"\"\n tag_name = models.SlugField()\n content_type = models.ForeignKey(ContentType)\n object_id = models.PositiveIntegerField()\n tagged_object = GenericForeignKey('content_type', 'object_id')\n\n def __unicode__(self):\n return self.tag\n\n\n\nAnd the following two models, which may be have associated tags:\n\n\nclass Bookmark(models.Model):\n\"\"\"\n A bookmark consists of a URL, and 0 or more descriptive tags.\n\"\"\"\n url = models.URLField()\n tags = GenericRelation(TaggedItem)\n\n\nclass Note(models.Model):\n\"\"\"\n A note consists of some text, and 0 or more descriptive tags.\n\"\"\"\n text = models.CharField(max_length=1000)\n tags = GenericRelation(TaggedItem)\n\n\n\nWe could define a custom field that could be used to serialize tagged instances, using the type of each instance to determine how it should be serialized.\n\n\nclass TaggedObjectRelatedField(serializers.RelatedField):\n\"\"\"\n A custom field to use for the `tagged_object` generic relationship.\n\"\"\"\n\n def to_representation(self, value):\n\"\"\"\n Serialize tagged objects to a simple textual representation.\n\"\"\"\n if isinstance(value, Bookmark):\n return 'Bookmark: ' + value.url\n elif isinstance(value, Note):\n return 'Note: ' + value.text\n raise Exception('Unexpected type of tagged object')\n\n\n\nIf you need the target of the relationship to have a nested representation, you can use the required serializers inside the \n.to_representation()\n method:\n\n\n def to_representation(self, value):\n\"\"\"\n Serialize bookmark instances using a bookmark serializer,\n and note instances using a note serializer.\n\"\"\"\n if isinstance(value, Bookmark):\n serializer = BookmarkSerializer(value)\n elif isinstance(value, Note):\n serializer = NoteSerializer(value)\n else:\n raise Exception('Unexpected type of tagged object')\n\n return serializer.data\n\n\n\nNote that reverse generic keys, expressed using the \nGenericRelation\n field, can be serialized using the regular relational field types, since the type of the target in the relationship is always known.\n\n\nFor more information see \nthe Django documentation on generic relations\n.\n\n\nManyToManyFields with a Through Model\n\n\nBy default, relational fields that target a \nManyToManyField\n with a\n\nthrough\n model specified are set to read-only.\n\n\nIf you explicitly specify a relational field pointing to a\n\nManyToManyField\n with a through model, be sure to set \nread_only\n\nto \nTrue\n.\n\n\n\n\nThird Party Packages\n\n\nThe following third party packages are also available.\n\n\nDRF Nested Routers\n\n\nThe \ndrf-nested-routers package\n provides routers and relationship fields for working with nested resources.",
"text":"The built-in __str__ method of the model will be used to generate string representations of the objects used to populate the choices property. These choices are used to populate select HTML inputs in the browsable API. To provide customized representations for such inputs, override display_value() of a RelatedField subclass. This method will receive a model object, and should return a string suitable for representing it. For example: class TrackPrimaryKeyRelatedField(serializers.PrimaryKeyRelatedField):\n def display_value(self, instance):\n return 'Track: %s' % (instance.title)",
"text":"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: class AlbumSerializer(serializers.ModelSerializer):\n class Meta:\n fields = ('tracks', ...) You'll normally want to ensure that you've set an appropriate related_name argument on the relationship, that you can use as the field name. For example: class Track(models.Model):\n album = models.ForeignKey(Album, related_name='tracks')\n ... If you have not set a related name for the reverse relationship, you'll need to use the automatically generated related name in the fields argument. For example: class AlbumSerializer(serializers.ModelSerializer):\n class Meta:\n fields = ('track_set', ...) See the Django documentation on reverse relationships for more details.",
"text":"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: class AlbumSerializer(serializers.ModelSerializer):\n class Meta:\n fields = ('tracks', ...) You'll normally want to ensure that you've set an appropriate related_name argument on the relationship, that you can use as the field name. For example: class Track(models.Model):\n album = models.ForeignKey(Album, related_name='tracks')\n ... If you have not set a related name for the reverse relationship, you'll need to use the automatically generated related name in the fields argument. For example: class AlbumSerializer(serializers.ModelSerializer):\n class Meta:\n fields = ('track_set', ...) See the Django documentation on reverse relationships for more details.",
"title":"Reverse relations"
"title":"Reverse relations"
...
@@ -2947,7 +2942,7 @@
...
@@ -2947,7 +2942,7 @@
},
},
{
{
"location":"/topics/3.2-announcement/",
"location":"/topics/3.2-announcement/",
"text":"Django REST framework 3.2\n\n\nThe 3.2 release is the first version to include an admin interface for the browsable API.\n\n\n\n\nThis interface is intended to act as a more user-friendly interface to the API. It can be used either as a replacement to the existing \nBrowsableAPIRenderer\n, or used together with it, allowing you to switch between the two styles as required.\n\n\nWe've also fixed a huge number of issues, and made numerous cleanups and improvements.\n\n\nOver the course of the 3.1.x series we've \nresolved nearly 600 tickets\n on our GitHub issue tracker. This means we're currently running at a rate of \nclosing around 100 issues or pull requests per month\n.\n\n\nNone of this would have been possible without the support of our wonderful Kickstarter backers. If you're looking for a job in Django development we'd strongly recommend taking \na look through our sponsors\n and finding out who's hiring.\n\n\nAdminRenderer\n\n\nTo include \nAdminRenderer\n simply add it to your settings:\n\n\nREST_FRAMEWORK = {\n 'DEFAULT_RENDERER_CLASSES': [\n 'rest_framework.renderers.JSONRenderer',\n 'rest_framework.renderers.AdminRenderer',\n 'rest_framework.renderers.BrowsableAPIRenderer'\n ],\n 'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',\n 'PAGE_SIZE': 100\n}\n\n\n\nThere are some limitations to the \nAdminRenderer\n, in particular it is not yet able to handle list or dictionary inputs, as we do not have any HTML form fields that support those.\n\n\nAlso note that this is an initial release and we do not yet have a public API for modifying the behavior or documentation on overriding the templates.\n\n\nThe idea is to get this released to users early, so we can start getting feedback and release a more fully featured version in 3.3.\n\n\nSupported versions\n\n\nThis release drops support for Django 1.4.\n\n\nOur supported Django versions are now 1.5.6+, 1.6.3+, 1.7 and 1.8.\n\n\nDeprecations\n\n\nThere are no new deprecations in 3.2, although a number of existing deprecations have now escalated in line with our deprecation policy.\n\n\n\n\nrequest.DATA\n was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of \nrequest.data\n instead.\n\n\nrequest.FILES\n was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of \nrequest.files\n instead.\n\n\nrequest.QUERY_PARAMS\n was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of \nrequest.query_params\n instead.\n\n\nThe following \nModelSerializer.Meta\n options have now been removed: \nwrite_only_fields\n, \nview_name\n, \nlookup_field\n. Use the more general \nextra_kwargs\n option instead.\n\n\n\n\nThe following pagination view attributes and settings have been moved into attributes on the pagination class since 3.1. Their usage was formerly in 'pending deprecation', and has now escalated to 'deprecated'. They will continue to function but will raise errors.\n\n\n\n\nview.paginate_by\n - Use \npaginator.page_size\n instead.\n\n\nview.page_query_param\n - Use \npaginator.page_query_param\n instead.\n\n\nview.paginate_by_param\n - Use \npaginator.page_size_query_param\n instead.\n\n\nview.max_paginate_by\n - Use \npaginator.max_page_size\n instead.\n\n\nsettings.PAGINATE_BY\n - Use \npaginator.page_size\n instead.\n\n\nsettings.PAGINATE_BY_PARAM\n - Use \npaginator.page_size_query_param\n instead.\n\n\nsettings.MAX_PAGINATE_BY\n - Use \nmax_page_size\n instead.\n\n\n\n\nModifications to list behaviors\n\n\nThere are a couple of bug fixes that are worth calling out as they introduce differing behavior.\n\n\nThese are a little subtle and probably won't affect most users, but are worth understanding before upgrading your project.\n\n\nManyToMany fields and blank=True\n\n\nWe've now added an \nallow_empty\n argument, which can be used with \nListSerializer\n, or with \nmany=True\n relationships. This is \nTrue\n by default, but can be set to \nFalse\n if you want to disallow empty lists as valid input.\n\n\nAs a follow-up to this we are now able to properly mirror the behavior of Django's \nModelForm\n with respect to how many-to-many fields are validated.\n\n\nPreviously a many-to-many field on a model would map to a serializer field that would allow either empty or non-empty list inputs. Now, a many-to-many field will map to a serializer field that requires at least one input, unless the model field has \nblank=True\n set.\n\n\nHere's what the mapping looks like in practice:\n\n\n\n\nmodels.ManyToManyField()\n\u2192 \nserializers.PrimaryKeyRelatedField(many=True, allow_empty=False)\n\n\nmodels.ManyToManyField(blank=True)\n\u2192 \nserializers.PrimaryKeyRelatedField(many=True)\n\n\n\n\nThe upshot is this: If you have many to many fields in your models, then make sure you've included the argument \nblank=True\n if you want to allow empty inputs in the equivalent \nModelSerializer\n fields.\n\n\nList fields and allow_null\n\n\nWhen using \nallow_null\n with \nListField\n or a nested \nmany=True\n serializer the previous behavior was to allow \nnull\n values as items in the list. The behavior is now to allow \nnull\n values instead of the list.\n\n\nFor example, take the following field:\n\n\nNestedSerializer(many=True, allow_null=True)\n\n\n\nPreviously the validation behavior would be:\n\n\n\n\n[{\u2026}, null, {\u2026}]\n is \nvalid\n.\n\n\nnull\n is \ninvalid\n.\n\n\n\n\nOur validation behavior as of 3.2.0 is now:\n\n\n\n\n[{\u2026}, null, {\u2026}]\n is \ninvalid\n.\n\n\nnull\n is \nvalid\n.\n\n\n\n\nIf you want to allow \nnull\n child items, you'll need to instead specify \nallow_null\n on the child class, using an explicit \nListField\n instead of \nmany=True\n. For example:\n\n\nListField(child=NestedSerializer(allow_null=True))\n\n\n\nWhat's next?\n\n\nThe 3.3 release is currently planned for the start of October, and will be the last Kickstarter-funded release.\n\n\nThis release is planned to include:\n\n\n\n\nSearch and filtering controls in the browsable API and admin interface.\n\n\nImprovements and public API for the admin interface.\n\n\nImprovements and public API for our templated HTML forms and fields.\n\n\nNested object and list support in HTML forms.\n\n\n\n\nThanks once again to all our sponsors and supporters.",
"text":"Django REST framework 3.2\n\n\nThe 3.2 release is the first version to include an admin interface for the browsable API.\n\n\n\n\nThis interface is intended to act as a more user-friendly interface to the API. It can be used either as a replacement to the existing \nBrowsableAPIRenderer\n, or used together with it, allowing you to switch between the two styles as required.\n\n\nWe've also fixed a huge number of issues, and made numerous cleanups and improvements.\n\n\nOver the course of the 3.1.x series we've \nresolved nearly 600 tickets\n on our GitHub issue tracker. This means we're currently running at a rate of \nclosing around 100 issues or pull requests per month\n.\n\n\nNone of this would have been possible without the support of our wonderful Kickstarter backers. If you're looking for a job in Django development we'd strongly recommend taking \na look through our sponsors\n and finding out who's hiring.\n\n\nAdminRenderer\n\n\nTo include \nAdminRenderer\n simply add it to your settings:\n\n\nREST_FRAMEWORK = {\n 'DEFAULT_RENDERER_CLASSES': [\n 'rest_framework.renderers.JSONRenderer',\n 'rest_framework.renderers.AdminRenderer',\n 'rest_framework.renderers.BrowsableAPIRenderer'\n ],\n 'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',\n 'PAGE_SIZE': 100\n}\n\n\n\nThere are some limitations to the \nAdminRenderer\n, in particular it is not yet able to handle list or dictionary inputs, as we do not have any HTML form fields that support those.\n\n\nAlso note that this is an initial release and we do not yet have a public API for modifying the behavior or documentation on overriding the templates.\n\n\nThe idea is to get this released to users early, so we can start getting feedback and release a more fully featured version in 3.3.\n\n\nSupported versions\n\n\nThis release drops support for Django 1.4.\n\n\nOur supported Django versions are now 1.5.6+, 1.6.3+, 1.7 and 1.8.\n\n\nDeprecations\n\n\nThere are no new deprecations in 3.2, although a number of existing deprecations have now escalated in line with our deprecation policy.\n\n\n\n\nrequest.DATA\n was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of \nrequest.data\n instead.\n\n\nrequest.QUERY_PARAMS\n was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of \nrequest.query_params\n instead.\n\n\nThe following \nModelSerializer.Meta\n options have now been removed: \nwrite_only_fields\n, \nview_name\n, \nlookup_field\n. Use the more general \nextra_kwargs\n option instead.\n\n\n\n\nThe following pagination view attributes and settings have been moved into attributes on the pagination class since 3.1. Their usage was formerly in 'pending deprecation', and has now escalated to 'deprecated'. They will continue to function but will raise errors.\n\n\n\n\nview.paginate_by\n - Use \npaginator.page_size\n instead.\n\n\nview.page_query_param\n - Use \npaginator.page_query_param\n instead.\n\n\nview.paginate_by_param\n - Use \npaginator.page_size_query_param\n instead.\n\n\nview.max_paginate_by\n - Use \npaginator.max_page_size\n instead.\n\n\nsettings.PAGINATE_BY\n - Use \npaginator.page_size\n instead.\n\n\nsettings.PAGINATE_BY_PARAM\n - Use \npaginator.page_size_query_param\n instead.\n\n\nsettings.MAX_PAGINATE_BY\n - Use \nmax_page_size\n instead.\n\n\n\n\nModifications to list behaviors\n\n\nThere are a couple of bug fixes that are worth calling out as they introduce differing behavior.\n\n\nThese are a little subtle and probably won't affect most users, but are worth understanding before upgrading your project.\n\n\nManyToMany fields and blank=True\n\n\nWe've now added an \nallow_empty\n argument, which can be used with \nListSerializer\n, or with \nmany=True\n relationships. This is \nTrue\n by default, but can be set to \nFalse\n if you want to disallow empty lists as valid input.\n\n\nAs a follow-up to this we are now able to properly mirror the behavior of Django's \nModelForm\n with respect to how many-to-many fields are validated.\n\n\nPreviously a many-to-many field on a model would map to a serializer field that would allow either empty or non-empty list inputs. Now, a many-to-many field will map to a serializer field that requires at least one input, unless the model field has \nblank=True\n set.\n\n\nHere's what the mapping looks like in practice:\n\n\n\n\nmodels.ManyToManyField()\n\u2192 \nserializers.PrimaryKeyRelatedField(many=True, allow_empty=False)\n\n\nmodels.ManyToManyField(blank=True)\n\u2192 \nserializers.PrimaryKeyRelatedField(many=True)\n\n\n\n\nThe upshot is this: If you have many to many fields in your models, then make sure you've included the argument \nblank=True\n if you want to allow empty inputs in the equivalent \nModelSerializer\n fields.\n\n\nList fields and allow_null\n\n\nWhen using \nallow_null\n with \nListField\n or a nested \nmany=True\n serializer the previous behavior was to allow \nnull\n values as items in the list. The behavior is now to allow \nnull\n values instead of the list.\n\n\nFor example, take the following field:\n\n\nNestedSerializer(many=True, allow_null=True)\n\n\n\nPreviously the validation behavior would be:\n\n\n\n\n[{\u2026}, null, {\u2026}]\n is \nvalid\n.\n\n\nnull\n is \ninvalid\n.\n\n\n\n\nOur validation behavior as of 3.2.0 is now:\n\n\n\n\n[{\u2026}, null, {\u2026}]\n is \ninvalid\n.\n\n\nnull\n is \nvalid\n.\n\n\n\n\nIf you want to allow \nnull\n child items, you'll need to instead specify \nallow_null\n on the child class, using an explicit \nListField\n instead of \nmany=True\n. For example:\n\n\nListField(child=NestedSerializer(allow_null=True))\n\n\n\nWhat's next?\n\n\nThe 3.3 release is currently planned for the start of October, and will be the last Kickstarter-funded release.\n\n\nThis release is planned to include:\n\n\n\n\nSearch and filtering controls in the browsable API and admin interface.\n\n\nImprovements and public API for the admin interface.\n\n\nImprovements and public API for our templated HTML forms and fields.\n\n\nNested object and list support in HTML forms.\n\n\n\n\nThanks once again to all our sponsors and supporters.",
"text":"There are no new deprecations in 3.2, although a number of existing deprecations have now escalated in line with our deprecation policy. request.DATA was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of request.data instead. request.FILES was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of request.files instead. request.QUERY_PARAMS was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of request.query_params instead. The following ModelSerializer.Meta options have now been removed: write_only_fields , view_name , lookup_field . Use the more general extra_kwargs option instead. The following pagination view attributes and settings have been moved into attributes on the pagination class since 3.1. Their usage was formerly in 'pending deprecation', and has now escalated to 'deprecated'. They will continue to function but will raise errors. view.paginate_by - Use paginator.page_size instead. view.page_query_param - Use paginator.page_query_param instead. view.paginate_by_param - Use paginator.page_size_query_param instead. view.max_paginate_by - Use paginator.max_page_size instead. settings.PAGINATE_BY - Use paginator.page_size instead. settings.PAGINATE_BY_PARAM - Use paginator.page_size_query_param instead. settings.MAX_PAGINATE_BY - Use max_page_size instead.",
"text":"There are no new deprecations in 3.2, although a number of existing deprecations have now escalated in line with our deprecation policy. request.DATA was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of request.data instead. request.QUERY_PARAMS was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of request.query_params instead. The following ModelSerializer.Meta options have now been removed: write_only_fields , view_name , lookup_field . Use the more general extra_kwargs option instead. The following pagination view attributes and settings have been moved into attributes on the pagination class since 3.1. Their usage was formerly in 'pending deprecation', and has now escalated to 'deprecated'. They will continue to function but will raise errors. view.paginate_by - Use paginator.page_size instead. view.page_query_param - Use paginator.page_query_param instead. view.paginate_by_param - Use paginator.page_size_query_param instead. view.max_paginate_by - Use paginator.max_page_size instead. settings.PAGINATE_BY - Use paginator.page_size instead. settings.PAGINATE_BY_PARAM - Use paginator.page_size_query_param instead. settings.MAX_PAGINATE_BY - Use max_page_size instead.",
<p>There are no new deprecations in 3.2, although a number of existing deprecations have now escalated in line with our deprecation policy.</p>
<p>There are no new deprecations in 3.2, although a number of existing deprecations have now escalated in line with our deprecation policy.</p>
<ul>
<ul>
<li><code>request.DATA</code> was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of <code>request.data</code> instead.</li>
<li><code>request.DATA</code> was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of <code>request.data</code> instead.</li>
<li><code>request.FILES</code> was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of <code>request.files</code> instead.</li>
<li><code>request.QUERY_PARAMS</code> was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of <code>request.query_params</code> instead.</li>
<li><code>request.QUERY_PARAMS</code> was put on the deprecation path in 3.0. It has now been removed and its usage will result in an error. Use the more pythonic style of <code>request.query_params</code> instead.</li>
<li>The following <code>ModelSerializer.Meta</code> options have now been removed: <code>write_only_fields</code>, <code>view_name</code>, <code>lookup_field</code>. Use the more general <code>extra_kwargs</code> option instead.</li>
<li>The following <code>ModelSerializer.Meta</code> options have now been removed: <code>write_only_fields</code>, <code>view_name</code>, <code>lookup_field</code>. Use the more general <code>extra_kwargs</code> option instead.</li>
