17.12 Django’s exceptions: django.core.exceptions

Who raises each, and what becomes of it

ValidationError: one error, a list, or a dictionary

ValidationError.__init__ gives the error one of three shapes, chosen by its first argument:

• a single error: a message, a code a program can test, and params for the message, kept as ValidationError.message, ValidationError.code and ValidationError.params, with a list of the error itself as ValidationError.error_list;
• a list: each item made a ValidationError if it is not one, and the single errors of all of them kept in error_list; a dictionary-shaped item gives its errors without their names;
• a dictionary of field names: each value made a ValidationError, and its list kept under the name in ValidationError.error_dict.

Given a ValidationError, it takes that error’s dictionary, its list, or its message, code and params, which win over a code and params passed beside it.

A single or list-shaped error iterates as its messages, each with its params put in by %; a dictionary-shaped one as pairs of a name and its messages. ValidationError.messages is a flat list of strings for any shape; ValidationError.message_dict is the dictionary of them, and raises AttributeError for the other shapes. ValidationError.update_error_dict adds the errors to a dictionary it is given, by name, or under NON_FIELD_ERRORS, "__all__"; Model.full_clean gathers its steps’ errors with it, and BaseForm.add_error files a form’s errors in the same shape (Validation: full_clean, cleaned_data and the errors).

ValidationError.__eq__ compares hashes. ValidationError.__hash__ hashes a single error’s message, code and params; a dictionary-shaped error’s dictionary through make_hashable, which sorts the names and keeps each list’s order; a list-shaped error’s errors sorted by message. So a list’s order does not count, the order within a dictionary’s list does, and one error is not equal to a list of it.

# a run: a ship's errors
small  = ValidationError("Tonnage %(tons)s is too small.", code="min_tonnage", params={"tons": 0})
both   = ValidationError([small, "A ship needs a home port."])
byname = ValidationError({"tonnage": small, "home": ["A ship needs a home port."]})
home   = both.error_list[1]

list(small)                             ['Tonnage 0 is too small.']
both.messages                           ['Tonnage 0 is too small.', 'A ship needs a home port.']
both.update_error_dict({})              {'__all__': [ValidationError(['Tonnage 0 is too small.']), ValidationError(['A ship needs a home port.'])]}
dict(byname)                            {'tonnage': ['Tonnage 0 is too small.'], 'home': ['A ship needs a home port.']}
ValidationError([byname]).messages      ['Tonnage 0 is too small.', 'A ship needs a home port.']
both == ValidationError([home, small])  True
small == ValidationError([small])       False

A model’s exceptions and the template engine

ModelBase makes each model that is not abstract its own Model.DoesNotExist, Model.MultipleObjectsReturned and Model.NotUpdated from ObjectDoesNotExist, MultipleObjectsReturned and ObjectNotUpdated, or from the parent model’s classes; Model.NotUpdated derives from DatabaseError too, for backward compatibility (ModelBase: a class statement becomes a model). An except can name one model’s error or every model’s.

ObjectDoesNotExist.silent_variable_failure is true. When a template variable’s lookup raises an exception with that attribute true, Variable._resolve_lookup gives the engine’s "string_if_invalid", empty by default, in its place; any other exception goes on up (Variables and filters: FilterExpression and Variable).

# a run: Valletta has two ships, Piraeus none
Port.objects.get(name="Rhodes")          raises Port.DoesNotExist: Port matching query does not exist.
  caught by except ObjectDoesNotExist    Port.DoesNotExist
[{{ port.ships.get }}], port Piraeus     '[]'
[{{ port.ships.get }}], port Valletta    raises Ship.MultipleObjectsReturned: get() returned more than one Ship -- it returned 2!

SynchronousOnlyOperation and async_unsafe

The documentation says some of Django relies on thread-safety and does not work under coroutines sharing a thread; async_unsafe marks such code. Its wrapper asks asyncio.get_running_loop whether a loop runs in the calling thread; if one does, and the environment variable "DJANGO_ALLOW_ASYNC_UNSAFE" is empty or unset, it raises SynchronousOnlyOperation, and otherwise calls the function. It asks about the thread, not the caller: a plain function called from a coroutine is refused too, and the same call through sync_to_async, on a thread with no loop, is not. The variable is read at each call.

Given a function, async_unsafe wraps it with a message of its own; given a message, it returns a decorator that raises with that one. BaseDatabaseWrapper marks the methods that open and close a connection, make a cursor, commit, roll back and keep savepoints, so a query run in a coroutine fails (The asynchronous methods of a queryset). A deployment check reports the variable set.

# harbour/office/notices.py
from django.utils.asyncio import async_unsafe


@async_unsafe
def post_notice(text):
    return f"posted: {text}"


@async_unsafe("The notice board is written from a thread.")
def pin_notice(text):
    return f"pinned: {text}"

# a run of the two functions
in a coroutine:
  post_notice("Beagle sails")                  raises SynchronousOnlyOperation: You cannot call this from an async context - use a thread or sync_to_async.
  pin_notice("Beagle sails")                   raises SynchronousOnlyOperation: The notice board is written from a thread.
  the same, DJANGO_ALLOW_ASYNC_UNSAFE set       'pinned: Beagle sails'
  await sync_to_async(pin_notice)("Beagle sails")  'pinned: Beagle sails'