.. =========================
   Related objects reference
   =========================

=====================================
リレーションオブジェクトリファレンス
=====================================

:revision-up-to: 17812 (1.4)

.. currentmodule:: django.db.models.fields.related

.. class:: RelatedManager

    .. A "related manager" is a manager used in a one-to-many or many-to-many
       related context. This happens in two cases:

    "Related manager" は一対多リレーションや多対多リレーションに関連して
    使われます。以下 2 つの場合に登場します:

    .. * The "other side" of a :class:`~django.db.models.ForeignKey` relation.
         That is::

    * :class:`~django.db.models.ForeignKey` リレーションの「向こう側」。
      つまり::

            class Reporter(models.Model):
                ...

            class Article(models.Model):
                reporter = models.ForeignKey(Reporter)

      .. In the above example, the methods below will be available on
         the manager ``reporter.article_set``.

      上の例では、マネージャ ``reporter.article_set`` で後述のメソッドが使用可能
      になります (訳注: ここでの ``reporter`` は ``Reporter`` のインスタンス
      です)。

    .. * Both sides of a :class:`~django.db.models.ManyToManyField` relation::

    * :class:`~django.db.models.ManyToManyField` リレーションの「両側」::

            class Topping(models.Model):
                ...

            class Pizza(models.Model):
                toppings = models.ManyToManyField(Topping)

      .. In this example, the methods below will be available both on
         ``topping.pizza_set`` and on ``pizza.toppings``.

      この例では、 ``topping.pizza_set`` と ``pizza.toppings`` で後述のメソッド
      が使用可能になります (訳注: ここでの ``topping`` は ``Topping`` クラスの、
      ``pizza`` は ``Pizza`` クラスのインスタンスです) 。

    .. These related managers have some extra methods:

    これらの "related manager" はいくつか追加のメソッドを持っています:

    .. method:: add(obj1, [obj2, ...])

        .. Adds the specified model objects to the related object set.

        指定したモデルオブジェクトを、被リレーションのセットに追加し (リレーショ
        ン先のオブジェクトからリレーションを張り) ます。

        使い方::

            >>> b = Blog.objects.get(id=1)
            >>> e = Entry.objects.get(id=234)
            >>> b.entry_set.add(e) # Entry e を Blog b に関連づけます。

    .. method:: create(**kwargs)

        .. Creates a new object, saves it and puts it in the related object set.
           Returns the newly created object::

        新たなオブジェクトを生成し、保存して、被リレーションのセットに追加しま
        す。新たに生成されたオブジェクトを返します::

            >>> b = Blog.objects.get(id=1)
            >>> e = b.entry_set.create(
            ...     headline='Hello',
            ...     body_text='Hi',
            ...     pub_date=datetime.date(2005, 1, 1)
            ... )

            # e は自動的に保存されるので、 e.save() は呼ばなくてかまいません

        .. This is equivalent to (but much simpler than)::

        上の例は、下記と同じ処理を実現します::

            >>> b = Blog.objects.get(id=1)
            >>> e = Entry(
            ...      blog=b,
            ...      headline='Hello',
            ...      body_text='Hi',
            ...      pub_date=datetime.date(2005, 1, 1)
            ...  )
            >>> e.save()

        .. Note that there's no need to specify the keyword argument of the model
           that defines the relationship. In the above example, we don't pass the
           parameter ``blog`` to ``create()``. Django figures out that the new
           ``Entry`` object's ``blog`` field should be set to ``b``.

        リレーションを定義するためのキーワード引数を指定する必要はないので注意
        してください。上の例では、 ``create()`` に ``blog`` パラメタを渡してい
        ません。 Django は ``Entry`` オブジェクトの ``blog`` フィールドに ``b``
        をセットすべきだと自動的に理解します。

    .. method:: remove(obj1, [obj2, ...])

        .. Removes the specified model objects from the related object set::

        指定したオブジェクトを被リレーションセットから除去します::

            >>> b = Blog.objects.get(id=1)
            >>> e = Entry.objects.get(id=234)
            >>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.

        .. In order to prevent database inconsistency, this method only exists on
           :class:`~django.db.models.ForeignKey` objects where ``null=True``. If
           the related field can't be set to ``None`` (``NULL``), then an object
           can't be removed from a relation without being added to another. In the
           above example, removing ``e`` from ``b.entry_set()`` is equivalent to
           doing ``e.blog = None``, and because the ``blog``
           :class:`~django.db.models.ForeignKey` doesn't have ``null=True``, this
           is invalid.

        データベースの一貫性を保持するために、このメソッドは ``null=True`` の
        :class:`~django.db.models.ForeignKey` オブジェクトでしか使えません。
        リレーションフィールドの値を
        ``None`` (``NULL``) にできなければ、あるオブジェクトを
        被リレーションセットから除去したときに、何らかの他のオブジェクトに対して
        リレーションを張り直さなければならないからです。上の例で、
        ``b.entry_set()`` からの ``e`` の除去は ``e.blog = None`` に
        相当しますが、 ``blog`` の :class:`~django.db.models.ForeignKey` には
        ``null=True`` が設定されていないので、これは無効な操作です。

    .. method:: clear()

        .. Removes all objects from the related object set::

        被リレーションセットから、全てのオブジェクトを除去します::

            >>> b = Blog.objects.get(id=1)
            >>> b.entry_set.clear()

        .. Note this doesn't delete the related objects -- it just disassociates
           them.

        このメソッドは、リレーション元のオブジェクトを削除せず、ただ単に
        リレーションを解除するだけなので注意してください。

        .. Just like ``remove()``, ``clear()`` is only available on
           :class:`~django.db.models.ForeignKey`\s where ``null=True``.

        ``remove()`` と同様、 ``clear()`` は ``null=True`` の
        :class:`~django.db.models.ForeignKey` でしか使えません。