From ab148c02cedbac492f29930dcd5346e1af052635 Mon Sep 17 00:00:00 2001 From: Simon Charette Date: Sun, 9 Mar 2025 07:04:16 -0400 Subject: Fixed #33579 -- Specialized exception raised on forced update failures. Raising DatabaseError directly made it harder than it should to differentiate between IntegrityError when a forced update resulted in no affected rows. Introducing a specialized exception allows for callers to more easily silence, log, or turn them update failures into user facing exceptions (e.g. 404s). Thanks Mariusz for the review. --- docs/ref/exceptions.txt | 14 ++++++++++++++ docs/ref/models/class.txt | 17 +++++++++++++++++ docs/ref/models/instances.txt | 6 ++++++ 3 files changed, 37 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/exceptions.txt b/docs/ref/exceptions.txt index f9f7c3c498..a105679a9b 100644 --- a/docs/ref/exceptions.txt +++ b/docs/ref/exceptions.txt @@ -33,6 +33,20 @@ Django core exception classes are defined in ``django.core.exceptions``. See :meth:`~django.db.models.query.QuerySet.get()`. +``ObjectNotUpdated`` +-------------------- + +.. versionadded:: 6.0 + +.. exception:: ObjectNotUpdated + + The base class for :exc:`Model.NotUpdated + ` exceptions. A ``try/except`` for + ``ObjectNotUpdated`` will catch + :exc:`~django.db.models.Model.NotUpdated` exceptions for all models. + + See :meth:`~django.db.models.Model.save()`. + ``EmptyResultSet`` ------------------ diff --git a/docs/ref/models/class.txt b/docs/ref/models/class.txt index c0ccb6caff..4890955fe7 100644 --- a/docs/ref/models/class.txt +++ b/docs/ref/models/class.txt @@ -39,6 +39,23 @@ Attributes The exception is a subclass of :exc:`django.core.exceptions.MultipleObjectsReturned`. +``NotUpdated`` +-------------- + +.. versionadded:: 6.0 + +.. exception:: Model.NotUpdated + + This exception is raised when :ref:`a forced update + ` of a :class:`~django.db.models.Model` instance + does not affect any rows. + + Django provides a ``NotUpdated`` exception as an attribute of each model + class to identify the class of object that could not be updated, allowing + you to catch exceptions for a particular model class. The exception is a + subclass of :exc:`django.core.exceptions.ObjectNotUpdated` and inherits + from :exc:`django.db.DatabaseError` for backward compatibility reasons. + ``objects`` ----------- diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index be4ad4a4f4..e15e1c93bf 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -601,6 +601,12 @@ You can pass ``force_insert=(models.Model,)`` to force an ``INSERT`` statement for all parents. By default, ``force_insert=True`` only forces the insertion of a new row for the current model. +.. versionchanged:: 6.0 + + When a forced update does not affect any rows a + :exc:`~django.db.models.Model.NotUpdated` exception is raised. On previous + versions a generic :exc:`django.db.DatabaseError` was raised. + It should be very rare that you'll need to use these parameters. Django will almost always do the right thing and trying to override that will lead to errors that are difficult to track down. This feature is for advanced use -- cgit v1.3