From ed93e13a1c6f792e14176bdaa5e96d0fa2c63a2f Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 1 Dec 2014 12:20:07 +0000 Subject: Update documentation --- api-guide/relations/index.html | 110 +++++++++++++++++++++++++---------------- 1 file changed, 67 insertions(+), 43 deletions(-) (limited to 'api-guide/relations') diff --git a/api-guide/relations/index.html b/api-guide/relations/index.html index 3f3a2460..0fe39d35 100644 --- a/api-guide/relations/index.html +++ b/api-guide/relations/index.html @@ -62,7 +62,7 @@
GitHub - Serializer relations +
  • + Validators +
    • +
  • Authentication
    • @@ -263,6 +267,10 @@ 2.4 Announcement +
  • + 3.0 Announcement +
    • +
  • Kickstarter Announcement
    • @@ -341,6 +349,10 @@ +
  • + Inspecting automatically generated relationships. +
    • + @@ -350,7 +362,7 @@
  • - RelatedField + StringRelatedField
  • @@ -401,6 +413,10 @@
    • +
  • + The queryset argument +
    • +
  • Reverse relations
    • @@ -417,10 +433,6 @@ Advanced Hyperlinked fields -
  • - Deprecated APIs -
    • - @@ -452,7 +464,10 @@ -

    Serializer relations

    +
    +

    Note: This is the documentation for the version 3.0 of REST framework. Documentation for version 2.4 is also available.

    +
    +

    Serializer relations

    Bad programmers worry about the code. Good programmers worry about data structures and their relationships.

    @@ -462,6 +477,17 @@ Good programmers worry about data structures and their relationships.

    Note: The relational fields are declared in relations.py, but by convention you should import them from the serializers module, using from rest_framework import serializers and refer to fields as serializers.<FieldName>.

    +

    Inspecting automatically generated relationships.

    +

    When using the ModelSerializer 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.

    +

    To do so, open the Django shell, using python manage.py shell, then import the serializer class, instantiate it, and print the object representation…

    +
    >>> from myapp.serializers import AccountSerializer
+>>> serializer = AccountSerializer()
+>>> print repr(serializer)  # Or `print(repr(serializer))` in Python 3.x.
+AccountSerializer():
+    id = IntegerField(label='ID', read_only=True)
+    name = CharField(allow_blank=True, max_length=100, required=False)
+    owner = PrimaryKeyRelatedField(queryset=User.objects.all())
+

    API Reference

    In 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.

    class Album(models.Model):
@@ -481,11 +507,11 @@ class Track(models.Model):
     def __unicode__(self):
         return '%d: %s' % (self.order, self.title)
    -

    RelatedField

    -

    RelatedField may be used to represent the target of the relationship using its __unicode__ method.

    +

    StringRelatedField

    +

    StringRelatedField may be used to represent the target of the relationship using its __unicode__ method.

    For example, the following serializer.

    class AlbumSerializer(serializers.ModelSerializer):
-    tracks = serializers.RelatedField(many=True)
+    tracks = serializers.StringRelatedField(many=True)
 
     class Meta:
         model = Album
@@ -533,16 +559,19 @@ class Track(models.Model):
 
    By default this field is read-write, although you can change this behavior using the read_only flag.
    
 
    Arguments:
    
 
      
+
    • queryset - The queryset used for model instance lookups when validating the field input. Relationships must either set a queryset explicitly, or set read_only=True.
      • 
 
    • many - If applied to a to-many relationship, you should set this argument to True.
      • 
-
    • required - If set to False, the field will accept values of None or the empty-string for nullable relationships.
      • 
-
    • queryset - By default ModelSerializer classes will use the default queryset for the relationship.  Serializer classes must either set a queryset explicitly, or set read_only=True.
      • 
+
    • allow_null - If set to True, the field will accept values of None or the empty string for nullable relationships. Defaults to False.
      • 
 
    
 
    HyperlinkedRelatedField
    
 
    HyperlinkedRelatedField may be used to represent the target of the relationship using a hyperlink.
    
 
    For example, the following serializer:
    
 
    class AlbumSerializer(serializers.ModelSerializer):
-    tracks = serializers.HyperlinkedRelatedField(many=True, read_only=True,
-                                                 view_name='track-detail')
+    tracks = serializers.HyperlinkedRelatedField(
+        many=True,
+        read_only=True,
+        view_name='track-detail'
+    )
 
     class Meta:
         model = Album
@@ -563,19 +592,23 @@ class Track(models.Model):
 
    By default this field is read-write, although you can change this behavior using the read_only flag.
    
 
    Arguments:
    
 
      
-
    • view_name - The view name that should be used as the target of the relationship.  If you're using the standard router classes this wil be a string with the format <modelname>-detail. required.
      • 
+
    • view_name - The view name that should be used as the target of the relationship.  If you're using the standard router classes this will be a string with the format <modelname>-detail. required.
      • 
+
    • queryset - The queryset used for model instance lookups when validating the field input. Relationships must either set a queryset explicitly, or set read_only=True.
      • 
 
    • many - If applied to a to-many relationship, you should set this argument to True.
      • 
-
    • required - If set to False, the field will accept values of None or the empty-string for nullable relationships.
      • 
-
    • queryset - By default ModelSerializer classes will use the default queryset for the relationship.  Serializer classes must either set a queryset explicitly, or set read_only=True.
      • 
+
    • allow_null - If set to True, the field will accept values of None or the empty string for nullable relationships. Defaults to False.
      • 
 
    • lookup_field - The field on the target that should be used for the lookup.  Should correspond to a URL keyword argument on the referenced view.  Default is 'pk'.
      • 
