Document a use-case for `Form.errors.as_data()`

[Selwin Ong]

From Django 1.7's release notes:

The dict-like attribute errors now has two new methods as_data() and as_json(). The former returns a dict that maps fields to their original errors, complete with all metadata (error code and params), the latter returns the errors serialized as json.

Is form.errors.as_dict() a better name than form.errors.as_data()?

[Selwin Ong]

Sorry, I meant form.errors.as_dict()

[loic84]

FWIW, I initially called it as_dict(), but form.errors is a dict, so technically that translates to dict.as_dict().

@mjtamlyn pointed out this issue in ​https://github.com/django/django/pull/1406#issuecomment-21705685 and I agreed with his argument.

It's also worth noting that as_data() is a lower level method, if you just want to access the rendered error messages, you should directly use form.errors as a dict.

[anonymous]

Ah ok, I understand your reasoning. If we cast technical implementation aside though, I think users will find form.errors.as_dict() more readable as it perfectly describes what the method does (getting form errors in dictionary format).

No strong opinions on this though :)

[Marc Tamlyn]

The problem with as_dict() is that it is already a dict. I think users are likely to overuse an as_dict() method when what they already have (an ErrorDict) would suffice.

Am I correct in thinking that the return of as_data() consists of just dicts, lists and strings (i.e. no ErrorDict, ErrorList objects)? If so then perhaps we can steal a name from DRF and call it to_native() or as_native()?

[loic84]

No strong opinion on my side either. But I think it's important to stress that form.errors is already just that: "form errors in dictionary format", albeit already rendered (translated and formatted with params).

[loic84]

Somehow missed @mjtamlyn's response. as_data() returns a dict (native) of list (native) of ValidationError. form.errrors on the other hand is a dict (ErrorDict) of list (ErrorList) of string.

[Tim Graham]

Should we perhaps clarify the reasoning with a documentation update so others don't ask the same question?

[Baptiste Mispelon]

I agree with Tim that a documentation update would help clear up the confusion.

Why would a user want to use form.errors.as_data() instead of just form.errors; is there a use-case for it?

I'm accepting the ticket on this basis.

[loic84]

• as_data() returns the ValidationError instances, you need that if you want to do anything meaningful with the errors other than just displaying them.

• form.errors returns the rendered errors which are basically blobs of text. At that point all the metadata is gone, no error code, no params, and the string has already been translated. All you can do is display this text; you can't manipulate it since you can't identify the individual errors anymore, especially if translation is involved.

Ideally form.errors would have always returned ValidationError instances and as_data() wouldn't exist, but that would have been backward incompatible, so we had to do it the other way around.

Use-cases include, serializing the errors (say in xml or a custom json), rewrite or remove a given error message, etc. Basically, anytime you need an answer to the question "what is this error message?".

[loic84]

PR ​https://github.com/django/django/pull/2273.

[Tim Graham <timograham@…>]

In 2e4200b5c7cb4887b7034bb5dcbbd354e4698f27:

Fixed #21654 -- Documented a use-case for Form.errors.as_data().

Thanks selwin for the suggestion.