Fixed #8730: Incorporated (with minor changes) additions/enhancements to one-to-one docs

    is not provided, Django will assume a default name based upon the names of

    the two tables being joined.

.. _ref-onetoone:

``OneToOneField``

-----------------

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

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,

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?

--------------------------------------------