+
    • lookup_url_kwarg - The name of the keyword argument defined in the URL conf that corresponds to the lookup field. Defaults to using the same value as lookup_field.
      • 
 
    • format - If using format suffixes, hyperlinked fields will use the same format suffix for the target unless overridden by using the format argument.
      • 
 
    
 
    SlugRelatedField
    
 
    SlugRelatedField may be used to represent the target of the relationship using a field on the target.
    
 
    For example, the following serializer:
    
 
    class AlbumSerializer(serializers.ModelSerializer):
-    tracks = serializers.SlugRelatedField(many=True, read_only=True,
-                                          slug_field='title')
+    tracks = serializers.SlugRelatedField(
+        many=True,
+        read_only=True,
+        slug_field='title'
+     )
 
     class Meta:
         model = Album
@@ -598,9 +631,9 @@ class Track(models.Model):
 
    Arguments:
    
 
      
 
    • 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.  required
      • 
+
    • queryset - The queryset used for model instance lookups when validating the field input. Relationships must either set a queryset explicitly, or set read_only=True.
      • 
 
    • many - If applied to a to-many relationship, you should set this argument to True.
      • 
-
    • required - If set to False, the field will accept values of None or the empty-string for nullable relationships.
      • 
-
    • queryset - By default ModelSerializer classes will use the default queryset for the relationship.  Serializer classes must either set a queryset explicitly, or set read_only=True.
      • 
+
    • allow_null - If set to True, the field will accept values of None or the empty string for nullable relationships. Defaults to False.
      • 
 
    
 
    HyperlinkedIdentityField
    
 
    This field can be applied as an identity relationship, such as the 'url' field on  a HyperlinkedModelSerializer.  It can also be used for an attribute on the object.  For example, the following serializer:
    
@@ -637,7 +670,7 @@ class Track(models.Model):
         fields = ('order', 'title')
 
 class AlbumSerializer(serializers.ModelSerializer):
-    tracks = TrackSerializer(many=True)
+    tracks = TrackSerializer(many=True, read_only=True)
 
     class Meta:
         model = Album
@@ -656,14 +689,14 @@ class AlbumSerializer(serializers.ModelSerializer):
 }
 
    
 
    Custom relational fields
    
-
    To implement a custom relational field, you should override RelatedField, and implement the .to_native(self, value) method.  This method takes the target of the field as the value argument, and should return the representation that should be used to serialize the target.
    
-
    If you want to implement a read-write relational field, you must also implement the .from_native(self, data) method, and add read_only = False to the class definition.
    
+
    To implement a custom relational field, you should override RelatedField, and implement the .to_representation(self, value) method. This method takes the target of the field as the value argument, and should return the representation that should be used to serialize the target. The value argument will typically be a model instance.
    
+
    If you want to implement a read-write relational field, you must also implement the .to_internal_value(self, data) method.
    
 
    Example
    
 
    For, example, we could define a relational field, to serialize a track to a custom string representation, using its ordering, title, and duration.
    
 
    import time
 
 class TrackListingField(serializers.RelatedField):
-    def to_native(self, value):
+    def to_representation(self, value):
         duration = time.strftime('%M:%S', time.gmtime(value.duration))
         return 'Track %d: %s (%s)' % (value.order, value.name, duration)
 
@@ -688,6 +721,11 @@ class AlbumSerializer(serializers.ModelSerializer):
 
    
 
    
 
    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:
    
 
    class AlbumSerializer(serializers.ModelSerializer):
@@ -744,7 +782,7 @@ class Note(models.Model):
     A custom field to use for the `tagged_object` generic relationship.
     """
 
-    def to_native(self, value):
+    def to_representation(self, value):
         """
         Serialize tagged objects to a simple textual representation.
         """
@@ -754,8 +792,8 @@ class Note(models.Model):
             return 'Note: ' + value.text
         raise Exception('Unexpected type of tagged object')
 
    
-
    If you need the target of the relationship to have a nested representation, you can  use the required serializers inside the .to_native() method:
    
-
        def to_native(self, value):
+
    If you need the target of the relationship to have a nested representation, you can use the required serializers inside the .to_native() method:
    
+
        def to_representation(self, value):
         """
         Serialize bookmark instances using a bookmark serializer,
         and note instances using a note serializer.
@@ -800,20 +838,6 @@ attributes are not configured to correctly match the URL conf.
    
         return queryset.get(account=account, slug=slug)
 
    
 
    
-
    Deprecated APIs
    
-
    The following classes have been deprecated, in favor of the many=<bool> syntax.
-They continue to function, but their usage will raise a PendingDeprecationWarning, which is silent by default.
    
-
      
-
    • ManyRelatedField
      • 
-
    • ManyPrimaryKeyRelatedField
      • 
-
    • ManyHyperlinkedRelatedField
      • 
-
    • ManySlugRelatedField
      • 
-
    
-
    The null=<bool> flag has been deprecated in favor of the required=<bool> flag.  It will continue to function, but will raise a PendingDeprecationWarning.
    
-
    In the 2.3 release, these warnings will be escalated to a DeprecationWarning, which is loud by default.
-In the 2.4 release, these parts of the API will be removed entirely.
    
-
    For more details see the 2.2 release announcement.
    
-
    
 
    Third Party Packages
    
 
    The following third party packages are also available.
    
 
    DRF Nested Routers
    
@@ -832,7 +856,7 @@ In the 2.4 release, these parts of the API will be removed entirely.
    
   
 
   
 
-- 
cgit v1.2.3