Ticket #16364: 16364.patch

docs/topics/serialization.txt

@@ -207 +207 @@
 object, but it can cause difficulty in some circumstances.
 
 Consider the case of a list of objects that have foreign key on
-:class:`ContentType`. If you're going to serialize an object that
-refers to a content type, you need to have a way to refer to that
-content type. Content Types are automatically created by Django as
-part of the database synchronization process, so you don't need to
-include content types in a fixture or other serialized data. As a
-result, the primary key of any given content type isn't easy to
-predict - it will depend on how and when :djadmin:`syncdb` was
-executed to create the content types.
+:class:`~django.contrib.conttenttypes.models.ContentType`. If you're going to
+serialize an object that refers to a content type, you need to have a way to
+refer to that content type. Content types are automatically created by Django
+as part of the database synchronization process. As a result, the primary key
+of any given content type isn't easy to predict - it will depend on how and
+when :djadmin:`syncdb` was executed to create the content types. This is also
+true for :class:`~django.contrib.auth.models.Permission`.
 
+.. warning::
+
+    You should never include automatically created objects in a fixture or
+    other serialized data. If the primary keys in the fixture and in the
+    database match by chance, loading the fixture will have no effect. If they
+    don't, you're likely to encounter a :class:`django.db.IntegrityError`.
+
 There is also the matter of convenience. An integer id isn't always
 the most convenient way to refer to an object; sometimes, a
 more natural reference would be helpful.
@@ -381 +387 @@
 ``natural_key()`` methods. You do this by setting a ``dependencies``
 attribute on the ``natural_key()`` method itself.
 
-For example, consider the ``Permission`` model in ``contrib.auth``.
-The following is a simplified version of the ``Permission`` model::
+For example, let's add a natural key to the ``Book`` model from the
+example above::
 
-    class Permission(models.Model):
-        name = models.CharField(max_length=50)
-        content_type = models.ForeignKey(ContentType)
-        codename = models.CharField(max_length=100)
-        # ...
+    class Book(models.Model):
+        name = models.CharField(max_length=100)
+        author = models.ForeignKey(Person)
+
         def natural_key(self):
-            return (self.codename,) + self.content_type.natural_key()
+            return (self.name,) + self.author.natural_key()
 
-The natural key for a ``Permission`` is a combination of the codename for the
-``Permission``, and the ``ContentType`` to which the ``Permission`` applies. This means
-that ``ContentType`` must be serialized before ``Permission``. To define this
-dependency, we add one extra line::
+The natural key for a ``Book`` is a combination of its name and of its
+author.  This means that ``Person`` must be serialized before ``Book``.
+To define this dependency, we add one extra line::
 
-    class Permission(models.Model):
-        # ...
         def natural_key(self):
-            return (self.codename,) + self.content_type.natural_key()
-        natural_key.dependencies = ['contenttypes.contenttype']
+            return (self.name,) + self.author.natural_key()
+        natural_key.dependencies = ['example_app.person']
 
-This definition ensures that ``ContentType`` models are serialized before
-``Permission`` models. In turn, any object referencing ``Permission`` will
-be serialized after both ``ContentType`` and ``Permission``.
+This definition ensures that ``Person`` models are serialized before
+``Book`` models. In turn, any object referencing ``Book`` will be
+serialized after both ``Person`` and ``Book``.