Ticket #15361: 15361-2.diff

File 15361-2.diff, 4.2 KB (added by mmcnickle, 14 years ago)

Documentation as per discussion. Added tests for MultipleObjectsReturned.

  • docs/ref/models/fields.txt

    diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
    index 38a7a10..527ea1b 100644
    a b characters that aren't allowed in Python variable names -- notably, the  
    162162hyphen -- that's OK. Django quotes column and table names behind the
    163163scenes.
    164164
     165.. _field-db_index:
     166
    165167``db_index``
    166168------------
    167169
    override the default primary-key behavior. For more, see  
    240242``primary_key=True`` implies :attr:`null=False <Field.null>` and :attr:`unique=True <Field.unique>`.
    241243Only one primary key is allowed on an object.
    242244
     245.. _field-unique:
     246
    243247``unique``
    244248----------
    245249
  • docs/topics/db/optimization.txt

    diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt
    index 4c5a389..86d77cb 100644
    a b Write your own :doc:`custom SQL to retrieve data or populate models  
    132132</topics/db/sql>`. Use ``django.db.connection.queries`` to find out what Django
    133133is writing for you and start from there.
    134134
     135Retrieve individual objects using a unique, indexed column
     136==========================================================
     137
     138There are two reasons you want to use :ref:`unique <field-unique>`,
     139:ref:`indexed <field-db_index>`: columns to get individual objects. Firstly,
     140the query will be quicker because of the underlying database index. Also
     141the query can run much slower if multiple objects match the lookup; having a
     142unique constraint on the column guarantees this will never happen.
     143
     144So using the :ref:`example Weblog models <queryset-model-example>`::
     145
     146  >>> entry = Entry.objects.get(id=10)
     147
     148will be quicker than the alternative:
     149
     150  >>> entry = Entry.object.get(headline="News Item Title")
     151
     152because ``id`` is indexed by the database and is guaranteed to be unique.
     153
     154Doing the following is potentially quite slow. It could return a large
     155number of results which then have to be rejected as get() can only return one
     156object:
     157
     158  >>> entry = Entry.objects.get(headline__startswith="News")
     159
     160
    135161Retrieve everything at once if you know you will need it
    136162========================================================
    137163
  • tests/modeltests/basic/tests.py

    diff --git a/tests/modeltests/basic/tests.py b/tests/modeltests/basic/tests.py
    index 966798d..acb5996 100644
    a b  
    11from datetime import datetime
    22
    3 from django.core.exceptions import ObjectDoesNotExist
     3from django.core.exceptions import ObjectDoesNotExist, MultipleObjectsReturned
    44from django.db import models, DEFAULT_DB_ALIAS, connection
    55from django.db.models.fields import FieldDoesNotExist
    66from django.test import TestCase, skipIfDBFeature, skipUnlessDBFeature
    class ModelTest(TestCase):  
    115115        b = Article.objects.get(pk=a.id)
    116116        self.assertEqual(a, b)
    117117
     118        # Create a very similar object
     119        a = Article(
     120            id=None,
     121            headline='Area man programs in Python',
     122            pub_date=datetime(2005, 7, 28),
     123        )
     124        a.save()
     125
     126        self.assertEqual(Article.objects.count(), 2)
     127
     128        # Django raises an Article.MultipleObjectsReturned exception if the
     129        # lookup matches more than one object
     130        self.assertRaisesRegexp(
     131            MultipleObjectsReturned,
     132            "get\(\) returned more than one Article -- it returned 2! Lookup parameters were {'headline__startswith': 'Area'}",
     133            Article.objects.get,
     134            headline__startswith='Area',
     135        )
     136
     137        self.assertRaisesRegexp(
     138            MultipleObjectsReturned,
     139            "get\(\) returned more than one Article -- it returned 2! Lookup parameters were {'pub_date__year': 2005}",
     140            Article.objects.get,
     141            pub_date__year=2005,
     142        )
     143
     144        self.assertRaisesRegexp(
     145            MultipleObjectsReturned,
     146            "get\(\) returned more than one Article -- it returned 2! Lookup parameters were {'pub_date__month': 7, 'pub_date__year': 2005}",
     147            Article.objects.get,
     148            pub_date__year=2005,
     149            pub_date__month=7,
     150        )
     151
    118152    def test_object_creation(self):
    119153        # Create an Article.
    120154        a = Article(
Back to Top