From 2e4200b5c7cb4887b7034bb5dcbbd354e4698f27 Mon Sep 17 00:00:00 2001 From: Loic Bistuer Date: Fri, 14 Feb 2014 01:19:13 +0700 Subject: [PATCH] Fixed #21654 -- Documented a use-case for Form.errors.as_data(). Thanks selwin for the suggestion. --- docs/ref/forms/api.txt | 14 ++++++++++++++ docs/ref/forms/validation.txt | 7 +++++++ 2 files changed, 21 insertions(+) diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index 7f2de3fa03..5a9f6a1cdc 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -128,6 +128,20 @@ instances. {'sender': [ValidationError(['Enter a valid email address.'])], 'subject': [ValidationError(['This field is required.'])]} +Use this method anytime you need to identify an error by its ``code``. This +enables things like rewriting the error's message or writing custom logic in a +view when a given error is present. It can also be used to serialize the errors +in a custom format (e.g. XML); for instance, :meth:`~Form.errors.as_json()` +relies on ``as_data()``. + +The need for the ``as_data()`` method is due to backwards compatibility. +Previously ``ValidationError`` instances were lost as soon as their +**rendered** error messages were added to the ``Form.errors`` dictionary. +Ideally ``Form.errors`` would have stored ``ValidationError`` instances +and methods with an ``as_`` prefix could render them, but it had to be done +the other way around in order not to break code that expects rendered error +messages in ``Form.errors``. + .. method:: Form.errors.as_json() .. versionadded:: 1.7 diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt index 569e7e77e7..78a022d436 100644 --- a/docs/ref/forms/validation.txt +++ b/docs/ref/forms/validation.txt @@ -179,6 +179,13 @@ to override your error message you can still opt for the less verbose:: ValidationError(_('Invalid value: %s') % value) +.. versionadded:: 1.7 + +The :meth:`Form.errors.as_data() ` and +:meth:`Form.errors.as_json() ` methods +greatly benefit from fully featured ``ValidationError``\s (with a ``code`` name +and a ``params`` dictionary). + Raising multiple errors ~~~~~~~~~~~~~~~~~~~~~~~