From b085ccce6cc26a16d24e7f6a4649a39fc3237570 Mon Sep 17 00:00:00 2001 From: James Bennett Date: Mon, 1 Sep 2008 09:32:41 +0000 Subject: [PATCH] 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 --- docs/ref/models/fields.txt | 12 ++++++-- docs/topics/db/models.txt | 61 ++++++++++++++++++++++++-------------- docs/topics/db/queries.txt | 31 +++++++++++++++++-- 3 files changed, 76 insertions(+), 28 deletions(-) diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index bf5d7b30cd3..f5c8f72356e 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -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 ` +and :ref:`lazy ` 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 diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index 9a2a00920a1..9e9ad69edb2 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -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 `, which involves an implicit +one-to-one relation). -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:`recursive relationship ` +can be defined and +:ref:`references to as-yet undefined models ` +can be made; see +:class:`the model field reference ` +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 `. + +: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, diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt index 4fb12624ed1..bf87b613289 100644 --- a/docs/topics/db/queries.txt +++ b/docs/topics/db/queries.txt @@ -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? --------------------------------------------