Opened 11 years ago

Closed 11 years ago

#21654 closed Cleanup/optimization (fixed)

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

Reported by: Selwin Ong Owned by: nobody
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: loic@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description (last modified by Simon Charette)

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()?

Change History (14)

comment:1 by Selwin Ong, 11 years ago

Sorry, I meant form.errors.as_dict()

comment:2 by Simon Charette, 11 years ago

Description: modified (diff)
Summary: Better name for Form.as_data()Better name for `Form.errors.as_data()`
Type: UncategorizedCleanup/optimization

comment:3 by loic84, 11 years ago

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.

comment:4 by anonymous, 11 years ago

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 :)

comment:5 by Marc Tamlyn, 11 years ago

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()?

comment:6 by loic84, 11 years ago

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).

comment:7 by loic84, 11 years ago

Cc: loic@… added

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.

Last edited 11 years ago by loic84 (previous) (diff)

comment:8 by Tim Graham, 11 years ago

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

comment:9 by Baptiste Mispelon, 11 years ago

Easy pickings: set
Summary: Better name for `Form.errors.as_data()`Document a use-case for `Form.errors.as_data()`
Triage Stage: UnreviewedAccepted

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.

comment:10 by loic84, 11 years ago

  • 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?".

Last edited 11 years ago by loic84 (previous) (diff)

comment:11 by Tim Graham, 11 years ago

Easy pickings: unset

comment:12 by Tim Graham, 11 years ago

Component: FormsDocumentation

comment:14 by Tim Graham <timograham@…>, 11 years ago

Resolution: fixed
Status: newclosed

In 2e4200b5c7cb4887b7034bb5dcbbd354e4698f27:

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

Thanks selwin for the suggestion.

Note: See TracTickets for help on using tickets.
Back to Top