Permalink
Browse files

Fixed #8730: Incorporated (with minor changes) additions/enhancements…

… to one-to-one docs

git-svn-id: http://code.djangoproject.com/svn/django/trunk@8787 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 94da2b8 commit b085ccce6cc26a16d24e7f6a4649a39fc3237570 @ubernostrum ubernostrum committed Sep 1, 2008
Showing with 76 additions and 28 deletions.
  1. +9 −3 docs/ref/models/fields.txt
  2. +38 −23 docs/topics/db/models.txt
  3. +29 −2 docs/topics/db/queries.txt
View
@@ -883,6 +883,8 @@ that control how the relationship functions.
is not provided, Django will assume a default name based upon the names of
the two tables being joined.
+.. _ref-onetoone:
+
``OneToOneField``
-----------------
@@ -897,13 +899,17 @@ another model in some way; :ref:`multi-table-inheritance` is
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
View
@@ -499,40 +499,55 @@ of the intermediate model::
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 were 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; in fact, to handle this you'd typically use
+:ref:`inheritance <model-inheritance>`, which involves an implicit
+one-to-one relation).
+
+As with :class:`~django.db.models.ForeignKey`, a
+:ref:`recursive relationship <recursive-relationships>`
+can be defined and
+:ref:`references to as-yet undefined models <lazy-relationships>`
+can be made; see
+:class:`the model field reference <django.db.models.fields.OneToOneField>`
+for details.
-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::
+.. seealso::
- e = Entry.objects.get(id=2)
- e.entrydetail # returns the related EntryDetail object
+ See the `One-to-one relationship model example`_ for a full example.
-If no object has been assigned to this relationship, Django will raise
-a ``DoesNotExist`` exception.
+.. _One-to-one relationship model example: http://www.djangoproject.com/documentation/models/one_to_one/
-Instances can be assigned to the reverse relationship in the same way as
-you would assign the forward relationship::
+**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>`.
- e.entrydetail = ed
+: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,
View
@@ -916,8 +916,35 @@ above example, if the ``ManyToManyField`` in ``Entry`` had specified
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?
--------------------------------------------

0 comments on commit b085ccc

Please sign in to comment.