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 )
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 , 11 years ago
comment:2 by , 11 years ago
Description: | modified (diff) |
---|---|
Summary: | Better name for Form.as_data() → Better name for `Form.errors.as_data()` |
Type: | Uncategorized → Cleanup/optimization |
comment:3 by , 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 , 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 , 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 , 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 , 11 years ago
Cc: | 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
.
comment:8 by , 11 years ago
Should we perhaps clarify the reasoning with a documentation update so others don't ask the same question?
comment:9 by , 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: | Unreviewed → Accepted |
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 , 11 years ago
as_data()
returns theValidationError
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?".
comment:11 by , 11 years ago
Easy pickings: | unset |
---|
comment:12 by , 11 years ago
Component: | Forms → Documentation |
---|
comment:14 by , 11 years ago
Resolution: | → fixed |
---|---|
Status: | new → closed |
Sorry, I meant
form.errors.as_dict()