PageRenderTime 43ms CodeModel.GetById 19ms RepoModel.GetById 0ms app.codeStats 0ms

/docs/ref/models/relations.txt

https://code.google.com/p/mango-py/
Plain Text | 105 lines | 73 code | 32 blank | 0 comment | 0 complexity | ba4e35d43cdb32cd9f6d59ea61f22c73 MD5 | raw file
Possible License(s): BSD-3-Clause
  1. =========================
  2. Related objects reference
  3. =========================
  4. .. currentmodule:: django.db.models.fields.related
  5. .. class:: RelatedManager
  6. A "related manager" is a manager used in a one-to-many or many-to-many
  7. related context. This happens in two cases:
  8. * The "other side" of a :class:`~django.db.models.ForeignKey` relation.
  9. That is::
  10. class Reporter(models.Model):
  11. ...
  12. class Article(models.Model):
  13. reporter = models.ForeignKey(Reporter)
  14. In the above example, the methods below will be available on
  15. the manager ``reporter.article_set``.
  16. * Both sides of a :class:`~django.db.models.ManyToManyField` relation::
  17. class Topping(models.Model):
  18. ...
  19. class Pizza(models.Model):
  20. toppings = models.ManyToManyField(Topping)
  21. In this example, the methods below will be available both on
  22. ``topping.pizza_set`` and on ``pizza.toppings``.
  23. These related managers have some extra methods:
  24. .. method:: add(obj1, [obj2, ...])
  25. Adds the specified model objects to the related object set.
  26. Example::
  27. >>> b = Blog.objects.get(id=1)
  28. >>> e = Entry.objects.get(id=234)
  29. >>> b.entry_set.add(e) # Associates Entry e with Blog b.
  30. .. method:: create(**kwargs)
  31. Creates a new object, saves it and puts it in the related object set.
  32. Returns the newly created object::
  33. >>> b = Blog.objects.get(id=1)
  34. >>> e = b.entry_set.create(
  35. ... headline='Hello',
  36. ... body_text='Hi',
  37. ... pub_date=datetime.date(2005, 1, 1)
  38. ... )
  39. # No need to call e.save() at this point -- it's already been saved.
  40. This is equivalent to (but much simpler than)::
  41. >>> b = Blog.objects.get(id=1)
  42. >>> e = Entry(
  43. ... blog=b,
  44. ... headline='Hello',
  45. ... body_text='Hi',
  46. ... pub_date=datetime.date(2005, 1, 1)
  47. ... )
  48. >>> e.save(force_insert=True)
  49. Note that there's no need to specify the keyword argument of the model
  50. that defines the relationship. In the above example, we don't pass the
  51. parameter ``blog`` to ``create()``. Django figures out that the new
  52. ``Entry`` object's ``blog`` field should be set to ``b``.
  53. .. method:: remove(obj1, [obj2, ...])
  54. Removes the specified model objects from the related object set::
  55. >>> b = Blog.objects.get(id=1)
  56. >>> e = Entry.objects.get(id=234)
  57. >>> b.entry_set.remove(e) # Disassociates Entry e from Blog b.
  58. In order to prevent database inconsistency, this method only exists on
  59. :class:`~django.db.models.ForeignKey` objects where ``null=True``. If
  60. the related field can't be set to ``None`` (``NULL``), then an object
  61. can't be removed from a relation without being added to another. In the
  62. above example, removing ``e`` from ``b.entry_set()`` is equivalent to
  63. doing ``e.blog = None``, and because the ``blog``
  64. :class:`~django.db.models.ForeignKey` doesn't have ``null=True``, this
  65. is invalid.
  66. .. method:: clear()
  67. Removes all objects from the related object set::
  68. >>> b = Blog.objects.get(id=1)
  69. >>> b.entry_set.clear()
  70. Note this doesn't delete the related objects -- it just disassociates
  71. them.
  72. Just like ``remove()``, ``clear()`` is only available on
  73. :class:`~django.db.models.ForeignKey`\s where ``null=True``.