Ticket #8730: t8730-r8761.diff

docs/ref/models/fields.txt

@@ -882 +882 @@
     The name of the table to create for storing the many-to-many data. If this
     is not provided, Django will assume a default name based upon the names of
     the two tables being joined.
+
+.. _ref-onetoone:
 
 ``OneToOneField``
 -----------------
@@ -897 +899 @@
 implemented by adding an implicit one-to-one relation from the child
 model to the parent model, for example.
 
-One positional argument is required: the class to which the model will
-be related.
+One positional argument is required: the class to which the model will be
+related. This works exactly the same as it does for :class:`ForeignKey`,
+including all the options regarding :ref:`recursive <recursive-relationships>`
+and :ref:`lazy <lazy-relationships>` relationships.
+
+.. _onetoone-arguments:
 
 Additionally, ``OneToOneField`` accepts all of the extra arguments
 accepted by :class:`ForeignKey`, plus one extra argument:
 
-.. attribute: OneToOneField.parent_link
+.. attribute:: OneToOneField.parent_link
 
     When ``True`` and used in a model which inherits from another
     (concrete) model, indicates that this field should be used as the

docs/topics/db/models.txt

@@ -499 +499 @@
     
 
 One-to-one relationships
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-One-to-one relationships are very similar to many-to-one relationships. If you
-define a :class:`~django.db.models.OneToOneField` on your model, instances of
-that model will have access to the related object via a simple attribute of the
-model.
+To define a one-to-one relationship, use
+:class:`~django.db.models.OneToOneField`. You use it just like any other
+``Field`` type: by including it as a class attribute of your model.
 
-For example::
+This is most useful on the primary key of an object when that object "extends"
+another object in some way.
 
-    class EntryDetail(models.Model):
-        entry = models.OneToOneField(Entry)
-        details = models.TextField()
+:class:`~django.db.models.OneToOneField` requires a positional argument: the
+class to which the model is related.
 
-    ed = EntryDetail.objects.get(id=2)
-    ed.entry # Returns the related Entry object.
+For example, if you're building a database of "places", you would build pretty
+standard stuff such as address, phone number, etc. in the database. Then, if you
+wanted to build a database of restaurants on top of the places, instead of
+repeating yourself and replicating those fields in the ``Restaurant`` model, you
+could make ``Restaurant`` have a :class:`~django.db.models.OneToOneField` to
+``Place`` (because a restaurant "is-a" place).
 
-The difference comes in "reverse" queries. The related model in a one-to-one
-relationship also has access to a :class:`~django.db.models.Manager` object, but
-that :class:`~django.db.models.Manager` represents a single object, rather than
-a collection of objects::
+As with :class:`~django.db.models.ForeignKey`, a :ref:`relationship to self
+<recursive-relationships>` can be defined and :ref:`references to as-yet
+undefined models <lazy-relationships>` can be made; see :ref:`the model field
+reference <ref-onetoone>` for details.
 
-    e = Entry.objects.get(id=2)
-    e.entrydetail # returns the related EntryDetail object
+.. seealso::
 
-If no object has been assigned to this relationship, Django will raise
-a ``DoesNotExist`` exception.
+    See the `One-to-one relationship model example`_ for a full example.
 
-Instances can be assigned to the reverse relationship in the same way as
-you would assign the forward relationship::
+.. _One-to-one relationship model example: http://www.djangoproject.com/documentation/models/one_to_one/
 
-    e.entrydetail = ed
+**New in Django development version**
+
+:class:`~django.db.models.OneToOneField` fields also accept one optional argument
+described in the :ref:`model field reference <ref-onetoone>`.
+
+:class:`~django.db.models.OneToOneField` classes used to automatically become
+the primary key on a model. This is no longer true (although you can manually
+pass in the :attr:`~django.db.models.Field.primary_key` argument if you like).
+Thus, it's now possible to have multiple fields of type
+:class:`~django.db.models.OneToOneField` on a single model.
 
 Models across files
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 It's perfectly OK to relate a model to one from another app. To do this, just
 import the related model at the top of the model that holds your model. Then,

docs/topics/db/queries.txt

@@ -916 +916 @@
 One-to-one relationships
 ------------------------
 
-The semantics of one-to-one relationships will be changing soon, so we don't
-recommend you use them.
+One-to-one relationships are very similar to many-to-one relationships. If you
+define a :class:`~django.db.models.OneToOneField` on your model, instances of
+that model will have access to the related object via a simple attribute of the
+model.
+
+For example::
+
+    class EntryDetail(models.Model):
+        entry = models.OneToOneField(Entry)
+        details = models.TextField()
+
+    ed = EntryDetail.objects.get(id=2)
+    ed.entry # Returns the related Entry object.
+
+The difference comes in "reverse" queries. The related model in a one-to-one
+relationship also has access to a :class:`~django.db.models.Manager` object, but
+that :class:`~django.db.models.Manager` represents a single object, rather than
+a collection of objects::
+
+    e = Entry.objects.get(id=2)
+    e.entrydetail # returns the related EntryDetail object
+
+If no object has been assigned to this relationship, Django will raise
+a ``DoesNotExist`` exception.
+
+Instances can be assigned to the reverse relationship in the same way as
+you would assign the forward relationship::
+
+    e.entrydetail = ed
 
 How are the backward relationships possible?
 --------------------------------------------