added method fail into fields. Rename old method fail to fail_field_validation

added method fail into fields. Rename old method fail to fail_field_validation

Author: nxexox

docs/api-guid/fields.md

@@ -333,25 +333,25 @@ class ClassNameField(serializers.Field):
 ### Raising validation errors
 
 Our `ColorField` class above currently does not perform any data validation.
-To indicate invalid data, we should raise a `serializers.ValidationError`, like so:
+To indicate invalid data, we should raise a `serializers.ValidationError` or call `self.fail(detail, status=400)`, like so:
 ```python
 def to_internal_value(self, data):
     if not isinstance(data, six.text_type):
         msg = 'Incorrect type. Expected a string, but got %s'
-        raise ValidationError(msg % type(data).__name__)
+        raise ValidationError(detail=msg % type(data).__name__)
 
     if not re.match(r'^rgb\([0-9]+,[0-9]+,[0-9]+\)$', data):
-        raise ValidationError('Incorrect format. Expected `rgb(#,#,#)`.')
+        raise ValidationError(detail='Incorrect format. Expected `rgb(#,#,#)`.', status=500)
 
     data = data.strip('rgb(').rstrip(')')
     red, green, blue = [int(col) for col in data.split(',')]
 
     if any([col > 255 or col < 0 for col in (red, green, blue)]):
-        raise ValidationError('Value out of range. Must be between 0 and 255.')
+        self.fail(detail='Value out of range. Must be between 0 and 255.')
 
     return Color(red, green, blue)
 ```
-The `.fail()` method is a shortcut for raising `ValidationError` that takes a message string from the `error_messages` dictionary. For example:
+The `.fail_field_validation()` method is a shortcut for raising `ValidationError` that takes a message string from the `error_messages` dictionary. For example:
 ```python
 default_error_messages = {
     'incorrect_type': 'Incorrect type. Expected a string, but got {input_type}',
@@ -361,16 +361,16 @@ default_error_messages = {
 
 def to_internal_value(self, data):
     if not isinstance(data, six.text_type):
-        self.fail('incorrect_type', input_type=type(data).__name__)
+        self.fail_field_validation('incorrect_type', input_type=type(data).__name__)
 
     if not re.match(r'^rgb\([0-9]+,[0-9]+,[0-9]+\)$', data):
-        self.fail('incorrect_format')
+        self.fail_field_validation('incorrect_format')
 
     data = data.strip('rgb(').rstrip(')')
     red, green, blue = [int(col) for col in data.split(',')]
 
     if any([col > 255 or col < 0 for col in (red, green, blue)]):
-        self.fail('out_of_range')
+        self.fail_field_validation('out_of_range')
 
     return Color(red, green, blue)
 ```

docs/release-notes.md

@@ -8,6 +8,14 @@ Medium version numbers (0.x.0) may include API changes, in line with the [deprec
 
 Major version numbers (x.0.0) are reserved for substantial project milestones.
 
+
+### 0.3.11
+
+**Date:** [21th January 2020]
+
+* Renaming method `fail` -> `fail_field_validation`.
+* Added method `fail(detail, status)` for raise `ValidationError`.
+
 ### 0.3.10
 
 **Date:** [17th September 2019]

rest_framework/__init__.py

@@ -8,7 +8,7 @@
          __/ |
         |___/
 """
-VERSION = (0, 3, 10)
+VERSION = (0, 3, 11)
 
 __title__ = 'Python-Rest-Framework'
 __author__ = 'Deys Timofey'

rest_framework/serializers/fields.py

@@ -158,7 +158,20 @@ def get_validators(self):
         """
         return self.default_validators[:]
 
-    def fail(self, key, **kwargs):
+    def fail(self, detail=None, status=400):
+        """
+        We throw a normal error if custom validation error.
+
+        :param Union[str, dict] detail: Detail validation error
+        :param int status: Code for response
+
+        :raise AssertionError: If you have not found the key in the `self.error_messages`.
+        :raise ValidationError: If you find the key in the `self.error_messages`.
+
+        """
+        raise ValidationError(detail=detail, status=status)
+
+    def fail_field_validation(self, key, **kwargs):
         """
         We throw a normal error if something went wrong during data processing.
 
@@ -440,7 +453,7 @@ def run_validation(self, data=None):
         """
         if data == '' or (self.trim_whitespace and six.text_type(data).strip() == ''):
             if not self.allow_blank:
-                self.fail('blank')
+                self.fail_field_validation('blank')
             return ''
         return super(CharField, self).run_validation(data)
 
@@ -458,7 +471,7 @@ def to_internal_value(self, data):
         """
         # We skip numbers as strings, but bool as strings seems to be a developer error.
         if isinstance(data, bool) or not isinstance(data, six.string_types + six.integer_types + (float,)):
-            self.fail('invalid')
+            self.fail_field_validation('invalid')
 
         val = six.text_type(data)
 
@@ -536,12 +549,12 @@ def to_internal_value(self, data):
         """
         # We look, do not want us to score a memory?
         if isinstance(data, six.text_type) and len(data) > self.MAX_STRING_LENGTH:
-            self.fail('max_string_length')
+            self.fail_field_validation('max_string_length')
 
         try:
             data = int(self.re_decimal.sub('', str(data)))
         except (ValueError, TypeError):
-            self.fail('invalid')
+            self.fail_field_validation('invalid')
         return data
 
     def to_representation(self, value):
@@ -612,12 +625,12 @@ def to_internal_value(self, data):
         """
         # We look, do not want us to score a memory?
         if isinstance(data, six.text_type) and len(data) > self.MAX_STRING_LENGTH:
-            self.fail('max_string_length')
+            self.fail_field_validation('max_string_length')
 
         try:
             return float(data)
         except (TypeError, ValueError):
-            self.fail('invalid')
+            self.fail_field_validation('invalid')
 
     def to_representation(self, value):
         """
@@ -676,7 +689,7 @@ def to_internal_value(self, data):
                 return False
         except TypeError:  # If the non-hash type came.
             pass
-        self.fail('invalid', input=data)
+        self.fail_field_validation('invalid', input=data)
 
     def to_representation(self, value):
         """
@@ -744,7 +757,7 @@ def to_internal_value(self, data):
                 return None
         except TypeError:  # If the non-hash type came.
             pass
-        self.fail('invalid', input=data)
+        self.fail_field_validation('invalid', input=data)
 
     def to_representation(self, value):
         """
@@ -874,10 +887,10 @@ def to_internal_value(self, data):
             data = html.parse_html_list(data)
 
         if any((isinstance(data, type('')), isinstance(data, Mapping), not hasattr(data, '__iter__'))):
-            self.fail('not_a_list', input_type=type(data).__name__)
+            self.fail_field_validation('not_a_list', input_type=type(data).__name__)
 
         if not self.allow_empty and len(data) == 0:
-            self.fail('empty')
+            self.fail_field_validation('empty')
 
         return [self.child.run_validation(item) for item in data]
 
@@ -946,7 +959,7 @@ def to_internal_value(self, data):
 
         # Check on the datetime object.
         if isinstance(data, datetime.datetime):
-            self.fail('datetime')
+            self.fail_field_validation('datetime')
 
         # Check on the date object.
         if isinstance(data, datetime.date):
@@ -962,7 +975,7 @@ def to_internal_value(self, data):
             return parsed.date()
 
         # Throw exception.
-        self.fail('invalid', format=data)
+        self.fail_field_validation('invalid', format=data)
 
     def to_representation(self, value):
         """
@@ -1058,7 +1071,7 @@ def to_internal_value(self, data):
             return parsed.time()
 
         # Throw exception.
-        self.fail('invalid', format=data)
+        self.fail_field_validation('invalid', format=data)
 
     def to_representation(self, value):
         """
@@ -1145,7 +1158,7 @@ def to_internal_value(self, data):
         # Check ot the data ot datetime object.
         if isinstance(data, datetime.date):
             if not isinstance(data, datetime.datetime):
-                self.fail('date')
+                self.fail_field_validation('date')
             else:
                 return data
 
@@ -1156,7 +1169,7 @@ def to_internal_value(self, data):
             pass
 
         # Throw error.
-        self.fail('invalid', format=data)
+        self.fail_field_validation('invalid', format=data)
 
     def to_representation(self, value):
         """
@@ -1207,7 +1220,7 @@ def to_internal_value(self, data):
         try:
             return json.loads(data, encoding='utf8')
         except (JSONDecodeError, TypeError, ValueError):
-            self.fail('invalid')
+            self.fail_field_validation('invalid')
 
     def to_representation(self, value):
         """
@@ -1222,7 +1235,7 @@ def to_representation(self, value):
         try:
             return json.dumps(value)
         except (TypeError, ValueError):
-            self.fail('invalid')
+            self.fail_field_validation('invalid')
 
 
 class DictField(JsonField):
@@ -1275,7 +1288,7 @@ def to_internal_value(self, data):
             data = html.parse_html_dict(data)
 
         if not isinstance(data, dict):
-            self.fail('not_a_dict', input_type=type(data).__name__)
+            self.fail_field_validation('not_a_dict', input_type=type(data).__name__)
 
         return {
             six.text_type(key): self.child.run_validation(value)

tests/test_fields.py

@@ -251,34 +251,65 @@ def test_bind(self):
         field.bind('test_label', self)
         self.assert_bind(field, 'test_label', self, 'test_label')
 
-    def test_fail(self):
+    def test_fail_field_validation(self):
         """
-        Testing fail method.
+        Testing fail_field_validation method.
 
         """
         # We test without our errors.
         field = self.field_class(**self.create_params())
         try:
-            field.fail('required')
-            self.fail('`.fail()` must throw as exception `ValidationError`.')
+            field.fail_field_validation('required')
+            self.fail('`.fail_field_validation()` must throw as exception `ValidationError`.')
         except ValidationError:
             pass
         try:
-            field.fail('test')
-            self.fail('`.fail()` must throw as exception `AssertionError`.')
+            field.fail_field_validation('test')
+            self.fail('`.fail_field_validation()` must throw as exception `AssertionError`.')
         except AssertionError:
             pass
 
         # Now add custom error message
         field = self.field_class(**self.create_params(error_messages={'test': '{test}-test'}))
         try:
-            field.fail('test', test='test')
-            self.fail('`.fail()` must throw as exception `ValidationError`.')
+            field.fail_field_validation('test', test='test')
+            self.fail('`.fail_field_validation()` must throw as exception `ValidationError`.')
         except ValidationError as e:
             assert e.detail == 'test-test', 'The error message should be `{}`, reality `{}`.'.format(
                 'test-test', e.detail
             )
 
+    def test_fail(self):
+        """
+        Testing fail method.
+
+        """
+        field = self.field_class(**self.create_params())
+        detail = {'error': 'test'}
+        try:
+            field.fail(detail=detail)
+            self.fail('`.fail()` must throw as exception `ValidationError`.')
+        except ValidationError as e:
+            self.assertEqual(
+                e.detail, detail,
+                'ValidationError.detail not equal source error. '
+                'Should be: `{}`, reality: `{}`.'.format(detail, e.detail)
+            )
+            self.assertEqual(
+                e.status, 400,
+                'ValidationError.status = `{}`. This is not 400.'.format(e.status)
+            )
+        status = 404
+        try:
+            field.fail(detail=detail, status=status)
+            self.fail('`.fail()` must throw as exception `ValidationError`.')
+        except ValidationError as e:
+            self.assertEqual(
+                e.status, status,
+                'ValidationError.status not equal source status. '
+                'Should be: `{}`, reality: `{}`.'.format(status, e.status)
+            )
+
     def test_abstract_methods(self):
         """
         Testing abstract methods.