Django-1.2.1/tests/modeltests/many_to_many/models.py

   1 """
   2 5. Many-to-many relationships
   3
   4 To define a many-to-many relationship, use ``ManyToManyField()``.
   5
   6 In this example, an ``Article`` can be published in multiple ``Publication``
   7 objects, and a ``Publication`` has multiple ``Article`` objects.
   8 """
   9
  10 from django.db import models
  11
  12 class Publication(models.Model):
  13     title = models.CharField(max_length=30)
  14
  15     def __unicode__(self):
  16         return self.title
  17
  18     class Meta:
  19         ordering = ('title',)
  20
  21 class Article(models.Model):
  22     headline = models.CharField(max_length=100)
  23     publications = models.ManyToManyField(Publication)
  24
  25     def __unicode__(self):
  26         return self.headline
  27
  28     class Meta:
  29         ordering = ('headline',)
  30
  31 __test__ = {'API_TESTS':"""
  32 # Create a couple of Publications.
  33 >>> p1 = Publication(id=None, title='The Python Journal')
  34 >>> p1.save()
  35 >>> p2 = Publication(id=None, title='Science News')
  36 >>> p2.save()
  37 >>> p3 = Publication(id=None, title='Science Weekly')
  38 >>> p3.save()
  39
  40 # Create an Article.
  41 >>> a1 = Article(id=None, headline='Django lets you build Web apps easily')
  42
  43 # You can't associate it with a Publication until it's been saved.
  44 >>> a1.publications.add(p1)
  45 Traceback (most recent call last):
  46 ...
  47 ValueError: 'Article' instance needs to have a primary key value before a many-to-many relationship can be used.
  48
  49 # Save it!
  50 >>> a1.save()
  51
  52 # Associate the Article with a Publication.
  53 >>> a1.publications.add(p1)
  54
  55 # Create another Article, and set it to appear in both Publications.
  56 >>> a2 = Article(id=None, headline='NASA uses Python')
  57 >>> a2.save()
  58 >>> a2.publications.add(p1, p2)
  59 >>> a2.publications.add(p3)
  60
  61 # Adding a second time is OK
  62 >>> a2.publications.add(p3)
  63
  64 # Adding an object of the wrong type raises TypeError
  65 >>> a2.publications.add(a1)
  66 Traceback (most recent call last):
  67 ...
  68 TypeError: 'Publication' instance expected
  69
  70 # Add a Publication directly via publications.add by using keyword arguments.
  71 >>> new_publication = a2.publications.create(title='Highlights for Children')
  72
  73 # Article objects have access to their related Publication objects.
  74 >>> a1.publications.all()
  75 [<Publication: The Python Journal>]
  76 >>> a2.publications.all()
  77 [<Publication: Highlights for Children>, <Publication: Science News>, <Publication: Science Weekly>, <Publication: The Python Journal>]
  78
  79 # Publication objects have access to their related Article objects.
  80 >>> p2.article_set.all()
  81 [<Article: NASA uses Python>]
  82 >>> p1.article_set.all()
  83 [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
  84 >>> Publication.objects.get(id=4).article_set.all()
  85 [<Article: NASA uses Python>]
  86
  87 # We can perform kwarg queries across m2m relationships
  88 >>> Article.objects.filter(publications__id__exact=1)
  89 [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
  90 >>> Article.objects.filter(publications__pk=1)
  91 [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
  92 >>> Article.objects.filter(publications=1)
  93 [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
  94 >>> Article.objects.filter(publications=p1)
  95 [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
  96
  97 >>> Article.objects.filter(publications__title__startswith="Science")
  98 [<Article: NASA uses Python>, <Article: NASA uses Python>]
  99
 100 >>> Article.objects.filter(publications__title__startswith="Science").distinct()
 101 [<Article: NASA uses Python>]
 102
 103 # The count() function respects distinct() as well.
 104 >>> Article.objects.filter(publications__title__startswith="Science").count()
 105 2
 106
 107 >>> Article.objects.filter(publications__title__startswith="Science").distinct().count()
 108 1
 109
 110 >>> Article.objects.filter(publications__in=[1,2]).distinct()
 111 [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
 112 >>> Article.objects.filter(publications__in=[1,p2]).distinct()
 113 [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
 114 >>> Article.objects.filter(publications__in=[p1,p2]).distinct()
 115 [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
 116
 117 # Reverse m2m queries are supported (i.e., starting at the table that doesn't
 118 # have a ManyToManyField).
 119 >>> Publication.objects.filter(id__exact=1)
 120 [<Publication: The Python Journal>]
 121 >>> Publication.objects.filter(pk=1)
 122 [<Publication: The Python Journal>]
 123
 124 >>> Publication.objects.filter(article__headline__startswith="NASA")
 125 [<Publication: Highlights for Children>, <Publication: Science News>, <Publication: Science Weekly>, <Publication: The Python Journal>]
 126
 127 >>> Publication.objects.filter(article__id__exact=1)
 128 [<Publication: The Python Journal>]
 129 >>> Publication.objects.filter(article__pk=1)
 130 [<Publication: The Python Journal>]
 131 >>> Publication.objects.filter(article=1)
 132 [<Publication: The Python Journal>]
 133 >>> Publication.objects.filter(article=a1)
 134 [<Publication: The Python Journal>]
 135
 136 >>> Publication.objects.filter(article__in=[1,2]).distinct()
 137 [<Publication: Highlights for Children>, <Publication: Science News>, <Publication: Science Weekly>, <Publication: The Python Journal>]
 138 >>> Publication.objects.filter(article__in=[1,a2]).distinct()
 139 [<Publication: Highlights for Children>, <Publication: Science News>, <Publication: Science Weekly>, <Publication: The Python Journal>]
 140 >>> Publication.objects.filter(article__in=[a1,a2]).distinct()
 141 [<Publication: Highlights for Children>, <Publication: Science News>, <Publication: Science Weekly>, <Publication: The Python Journal>]
 142
 143 # Excluding a related item works as you would expect, too (although the SQL
 144 # involved is a little complex).
 145 >>> Article.objects.exclude(publications=p2)
 146 [<Article: Django lets you build Web apps easily>]
 147
 148 # If we delete a Publication, its Articles won't be able to access it.
 149 >>> p1.delete()
 150 >>> Publication.objects.all()
 151 [<Publication: Highlights for Children>, <Publication: Science News>, <Publication: Science Weekly>]
 152 >>> a1 = Article.objects.get(pk=1)
 153 >>> a1.publications.all()
 154 []
 155
 156 # If we delete an Article, its Publications won't be able to access it.
 157 >>> a2.delete()
 158 >>> Article.objects.all()
 159 [<Article: Django lets you build Web apps easily>]
 160 >>> p2.article_set.all()
 161 []
 162
 163 # Adding via the 'other' end of an m2m
 164 >>> a4 = Article(headline='NASA finds intelligent life on Earth')
 165 >>> a4.save()
 166 >>> p2.article_set.add(a4)
 167 >>> p2.article_set.all()
 168 [<Article: NASA finds intelligent life on Earth>]
 169 >>> a4.publications.all()
 170 [<Publication: Science News>]
 171
 172 # Adding via the other end using keywords
 173 >>> new_article = p2.article_set.create(headline='Oxygen-free diet works wonders')
 174 >>> p2.article_set.all()
 175 [<Article: NASA finds intelligent life on Earth>, <Article: Oxygen-free diet works wonders>]
 176 >>> a5 = p2.article_set.all()[1]
 177 >>> a5.publications.all()
 178 [<Publication: Science News>]
 179
 180 # Removing publication from an article:
 181 >>> a4.publications.remove(p2)
 182 >>> p2.article_set.all()
 183 [<Article: Oxygen-free diet works wonders>]
 184 >>> a4.publications.all()
 185 []
 186
 187 # And from the other end
 188 >>> p2.article_set.remove(a5)
 189 >>> p2.article_set.all()
 190 []
 191 >>> a5.publications.all()
 192 []
 193
 194 # Relation sets can be assigned. Assignment clears any existing set members
 195 >>> p2.article_set = [a4, a5]
 196 >>> p2.article_set.all()
 197 [<Article: NASA finds intelligent life on Earth>, <Article: Oxygen-free diet works wonders>]
 198 >>> a4.publications.all()
 199 [<Publication: Science News>]
 200 >>> a4.publications = [p3]
 201 >>> p2.article_set.all()
 202 [<Article: Oxygen-free diet works wonders>]
 203 >>> a4.publications.all()
 204 [<Publication: Science Weekly>]
 205
 206 # Relation sets can be cleared:
 207 >>> p2.article_set.clear()
 208 >>> p2.article_set.all()
 209 []
 210 >>> a4.publications.all()
 211 [<Publication: Science Weekly>]
 212
 213 # And you can clear from the other end
 214 >>> p2.article_set.add(a4, a5)
 215 >>> p2.article_set.all()
 216 [<Article: NASA finds intelligent life on Earth>, <Article: Oxygen-free diet works wonders>]
 217 >>> a4.publications.all()
 218 [<Publication: Science News>, <Publication: Science Weekly>]
 219 >>> a4.publications.clear()
 220 >>> a4.publications.all()
 221 []
 222 >>> p2.article_set.all()
 223 [<Article: Oxygen-free diet works wonders>]
 224
 225 # Relation sets can also be set using primary key values
 226 >>> p2.article_set = [a4.id, a5.id]
 227 >>> p2.article_set.all()
 228 [<Article: NASA finds intelligent life on Earth>, <Article: Oxygen-free diet works wonders>]
 229 >>> a4.publications.all()
 230 [<Publication: Science News>]
 231 >>> a4.publications = [p3.id]
 232 >>> p2.article_set.all()
 233 [<Article: Oxygen-free diet works wonders>]
 234 >>> a4.publications.all()
 235 [<Publication: Science Weekly>]
 236
 237 # Recreate the article and Publication we have deleted.
 238 >>> p1 = Publication(id=None, title='The Python Journal')
 239 >>> p1.save()
 240 >>> a2 = Article(id=None, headline='NASA uses Python')
 241 >>> a2.save()
 242 >>> a2.publications.add(p1, p2, p3)
 243
 244 # Bulk delete some Publications - references to deleted publications should go
 245 >>> Publication.objects.filter(title__startswith='Science').delete()
 246 >>> Publication.objects.all()
 247 [<Publication: Highlights for Children>, <Publication: The Python Journal>]
 248 >>> Article.objects.all()
 249 [<Article: Django lets you build Web apps easily>, <Article: NASA finds intelligent life on Earth>, <Article: NASA uses Python>, <Article: Oxygen-free diet works wonders>]
 250 >>> a2.publications.all()
 251 [<Publication: The Python Journal>]
 252
 253 # Bulk delete some articles - references to deleted objects should go
 254 >>> q = Article.objects.filter(headline__startswith='Django')
 255 >>> print q
 256 [<Article: Django lets you build Web apps easily>]
 257 >>> q.delete()
 258
 259 # After the delete, the QuerySet cache needs to be cleared, and the referenced objects should be gone
 260 >>> print q
 261 []
 262 >>> p1.article_set.all()
 263 [<Article: NASA uses Python>]
 264
 265 # An alternate to calling clear() is to assign the empty set
 266 >>> p1.article_set = []
 267 >>> p1.article_set.all()
 268 []
 269
 270 >>> a2.publications = [p1, new_publication]
 271 >>> a2.publications.all()
 272 [<Publication: Highlights for Children>, <Publication: The Python Journal>]
 273 >>> a2.publications = []
 274 >>> a2.publications.all()
 275 []
 276
 277 """}