Ticket #17605: 17605-2.diff

new file docs/topics/db/examples/many_to_many.txt

@@ +1 @@
+##########################
+Many-to-many relationships
+##########################
+
+To define a many-to-many relationship, use ``ManyToManyField()``.
+
+In this example, an ``Article`` can be published in multiple ``Publication``
+objects, and a ``Publication`` has multiple ``Article`` objects::
+
+    from django.db import models
+
+    class Publication(models.Model):
+        title = models.CharField(max_length=30)
+
+        def __unicode__(self):
+            return self.title
+
+        class Meta:
+            ordering = ('title',)
+
+    class Article(models.Model):
+        headline = models.CharField(max_length=100)
+        publications = models.ManyToManyField(Publication)
+
+        def __unicode__(self):
+            return self.headline
+
+        class Meta:
+            ordering = ('headline',)
+
+What follows are examples of operations that can be performed using the Python
+API facilities::
+
+    >>> # Create a couple of Publications.
+    >>> p1 = Publication(id=None, title='The Python Journal')
+    >>> p1.save()
+    >>> p2 = Publication(id=None, title='Science News')
+    >>> p2.save()
+    >>> p3 = Publication(id=None, title='Science Weekly')
+    >>> p3.save()
+
+    # Create an Article.
+    >>> a1 = Article(id=None, headline='Django lets you build Web apps easily')
+
+    # You can't associate it with a Publication until it's been saved.
+    >>> a1.publications.add(p1)
+    Traceback (most recent call last):
+    ...
+    ValueError: 'Article' instance needs to have a primary key value before a many-to-many relationship can be used.
+
+    # Save it!
+    >>> a1.save()
+
+    # Associate the Article with a Publication.
+    >>> a1.publications.add(p1)
+
+    # Create another Article, and set it to appear in both
+    # Publications.
+    >>> a2 = Article(id=None, headline='NASA uses Python')
+    >>> a2.save()
+    >>> a2.publications.add(p1, p2)
+    >>> a2.publications.add(p3)
+
+    # Adding a second time is OK
+    >>> a2.publications.add(p3)
+
+    # Adding an object of the wrong type raises TypeError
+    >>> a2.publications.add(a1)
+    Traceback (most recent call last):
+    ...
+    TypeError: 'Publication' instance expected
+
+    # Add a Publication directly via publications.add by using
+    # keyword arguments.
+    >>> new_publication = a2.publications.create(title='Highlights for Children')
+
+    # Article objects have access to their related Publication
+    # objects.
+    >>> a1.publications.all()
+    [<Publication: The Python Journal>]
+    >>> a2.publications.all()
+    [<Publication: Highlights for Children>, <Publication: Science News>, <Publication: Science Weekly>, <Publication: The Python Journal>]
+
+    # Publication objects have access to their related Article
+    # objects.
+    >>> p2.article_set.all()
+    [<Article: NASA uses Python>]
+    >>> p1.article_set.all()
+    [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
+    >>> Publication.objects.get(id=4).article_set.all()
+    [<Article: NASA uses Python>]
+
+    # We can perform kwarg queries across m2m relationships
+    >>> Article.objects.filter(publications__id__exact=1)
+    [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
+    >>> Article.objects.filter(publications__pk=1)
+    [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
+    >>> Article.objects.filter(publications=1)
+    [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
+    >>> Article.objects.filter(publications=p1)
+    [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
+
+    >>> Article.objects.filter(publications__title__startswith="Science")
+    [<Article: NASA uses Python>, <Article: NASA uses Python>]
+
+    >>> Article.objects.filter(publications__title__startswith="Science").distinct()
+    [<Article: NASA uses Python>]
+
+    # The count() function respects distinct() as well.
+    >>> Article.objects.filter(publications__title__startswith="Science").count()
+    2
+
+    >>> Article.objects.filter(publications__title__startswith="Science").distinct().count()
+    1
+
+    >>> Article.objects.filter(publications__in=[1,2]).distinct()
+    [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
+    >>> Article.objects.filter(publications__in=[1,p2]).distinct()
+    [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
+    >>> Article.objects.filter(publications__in=[p1,p2]).distinct()
+    [<Article: Django lets you build Web apps easily>, <Article: NASA uses Python>]
+
+    # Reverse m2m queries are supported (i.e., starting at the table
+    # that doesn't have a ManyToManyField).
+    >>> Publication.objects.filter(id__exact=1)
+    [<Publication: The Python Journal>]
+    >>> Publication.objects.filter(pk=1)
+    [<Publication: The Python Journal>]
+
+    >>> Publication.objects.filter(article__headline__startswith="NASA")
+    [<Publication: Highlights for Children>, <Publication: Science News>, <Publication: Science Weekly>, <Publication: The Python Journal>]
+
+    >>> Publication.objects.filter(article__id__exact=1)
+    [<Publication: The Python Journal>]
+    >>> Publication.objects.filter(article__pk=1)
+    [<Publication: The Python Journal>]
+    >>> Publication.objects.filter(article=1)
+    [<Publication: The Python Journal>]
+    >>> Publication.objects.filter(article=a1)
+    [<Publication: The Python Journal>]
+
+    >>> Publication.objects.filter(article__in=[1,2]).distinct()
+    [<Publication: Highlights for Children>, <Publication: Science News>, <Publication: Science Weekly>, <Publication: The Python Journal>]
+    >>> Publication.objects.filter(article__in=[1,a2]).distinct()
+    [<Publication: Highlights for Children>, <Publication: Science News>, <Publication: Science Weekly>, <Publication: The Python Journal>]
+    >>> Publication.objects.filter(article__in=[a1,a2]).distinct()
+    [<Publication: Highlights for Children>, <Publication: Science News>, <Publication: Science Weekly>, <Publication: The Python Journal>]
+
+    # Excluding a related item works as you would expect, too
+    # (although the SQL involved is a little complex).
+    >>> Article.objects.exclude(publications=p2)
+    [<Article: Django lets you build Web apps easily>]
+
+    # If we delete a Publication, its Articles won't be able to
+    # access it.
+    >>> p1.delete()
+    >>> Publication.objects.all()
+    [<Publication: Highlights for Children>, <Publication: Science News>, <Publication: Science Weekly>]
+    >>> a1 = Article.objects.get(pk=1)
+    >>> a1.publications.all()
+    []
+
+    # If we delete an Article, its Publications won't be able to
+    # access it.
+    >>> a2.delete()
+    >>> Article.objects.all()
+    [<Article: Django lets you build Web apps easily>]
+    >>> p2.article_set.all()
+    []
+
+    # Adding via the 'other' end of an m2m
+    >>> a4 = Article(headline='NASA finds intelligent life on Earth')
+    >>> a4.save()
+    >>> p2.article_set.add(a4)
+    >>> p2.article_set.all()
+    [<Article: NASA finds intelligent life on Earth>]
+    >>> a4.publications.all()
+    [<Publication: Science News>]
+
+    # Adding via the other end using keywords
+    >>> new_article = p2.article_set.create(headline='Oxygen-free diet works wonders')
+    >>> p2.article_set.all()
+    [<Article: NASA finds intelligent life on Earth>, <Article: Oxygen-free diet works wonders>]
+    >>> a5 = p2.article_set.all()[1]
+    >>> a5.publications.all()
+    [<Publication: Science News>]
+
+    # Removing publication from an article:
+    >>> a4.publications.remove(p2)
+    >>> p2.article_set.all()
+    [<Article: Oxygen-free diet works wonders>]
+    >>> a4.publications.all()
+    []
+
+    # And from the other end
+    >>> p2.article_set.remove(a5)
+    >>> p2.article_set.all()
+    []
+    >>> a5.publications.all()
+    []
+
+    # Relation sets can be assigned. Assignment clears any existing set members
+    >>> p2.article_set = [a4, a5]
+    >>> p2.article_set.all()
+    [<Article: NASA finds intelligent life on Earth>, <Article: Oxygen-free diet works wonders>]
+    >>> a4.publications.all()
+    [<Publication: Science News>]
+    >>> a4.publications = [p3]
+    >>> p2.article_set.all()
+    [<Article: Oxygen-free diet works wonders>]
+    >>> a4.publications.all()
+    [<Publication: Science Weekly>]
+
+    # Relation sets can be cleared:
+    >>> p2.article_set.clear()
+    >>> p2.article_set.all()
+    []
+    >>> a4.publications.all()
+    [<Publication: Science Weekly>]
+
+    # And you can clear from the other end
+    >>> p2.article_set.add(a4, a5)
+    >>> p2.article_set.all()
+    [<Article: NASA finds intelligent life on Earth>, <Article: Oxygen-free diet works wonders>]
+    >>> a4.publications.all()
+    [<Publication: Science News>, <Publication: Science Weekly>]
+    >>> a4.publications.clear()
+    >>> a4.publications.all()
+    []
+    >>> p2.article_set.all()
+    [<Article: Oxygen-free diet works wonders>]
+
+    # Relation sets can also be set using primary key values
+    >>> p2.article_set = [a4.id, a5.id]
+    >>> p2.article_set.all()
+    [<Article: NASA finds intelligent life on Earth>, <Article: Oxygen-free diet works wonders>]
+    >>> a4.publications.all()
+    [<Publication: Science News>]
+    >>> a4.publications = [p3.id]
+    >>> p2.article_set.all()
+    [<Article: Oxygen-free diet works wonders>]
+    >>> a4.publications.all()
+    [<Publication: Science Weekly>]
+
+    # Recreate the article and Publication we have deleted.
+    >>> p1 = Publication(id=None, title='The Python Journal')
+    >>> p1.save()
+    >>> a2 = Article(id=None, headline='NASA uses Python')
+    >>> a2.save()
+    >>> a2.publications.add(p1, p2, p3)
+
+    # Bulk delete some Publications - references to deleted
+    # publications should go
+    >>> Publication.objects.filter(title__startswith='Science').delete()
+    >>> Publication.objects.all()
+    [<Publication: Highlights for Children>, <Publication: The Python Journal>]
+    >>> Article.objects.all()
+    [<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>]
+    >>> a2.publications.all()
+    [<Publication: The Python Journal>]
+
+    # Bulk delete some articles - references to deleted objects
+    # should go
+    >>> q = Article.objects.filter(headline__startswith='Django')
+    >>> print q
+    [<Article: Django lets you build Web apps easily>]
+    >>> q.delete()
+
+    # After the delete, the QuerySet cache needs to be cleared, and
+    # the referenced objects should be gone
+    >>> print q
+    []
+    >>> p1.article_set.all()
+    [<Article: NASA uses Python>]
+
+    # An alternate to calling clear() is to assign the empty set
+    >>> p1.article_set = []
+    >>> p1.article_set.all()
+    []
+
+    >>> a2.publications = [p1, new_publication]
+    >>> a2.publications.all()
+    [<Publication: Highlights for Children>, <Publication: The Python Journal>]
+    >>> a2.publications = []
+    >>> a2.publications.all()
+    []

new file docs/topics/db/examples/many_to_one.txt

@@ +1 @@
+#########################
+Many-to-one relationships
+#########################
+
+To define a many-to-one relationship, use ``ForeignKey()``.
+
+::
+
+    from django.db import models
+
+    class Reporter(models.Model):
+        first_name = models.CharField(max_length=30)
+        last_name = models.CharField(max_length=30)
+        email = models.EmailField()
+
+        def __unicode__(self):
+            return u"%s %s" % (self.first_name, self.last_name)
+
+    class Article(models.Model):
+        headline = models.CharField(max_length=100)
+        pub_date = models.DateField()
+        reporter = models.ForeignKey(Reporter)
+
+        def __unicode__(self):
+            return self.headline
+
+        class Meta:
+            ordering = ('headline',)
+
+What follows are examples of operations that can be performed using the Python
+API facilities::
+
+    >>> # Create a few Reporters.
+    >>> r = Reporter(first_name='John', last_name='Smith', email='john@example.com')
+    >>> r.save()
+
+    >>> r2 = Reporter(first_name='Paul', last_name='Jones', email='paul@example.com')
+    >>> r2.save()
+
+    # Create an Article.
+    >>> from datetime import datetime
+    >>> a = Article(id=None, headline="This is a test", pub_date=datetime(2005, 7, 27), reporter=r)
+    >>> a.save()
+
+    >>> a.reporter.id
+    1
+
+    >>> a.reporter
+    <Reporter: John Smith>
+
+    # Article objects have access to their related Reporter objects.
+    >>> r = a.reporter
+
+    # These are strings instead of unicode strings because that's what was used
+    # in the creation of this reporter (and we haven't refreshed the data from
+    # the database, which always returns unicode strings).
+    >>> r.first_name, r.last_name
+    ('John', 'Smith')
+
+    # Create an Article via the Reporter object.
+    >>> new_article = r.article_set.create(headline="John's second story", pub_date=datetime(2005, 7, 29))
+    >>> new_article
+    <Article: John's second story>
+    >>> new_article.reporter.id
+    1
+
+    # Create a new article, and add it to the article set.
+    >>> new_article2 = Article(headline="Paul's story", pub_date=datetime(2006, 1, 17))
+    >>> r.article_set.add(new_article2)
+    >>> new_article2.reporter.id
+    1
+    >>> r.article_set.all()
+    [<Article: John's second story>, <Article: Paul's story>, <Article: This is a test>]
+
+    # Add the same article to a different article set - check that it moves.
+    >>> r2.article_set.add(new_article2)
+    >>> new_article2.reporter.id
+    2
+
+    # Adding an object of the wrong type raises TypeError
+    >>> r.article_set.add(r2)
+    Traceback (most recent call last):
+    ...
+    TypeError: 'Article' instance expected
+
+    >>> r.article_set.all()
+    [<Article: John's second story>, <Article: This is a test>]
+    >>> r2.article_set.all()
+    [<Article: Paul's story>]
+
+    # Assign the article to the reporter directly using the descriptor
+    >>> new_article2.reporter = r
+    >>> new_article2.save()
+    >>> new_article2.reporter
+    <Reporter: John Smith>
+    >>> new_article2.reporter.id
+    1
+    >>> r.article_set.all()
+    [<Article: John's second story>, <Article: Paul's story>, <Article: This is a test>]
+    >>> r2.article_set.all()
+    []
+
+    # Set the article back again using set descriptor.
+    >>> r2.article_set = [new_article, new_article2]
+    >>> r.article_set.all()
+    [<Article: This is a test>]
+    >>> r2.article_set.all()
+    [<Article: John's second story>, <Article: Paul's story>]
+
+    # Funny case - assignment notation can only go so far; because the
+    # ForeignKey cannot be null, existing members of the set must remain
+    >>> r.article_set = [new_article]
+    >>> r.article_set.all()
+    [<Article: John's second story>, <Article: This is a test>]
+    >>> r2.article_set.all()
+    [<Article: Paul's story>]
+
+    # Reporter cannot be null - there should not be a clear or remove method
+    >>> hasattr(r2.article_set, 'remove')
+    False
+    >>> hasattr(r2.article_set, 'clear')
+    False
+
+    # Reporter objects have access to their related Article objects.
+    >>> r.article_set.all()
+    [<Article: John's second story>, <Article: This is a test>]
+
+    >>> r.article_set.filter(headline__startswith='This')
+    [<Article: This is a test>]
+
+    >>> r.article_set.count()
+    2
+
+    >>> r2.article_set.count()
+    1
+
+    # Get articles by id
+    >>> Article.objects.filter(id__exact=1)
+    [<Article: This is a test>]
+    >>> Article.objects.filter(pk=1)
+    [<Article: This is a test>]
+
+    # Query on an article property
+    >>> Article.objects.filter(headline__startswith='This')
+    [<Article: This is a test>]
+
+    # The API automatically follows relationships as far as you need.
+    # Use double underscores to separate relationships.
+    # This works as many levels deep as you want. There's no limit.
+    # Find all Articles for any Reporter whose first name is "John".
+    >>> Article.objects.filter(reporter__first_name__exact='John')
+    [<Article: John's second story>, <Article: This is a test>]
+
+    # Check that implied __exact also works
+    >>> Article.objects.filter(reporter__first_name='John')
+    [<Article: John's second story>, <Article: This is a test>]
+
+    # Query twice over the related field.
+    >>> Article.objects.filter(reporter__first_name__exact='John', reporter__last_name__exact='Smith')
+    [<Article: John's second story>, <Article: This is a test>]
+
+    # The underlying query only makes one join when a related table is
+    # referenced twice.
+    >>> queryset = Article.objects.filter(reporter__first_name__exact='John', reporter__last_name__exact='Smith')
+    >>> sql = queryset.query.get_compiler(queryset.db).as_sql()[0]
+    >>> sql.count('INNER JOIN')
+    1
+
+    # The automatically joined table has a predictable name.
+    >>> Article.objects.filter(reporter__first_name__exact='John').extra(where=["many_to_one_reporter.last_name='Smith'"])
+    [<Article: John's second story>, <Article: This is a test>]
+
+    # And should work fine with the unicode that comes out of
+    # forms.Form.cleaned_data
+    >>> Article.objects.filter(reporter__first_name__exact='John').extra(where=["many_to_one_reporter.last_name='%s'" % u'Smith'])
+    [<Article: John's second story>, <Article: This is a test>]
+
+    # Find all Articles for the Reporter whose ID is 1.
+    # Use direct ID check, pk check, and object comparison
+    >>> Article.objects.filter(reporter__id__exact=1)
+    [<Article: John's second story>, <Article: This is a test>]
+    >>> Article.objects.filter(reporter__pk=1)
+    [<Article: John's second story>, <Article: This is a test>]
+    >>> Article.objects.filter(reporter=1)
+    [<Article: John's second story>, <Article: This is a test>]
+    >>> Article.objects.filter(reporter=r)
+    [<Article: John's second story>, <Article: This is a test>]
+
+    >>> Article.objects.filter(reporter__in=[1,2]).distinct()
+    [<Article: John's second story>, <Article: Paul's story>, <Article: This is a test>]
+    >>> Article.objects.filter(reporter__in=[r,r2]).distinct()
+    [<Article: John's second story>, <Article: Paul's story>, <Article: This is a test>]
+
+    # You can also use a queryset instead of a literal list of instances.
+    # The queryset must be reduced to a list of values using values(),
+    # then converted into a query
+    >>> Article.objects.filter(reporter__in=Reporter.objects.filter(first_name='John').values('pk').query).distinct()
+    [<Article: John's second story>, <Article: This is a test>]
+
+    # You need two underscores between "reporter" and "id" -- not one.
+    >>> Article.objects.filter(reporter_id__exact=1)
+    Traceback (most recent call last):
+        ...
+    FieldError: Cannot resolve keyword 'reporter_id' into field. Choices are: headline, id, pub_date, reporter
+
+    # You need to specify a comparison clause
+    >>> Article.objects.filter(reporter_id=1)
+    Traceback (most recent call last):
+        ...
+    FieldError: Cannot resolve keyword 'reporter_id' into field. Choices are: headline, id, pub_date, reporter
+
+    # You can also instantiate an Article by passing
+    # the Reporter's ID instead of a Reporter object.
+    >>> a3 = Article(id=None, headline="This is a test", pub_date=datetime(2005, 7, 27), reporter_id=r.id)
+    >>> a3.save()
+    >>> a3.reporter.id
+    1
+    >>> a3.reporter
+    <Reporter: John Smith>
+
+    # Similarly, the reporter ID can be a string.
+    >>> a4 = Article(id=None, headline="This is a test", pub_date=datetime(2005, 7, 27), reporter_id="1")
+    >>> a4.save()
+    >>> a4.reporter
+    <Reporter: John Smith>
+
+    # Reporters can be queried
+    >>> Reporter.objects.filter(id__exact=1)
+    [<Reporter: John Smith>]
+    >>> Reporter.objects.filter(pk=1)
+    [<Reporter: John Smith>]
+    >>> Reporter.objects.filter(first_name__startswith='John')
+    [<Reporter: John Smith>]
+
+    # Reporters can query in opposite direction of ForeignKey definition
+    >>> Reporter.objects.filter(article__id__exact=1)
+    [<Reporter: John Smith>]
+    >>> Reporter.objects.filter(article__pk=1)
+    [<Reporter: John Smith>]
+    >>> Reporter.objects.filter(article=1)
+    [<Reporter: John Smith>]
+    >>> Reporter.objects.filter(article=a)
+    [<Reporter: John Smith>]
+
+    >>> Reporter.objects.filter(article__in=[1,4]).distinct()
+    [<Reporter: John Smith>]
+    >>> Reporter.objects.filter(article__in=[1,a3]).distinct()
+    [<Reporter: John Smith>]
+    >>> Reporter.objects.filter(article__in=[a,a3]).distinct()
+    [<Reporter: John Smith>]
+
+    >>> Reporter.objects.filter(article__headline__startswith='This')
+    [<Reporter: John Smith>, <Reporter: John Smith>, <Reporter: John Smith>]
+    >>> Reporter.objects.filter(article__headline__startswith='This').distinct()
+    [<Reporter: John Smith>]
+
+    # Counting in the opposite direction works in conjunction with distinct()
+    >>> Reporter.objects.filter(article__headline__startswith='This').count()
+    3
+    >>> Reporter.objects.filter(article__headline__startswith='This').distinct().count()
+    1
+
+    # Queries can go round in circles.
+    >>> Reporter.objects.filter(article__reporter__first_name__startswith='John')
+    [<Reporter: John Smith>, <Reporter: John Smith>, <Reporter: John Smith>, <Reporter: John Smith>]
+    >>> Reporter.objects.filter(article__reporter__first_name__startswith='John').distinct()
+    [<Reporter: John Smith>]
+    >>> Reporter.objects.filter(article__reporter__exact=r).distinct()
+    [<Reporter: John Smith>]
+
+    # Regression for #12876 -- Model methods that include queries that
+    # recursive don't cause recursion depth problems under deepcopy.
+    >>> r.cached_query = Article.objects.filter(reporter=r)
+    >>> from copy import deepcopy
+    >>> deepcopy(r)
+    <Reporter: John Smith>
+
+    # Check that implied __exact also works.
+    >>> Reporter.objects.filter(article__reporter=r).distinct()
+    [<Reporter: John Smith>]
+
+    # It's possible to use values() calls across many-to-one relations. (Note,
+    # too, that we clear the ordering here so as not to drag the 'headline'
+    # field into the columns being used to determine uniqueness.)
+    >>> d = {'reporter__first_name': u'John', 'reporter__last_name': u'Smith'}
+    >>> list(Article.objects.filter(reporter=r).distinct().order_by().values('reporter__first_name', 'reporter__last_name')) == [d]
+    True
+
+    # If you delete a reporter, his articles will be deleted.
+    >>> Article.objects.all()
+    [<Article: John's second story>, <Article: Paul's story>, <Article: This is a test>, <Article: This is a test>, <Article: This is a test>]
+    >>> Reporter.objects.order_by('first_name')
+    [<Reporter: John Smith>, <Reporter: Paul Jones>]
+    >>> r2.delete()
+    >>> Article.objects.all()
+    [<Article: John's second story>, <Article: This is a test>, <Article: This is a test>, <Article: This is a test>]
+    >>> Reporter.objects.order_by('first_name')
+    [<Reporter: John Smith>]
+
+    # You can delete using a JOIN in the query.
+    >>> Reporter.objects.filter(article__headline__startswith='This').delete()
+    >>> Reporter.objects.all()
+    []
+    >>> Article.objects.all()
+    []
+
+    # Check that Article.objects.select_related().dates() works properly when
+    # there are multiple Articles with the same date but different foreign-key
+    # objects (Reporters).
+    >>> r1 = Reporter.objects.create(first_name='Mike', last_name='Royko', email='royko@suntimes.com')
+    >>> r2 = Reporter.objects.create(first_name='John', last_name='Kass', email='jkass@tribune.com')
+    >>> a1 = Article.objects.create(headline='First', pub_date=datetime(1980, 4, 23), reporter=r1)
+    >>> a2 = Article.objects.create(headline='Second', pub_date=datetime(1980, 4, 23), reporter=r2)
+    >>> Article.objects.select_related().dates('pub_date', 'day')
+    [datetime.datetime(1980, 4, 23, 0, 0)]
+    >>> Article.objects.select_related().dates('pub_date', 'month')
+    [datetime.datetime(1980, 4, 1, 0, 0)]
+    >>> Article.objects.select_related().dates('pub_date', 'year')
+    [datetime.datetime(1980, 1, 1, 0, 0)]

new file docs/topics/db/examples/one_to_one.txt

@@ +1 @@
+############################
+10. One-to-one relationships
+############################
+
+To define a one-to-one relationship, use ``OneToOneField()``.
+
+In this example, a ``Place`` optionally can be a ``Restaurant``::
+
+    from django.db import models, transaction, IntegrityError
+
+    class Place(models.Model):
+        name = models.CharField(max_length=50)
+        address = models.CharField(max_length=80)
+
+        def __unicode__(self):
+            return u"%s the place" % self.name
+
+    class Restaurant(models.Model):
+        place = models.OneToOneField(Place, primary_key=True)
+        serves_hot_dogs = models.BooleanField()
+        serves_pizza = models.BooleanField()
+
+        def __unicode__(self):
+            return u"%s the restaurant" % self.place.name
+
+    class Waiter(models.Model):
+        restaurant = models.ForeignKey(Restaurant)
+        name = models.CharField(max_length=50)
+
+        def __unicode__(self):
+            return u"%s the waiter at %s" % (self.name, self.restaurant)
+
+    class ManualPrimaryKey(models.Model):
+        primary_key = models.CharField(max_length=10, primary_key=True)
+        name = models.CharField(max_length = 50)
+
+    class RelatedModel(models.Model):
+        link = models.OneToOneField(ManualPrimaryKey)
+        name = models.CharField(max_length = 50)
+
+    class MultiModel(models.Model):
+        link1 = models.OneToOneField(Place)
+        link2 = models.OneToOneField(ManualPrimaryKey)
+        name = models.CharField(max_length=50)
+
+        def __unicode__(self):
+            return u"Multimodel %s" % self.name
+
+What follows are examples of operations that can be performed using the Python
+API facilities::
+
+::
+
+    >>> # Create a couple of Places.
+    >>> p1 = Place(name='Demon Dogs', address='944 W. Fullerton')
+    >>> p1.save()
+    >>> p2 = Place(name='Ace Hardware', address='1013 N. Ashland')
+    >>> p2.save()
+
+    # Create a Restaurant. Pass the ID of the "parent" object as this object's ID.
+    >>> r = Restaurant(place=p1, serves_hot_dogs=True, serves_pizza=False)
+    >>> r.save()
+
+    # A Restaurant can access its place.
+    >>> r.place
+    <Place: Demon Dogs the place>
+
+    # A Place can access its restaurant, if available.
+    >>> p1.restaurant
+    <Restaurant: Demon Dogs the restaurant>
+
+    # p2 doesn't have an associated restaurant.
+    >>> p2.restaurant
+    Traceback (most recent call last):
+        ...
+    DoesNotExist: Restaurant matching query does not exist.
+
+    # Set the place using assignment notation. Because place is the primary key on
+    # Restaurant, the save will create a new restaurant
+    >>> r.place = p2
+    >>> r.save()
+    >>> p2.restaurant
+    <Restaurant: Ace Hardware the restaurant>
+    >>> r.place
+    <Place: Ace Hardware the place>
+    >>> p2.id
+    2
+
+    # Set the place back again, using assignment in the reverse direction.
+    >>> p1.restaurant = r
+    >>> p1.restaurant
+    <Restaurant: Demon Dogs the restaurant>
+
+    >>> r = Restaurant.objects.get(pk=1)
+    >>> r.place
+    <Place: Demon Dogs the place>
+
+    # Restaurant.objects.all() just returns the Restaurants, not the Places.
+    # Note that there are two restaurants - Ace Hardware the Restaurant was created
+    # in the call to r.place = p2.
+    >>> Restaurant.objects.all()
+    [<Restaurant: Demon Dogs the restaurant>, <Restaurant: Ace Hardware the restaurant>]
+
+    # Place.objects.all() returns all Places, regardless of whether they have
+    # Restaurants.
+    >>> Place.objects.order_by('name')
+    [<Place: Ace Hardware the place>, <Place: Demon Dogs the place>]
+
+    >>> Restaurant.objects.get(place__id__exact=1)
+    <Restaurant: Demon Dogs the restaurant>
+    >>> Restaurant.objects.get(pk=1)
+    <Restaurant: Demon Dogs the restaurant>
+    >>> Restaurant.objects.get(place__exact=1)
+    <Restaurant: Demon Dogs the restaurant>
+    >>> Restaurant.objects.get(place__exact=p1)
+    <Restaurant: Demon Dogs the restaurant>
+    >>> Restaurant.objects.get(place=1)
+    <Restaurant: Demon Dogs the restaurant>
+    >>> Restaurant.objects.get(place=p1)
+    <Restaurant: Demon Dogs the restaurant>
+    >>> Restaurant.objects.get(place__pk=1)
+    <Restaurant: Demon Dogs the restaurant>
+    >>> Restaurant.objects.get(place__name__startswith="Demon")
+    <Restaurant: Demon Dogs the restaurant>
+
+    >>> Place.objects.get(id__exact=1)
+    <Place: Demon Dogs the place>
+    >>> Place.objects.get(pk=1)
+    <Place: Demon Dogs the place>
+    >>> Place.objects.get(restaurant__place__exact=1)
+    <Place: Demon Dogs the place>
+    >>> Place.objects.get(restaurant__place__exact=p1)
+    <Place: Demon Dogs the place>
+    >>> Place.objects.get(restaurant__pk=1)
+    <Place: Demon Dogs the place>
+    >>> Place.objects.get(restaurant=1)
+    <Place: Demon Dogs the place>
+    >>> Place.objects.get(restaurant=r)
+    <Place: Demon Dogs the place>
+    >>> Place.objects.get(restaurant__exact=1)
+    <Place: Demon Dogs the place>
+    >>> Place.objects.get(restaurant__exact=r)
+    <Place: Demon Dogs the place>
+
+    # Add a Waiter to the Restaurant.
+    >>> w = r.waiter_set.create(name='Joe')
+    >>> w.save()
+    >>> w
+    <Waiter: Joe the waiter at Demon Dogs the restaurant>
+
+    # Query the waiters
+    >>> Waiter.objects.filter(restaurant__place__pk=1)
+    [<Waiter: Joe the waiter at Demon Dogs the restaurant>]
+    >>> Waiter.objects.filter(restaurant__place__exact=1)
+    [<Waiter: Joe the waiter at Demon Dogs the restaurant>]
+    >>> Waiter.objects.filter(restaurant__place__exact=p1)
+    [<Waiter: Joe the waiter at Demon Dogs the restaurant>]
+    >>> Waiter.objects.filter(restaurant__pk=1)
+    [<Waiter: Joe the waiter at Demon Dogs the restaurant>]
+    >>> Waiter.objects.filter(id__exact=1)
+    [<Waiter: Joe the waiter at Demon Dogs the restaurant>]
+    >>> Waiter.objects.filter(pk=1)
+    [<Waiter: Joe the waiter at Demon Dogs the restaurant>]
+    >>> Waiter.objects.filter(restaurant=1)
+    [<Waiter: Joe the waiter at Demon Dogs the restaurant>]
+    >>> Waiter.objects.filter(restaurant=r)
+    [<Waiter: Joe the waiter at Demon Dogs the restaurant>]
+
+    # Delete the restaurant; the waiter should also be removed
+    >>> r = Restaurant.objects.get(pk=1)
+    >>> r.delete()
+
+    # One-to-one fields still work if you create your own primary key
+    >>> o1 = ManualPrimaryKey(primary_key="abc123", name="primary")
+    >>> o1.save()
+    >>> o2 = RelatedModel(link=o1, name="secondary")
+    >>> o2.save()
+
+    # You can have multiple one-to-one fields on a model, too.
+    >>> x1 = MultiModel(link1=p1, link2=o1, name="x1")
+    >>> x1.save()
+    >>> o1.multimodel
+    <MultiModel: Multimodel x1>
+
+    # This will fail because each one-to-one field must be unique (and link2=o1 was
+    # used for x1, above).
+    >>> sid = transaction.savepoint()
+    >>> try:
+    ...     MultiModel(link1=p2, link2=o1, name="x1").save()
+    ... except Exception, e:
+    ...     if isinstance(e, IntegrityError):
+    ...         print "Pass"
+    ...     else:
+    ...         print "Fail with %s" % type(e)
+    Pass
+    >>> transaction.savepoint_rollback(sid)

docs/topics/db/models.txt

@@ -18 +18 @@
 * With all of this, Django gives you an automatically-generated
   database-access API; see :doc:`/topics/db/queries`.
 
-.. seealso::
-
-    A companion to this document is the `official repository of model
-    examples`_. (In the Django source distribution, these examples are in the
-    ``tests/modeltests`` directory.)
-
-    .. _official repository of model examples: http://code.djangoproject.com/browser/django/trunk/tests/modeltests
-
 Quick example
 =============
 
@@ -326 +318 @@
     For details on accessing backwards-related objects, see the
     :ref:`Following relationships backward example <backwards-related-objects>`.
 
-    For sample code, see the `Many-to-one relationship model tests`_.
-
-    .. _Many-to-one relationship model tests: http://code.djangoproject.com/browser/django/trunk/tests/modeltests/many_to_one
+    For sample code, see the :doc:`Many-to-one relationship model tests
+    </topics/db/examples/many_to_one>`.
 
 Many-to-many relationships
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -376 +367 @@
 
 .. seealso::
 
-    See the `Many-to-many relationship model example`_ for a full example.
-
-.. _Many-to-many relationship model example: http://code.djangoproject.com/browser/django/trunk/tests/modeltests/many_to_many/models.py
+    See the :doc:`Many-to-many relationship model example
+    </topics/db/examples/many_to_many>` for a full example.
 
 :class:`~django.db.models.ManyToManyField` fields also accept a number of extra
 arguments which are explained in :ref:`the model field reference
@@ -569 +559 @@
 
 .. seealso::
 
-    See the `One-to-one relationship model example`_ for a full example.
-
-.. _One-to-one relationship model example: http://code.djangoproject.com/browser/django/trunk/tests/modeltests/one_to_one/models.py
+    See the :doc:`One-to-one relationship model example
+    </topics/db/examples/one_to_one>` for a full example.
 
 :class:`~django.db.models.OneToOneField` fields also accept one optional argument
 described in the :ref:`model field reference <ref-onetoone>`.