Ticket #13418: 13418-r13135.diff

docs/topics/serialization.txt

@@ -197 +197 @@
 ------------
 
 .. versionadded:: 1.2
+
    The ability to use natural keys when serializing/deserializing data was
    added in the 1.2 release.
 
@@ -219 +220 @@
 the most convenient way to refer to an object; sometimes, a
 more natural reference would be helpful.
 
+It is for these reasons that Django provides *natural keys*. A natural
+key is a tuple of values that can be used to uniquely identify an
+object instance without using the primary key value.
+
 Deserialization of natural keys
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-It is for these reasons that Django provides `natural keys`. A natural
-key is a tuple of values that can be used to uniquely identify an
-object instance without using the primary key value.
-
 Consider the following two models::
 
     from django.db import models
@@ -236 +237 @@
 
         birthdate = models.DateField()
 
+        class Meta:
+            unique_together = (('first_name', 'last_name'),)
+
     class Book(models.Model):
         name = models.CharField(max_length=100)
         author = models.ForeignKey(Person)
@@ -278 +282 @@
 
         birthdate = models.DateField()
 
+        class Meta:
+            unique_together = (('first_name', 'last_name'),)
+
 Now books can use that natural key to refer to ``Person`` objects::
 
     ...
@@ -312 +319 @@
         def natural_key(self):
             return (self.first_name, self.last_name)
 
-Then, when you call ``serializers.serialize()``, you provide a
-``use_natural_keys=True`` argument::
+        class Meta:
+            unique_together = (('first_name', 'last_name'),)
+
+That method should always return a natural key tuple as per our design
+(``(first name, last name)`` in this example). Then, when you call
+``serializers.serialize()``, you provide a ``use_natural_keys=True`` argument::
 
     >>> serializers.serialize([book1, book2], format='json', indent=2, use_natural_keys=True)