diff --git a/docs/ref/exceptions.txt b/docs/ref/exceptions.txt index ee2c9b7f10..ae2180ff9f 100644 --- a/docs/ref/exceptions.txt +++ b/docs/ref/exceptions.txt @@ -26,12 +26,12 @@ Django core exception classes are defined in ``django.core.exceptions``. .. exception:: ObjectDoesNotExist - The base class for :exc:`~django.db.models.Model.DoesNotExist` exceptions; - a ``try/except`` for ``ObjectDoesNotExist`` will catch + The base class for :exc:`Model.DoesNotExist + ` exceptions. A ``try/except`` for + ``ObjectDoesNotExist`` will catch :exc:`~django.db.models.Model.DoesNotExist` exceptions for all models. - See :meth:`~django.db.models.query.QuerySet.get()` for further information - on :exc:`ObjectDoesNotExist` and :exc:`~django.db.models.Model.DoesNotExist`. + See :meth:`~django.db.models.query.QuerySet.get()`. ``EmptyResultSet`` ------------------ @@ -56,13 +56,13 @@ Django core exception classes are defined in ``django.core.exceptions``. .. exception:: MultipleObjectsReturned - The :exc:`MultipleObjectsReturned` exception is raised by a query if only - one object is expected, but multiple objects are returned. A base version - of this exception is provided in :mod:`django.core.exceptions`; each model - class contains a subclassed version that can be used to identify the - specific object type that has returned multiple objects. + The base class for :exc:`Model.MultipleObjectsReturned + ` exceptions. A + ``try/except`` for ``MultipleObjectsReturned`` will catch + :exc:`~django.db.models.Model.MultipleObjectsReturned` exceptions for all + models. - See :meth:`~django.db.models.query.QuerySet.get()` for further information. + See :meth:`~django.db.models.query.QuerySet.get()`. ``SuspiciousOperation`` ----------------------- diff --git a/docs/ref/models/class.txt b/docs/ref/models/class.txt index c41052788e..81414973a9 100644 --- a/docs/ref/models/class.txt +++ b/docs/ref/models/class.txt @@ -25,6 +25,20 @@ Attributes to catch exceptions for a particular model class. The exception is a subclass of :exc:`django.core.exceptions.ObjectDoesNotExist`. +``MultipleObjectsReturned`` +--------------------------- + +.. exception:: Model.MultipleObjectsReturned + + This exception is raised by :meth:`.QuerySet.get` when multiple objects are + found for the given lookups. + + Django provides a ``MultipleObjectsReturned`` exception as an attribute of + each model class to identify the class of object for which multiple objects + were found, allowing you to catch exceptions for a particular model class. + The exception is a subclass of + :exc:`django.core.exceptions.MultipleObjectsReturned`. + ``objects`` ----------- diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 4e3cd108b9..fd7e88d168 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -1999,14 +1999,16 @@ your resulting ``User`` model will have the following attributes:: >>> hasattr(user, 'supervisor_of') True -A ``DoesNotExist`` exception is raised when accessing the reverse relationship -if an entry in the related table doesn't exist. For example, if a user doesn't -have a supervisor designated by ``MySpecialUser``:: +A ``RelatedObjectDoesNotExist`` exception is raised when accessing the reverse +relationship if an entry in the related table doesn't exist. This is a subclass +of the target model's :exc:`Model.DoesNotExist +` exception. For example, if a user +doesn't have a supervisor designated by ``MySpecialUser``:: >>> user.supervisor_of Traceback (most recent call last): ... - DoesNotExist: User matching query does not exist. + RelatedObjectDoesNotExist: User has no supervisor_of. .. _onetoone-arguments: diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index bef6938263..1c82f378b9 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -1844,34 +1844,42 @@ they query the database each time they're called. .. method:: get(**kwargs) Returns the object matching the given lookup parameters, which should be in -the format described in `Field lookups`_. +the format described in `Field lookups`_. You should use lookups that are +guaranteed unique, such as the primary key or fields in a unique constraint. +For example:: -``get()`` raises :exc:`~django.core.exceptions.MultipleObjectsReturned` if more -than one object was found. The -:exc:`~django.core.exceptions.MultipleObjectsReturned` exception is an -attribute of the model class. + Entry.objects.get(id=1) + Entry.objects.get(blog=blog, entry_number=1) -``get()`` raises a :exc:`~django.db.models.Model.DoesNotExist` exception if an -object wasn't found for the given parameters. This exception is an attribute -of the model class. Example:: +If you expect a queryset to already return one row, you can use ``get()`` +without any arguments to return the object for that row:: - Entry.objects.get(id='foo') # raises Entry.DoesNotExist + Entry.objects.filter(pk=1).get() -The :exc:`~django.db.models.Model.DoesNotExist` exception inherits from -:exc:`django.core.exceptions.ObjectDoesNotExist`, so you can target multiple -:exc:`~django.db.models.Model.DoesNotExist` exceptions. Example:: +If ``get()`` doesn't find any object, it raises a :exc:`Model.DoesNotExist +` exception:: + + Entry.objects.get(id=-999) # raises Entry.DoesNotExist + +If ``get()`` finds more than one object, it raises a +:exc:`Model.MultipleObjectsReturned +` exception:: + + Entry.objects.get(name='A Duplicated Name') # raises Entry.MultipleObjectsReturned + +Both these exception classes are attributes of the model class, and specific to +that model. If you want to handle such exceptions from several ``get()`` calls +for different models, you can use their generic base classes. For example, you +can use :exc:`django.core.exceptions.ObjectDoesNotExist` to handle +:exc:`~django.db.models.Model.DoesNotExist` exceptions from multiple models:: from django.core.exceptions import ObjectDoesNotExist + try: - e = Entry.objects.get(id=3) - b = Blog.objects.get(id=1) + blog = Blog.objects.get(id=1) + entry = Entry.objects.get(blog=blog, entry_number=1) except ObjectDoesNotExist: - print("Either the entry or blog doesn't exist.") - -If you expect a queryset to return one row, you can use ``get()`` without any -arguments to return the object for that row:: - - entry = Entry.objects.filter(...).exclude(...).get() + print("Either the blog or entry doesn't exist.") ``create()`` ~~~~~~~~~~~~