Merge pull request #98 from binary-butterfly/enum-validator-default-case-insensitive

binaryDiv · web-flow · commit ec99a1d23136 · 2022-11-29T15:34:51.000+01:00
AnyOfValidator/EnumValidator: Set case-sensitive as default (#93)
diff --git a/docs/03-basic-validators.md b/docs/03-basic-validators.md
@@ -856,9 +856,13 @@ These values can potentially be of any type, although strings and integers are p
 The `AnyOfValidator` is defined with a simple list of allowed values and accepts only values that are part of this list.
 The values will be returned as defined in the list.
 
-By default, strings will be matched case-sensitively. To change this, set `case_insensitive=True`. In that case, the
-value will always be returned as it is defined in the list of allowed values (e.g. if the allowed values contain
-"Apple", then "APPLE" and "apple" will be valid input too, but in all cases "Apple" will be returned).
+By default, strings will be matched **case-insensitively**. To change this, set `case_sensitive=True`. The returned
+value will always be as defined in the list of allowed values (e.g. if the allowed values contain "Apple" and the
+validator is case-insensitive, then "APPLE" and "apple" will be valid input too, but in all cases "Apple" will be
+returned).
+
+**NOTE:** Prior to version 0.8.0, the validator was NOT case-insensitive by default. The old parameter `case_insensitive`
+still exists for compatibility, but is deprecated now and will be removed in a future version.
 
 The list of allowed values may contain mixed types (e.g. `['banana', 123, True, None]`). Also the allowed values can be
 specified with any iterable, not just as a list (e.g. as a set or tuple).
@@ -878,18 +882,19 @@ include the list of allowed values (as "allowed_values"), as long as this list i
 ```python
 from validataclass.validators import AnyOfValidator
 
-# Accept a specific list of strings
-validator = AnyOfValidator(['apple', 'banana', 'strawberry'])
-validator.validate('banana')      # will return 'banana'
-validator.validate('strawberry')  # will return 'strawberry'
-validator.validate('pineapple')   # will raise ValueNotAllowedError()
-validator.validate(1)             # will raise InvalidTypeError(expected_type='str')
-
-# Accept strings with case-insensitive matching
-validator = AnyOfValidator(['Apple', 'Banana', 'Strawberry'], case_insensitive=True)
+# Accept a specific list of strings (case-insensitive by default)
+validator = AnyOfValidator(['Apple', 'Banana', 'Strawberry'])
 validator.validate('apple')       # will return 'Apple'
 validator.validate('bAnAnA')      # will return 'Banana'
 validator.validate('STRAWBERRY')  # will return 'Strawberry'
+validator.validate('pineapple')   # will raise ValueNotAllowedError()
+validator.validate(1)             # will raise InvalidTypeError(expected_type='str')
+
+# Accept strings with case-sensitive matching
+validator = AnyOfValidator(['Apple', 'Banana', 'Strawberry'], case_sensitive=True)
+validator.validate('Banana')     # will return 'Banana'
+validator.validate('banana')     # will raise ValueNotAllowedError
+validator.validate('BANANA')     # will raise ValueNotAllowedError
 
 # Accept a list of values of mixed types
 validator = AnyOfValidator(['banana', 123, True, None])
@@ -916,7 +921,10 @@ The `EnumValidator` is an extended `AnyOfValidator` that uses `Enum` classes ins
 
 It accepts the **values** of the Enum and converts the input value to the according enum **member**.
 
-Strings will be matched case-sensitively by default. To change this, set `case_insensitive=True`.
+Strings will be matched **case-insensitively** by default. To change this, set `case_insensitive=True`.
+
+NOTE: Prior to version 0.8.0, the validator was NOT case-insensitive by default. The old parameter "case_insensitive"
+still exists for compatibility, but is deprecated now and will be removed in a future version.
 
 By default all values in the Enum are accepted as input. This can be optionally restricted by specifying the
 `allowed_values` parameter, which will override the list of allowed values. Values in this list that are not valid for
@@ -951,19 +959,19 @@ class ExampleIntegerEnum(Enum):
     BAR = 3
     BAZ = -20
 
-# Default: Accept all values of the ExampleStringEnum
+# Default: Accept all values of the ExampleStringEnum (case-insensitive)
 validator = EnumValidator(ExampleStringEnum)
 validator.validate('apple')       # will return ExampleStringEnum.APPLE
-validator.validate('banana')      # will return ExampleStringEnum.BANANA
-validator.validate('strawberry')  # will return ExampleStringEnum.STRAWBERRY
+validator.validate('BANANA')      # will return ExampleStringEnum.BANANA
+validator.validate('Strawberry')  # will return ExampleStringEnum.STRAWBERRY
 validator.validate('pineapple')   # will raise ValueNotAllowedError
 validator.validate(123)           # will raise InvalidTypeError(expected_type='str')
 
-# Accept all values of the ExampleStringEnum with case-insensitive string matching
-validator = EnumValidator(ExampleStringEnum, case_insensitive=True)
-validator.validate('Apple')       # will return ExampleStringEnum.APPLE
-validator.validate('bAnAnA')      # will return ExampleStringEnum.BANANA
-validator.validate('STRAWBERRY')  # will return ExampleStringEnum.STRAWBERRY
+# Accept all values of the ExampleStringEnum, but with case-sensitive matching
+validator = EnumValidator(ExampleStringEnum, case_sensitive=True)
+validator.validate('apple')       # will return ExampleStringEnum.APPLE
+validator.validate('Apple')       # will raise ValueNotAllowedError
+validator.validate('APPLE')       # will raise ValueNotAllowedError
 
 # Default: Accept all values of the ExampleIntegerEnum
 validator = EnumValidator(ExampleIntegerEnum)
diff --git a/src/validataclass/validators/any_of_validator.py b/src/validataclass/validators/any_of_validator.py
@@ -4,6 +4,7 @@
 Use of this source code is governed by an MIT-style license that can be found in the LICENSE file.
 """
 
+import warnings
 from typing import Any, Iterable, List, Optional, Union
 
 from validataclass.exceptions import ValueNotAllowedError, InvalidValidatorOptionException
@@ -24,9 +25,13 @@ class AnyOfValidator(Validator):
     The types allowed for input data will be automatically determined from the list of allowed values by default, unless
     explicitly specified with the parameter 'allowed_types'.
 
-    By default, strings will be matched case-sensitively. To change this, set `case_insensitive=True`. In that case,
-    the value will always be returned as it is defined in the list of allowed values (e.g. if the allowed values contain
-    "Apple", then "APPLE" and "apple" will be valid input too, but in all cases "Apple" will be returned).
+    By default, strings will be matched *case-insensitively*. To change this, set `case_sensitive=True`. The returned
+    value will always be as defined in the list of allowed values (e.g. if the allowed values contain "Apple" and the
+    validator is case-insensitive, then "APPLE" and "apple" will be valid input too, but in all cases "Apple" will be
+    returned).
+
+    NOTE: Prior to version 0.8.0, the validator was NOT case-insensitive by default. The old parameter "case_insensitive"
+    still exists for compatibility, but is deprecated now and will be removed in a future version.
 
     If the input value is not valid (but has the correct type), a ValueNotAllowedError (code='value_not_allowed') will
     be raised. This error will include the list of allowed values (as "allowed_values"), as long as this list is not
@@ -36,11 +41,11 @@ class AnyOfValidator(Validator):
     Examples:
 
     ```
-    # Accepts "apple", "banana", "strawberry" (but not "APPLE" or "Banana")
+    # Accepts "apple", "banana", "strawberry" in any capitalization (e.g. "APPLE" is accepted, but returns "apple")
     AnyOfValidator(['apple', 'banana', 'strawberry'])
 
-    # Accepts the same values, but case-insensitively. Always returns the defined string (e.g. "apple" -> "Apple").
-    AnyOfValidator(['Apple', 'Banana', 'Strawberry'], case_insensitive=True)
+    # Accepts the same values, but case-sensitively (e.g. "APPLE" is not accepted, only "apple" is)
+    AnyOfValidator(['Apple', 'Banana', 'Strawberry'], case_sensitive=True)
     ```
 
     See also: `EnumValidator` (same principle but using Enum classes instead of raw value lists)
@@ -58,23 +63,25 @@ class AnyOfValidator(Validator):
     # Types allowed for input data (set by parameter or autodetermined from allowed_values)
     allowed_types: List[type] = None
 
-    # Check strings case-insensitively
-    case_insensitive: bool = False
+    # If set, strings will be matched case-sensitively
+    case_sensitive: bool = False
 
     def __init__(
         self,
         allowed_values: Iterable[Any],
         *,
         allowed_types: Optional[Union[type, Iterable[type]]] = None,
-        case_insensitive: bool = False,
+        case_sensitive: Optional[bool] = None,
+        case_insensitive: Optional[bool] = None,
     ):
         """
         Create an AnyOfValidator with a specified list of allowed values.
 
         Parameters:
             allowed_values: List (or any other iterable) of values that are allowed as input (required)
             allowed_types: Types that are allowed for input data (default: None, autodetermine types from allowed_values)
-            case_insensitive: If set, strings will be matched case-insensitively (default: False)
+            case_sensitive: If set, strings will be matched case-sensitively (default: True)
+            case_insensitive: DEPRECATED. Validator is case-insensitive by default, use case_sensitive to change this.
         """
         # Save list of allowed values
         self.allowed_values = list(allowed_values)
@@ -91,7 +98,24 @@ def __init__(
         if len(self.allowed_types) == 0:
             raise InvalidValidatorOptionException('Parameter "allowed_types" is an empty list (or types could not be autodetermined).')
 
-        self.case_insensitive = case_insensitive
+        # Changed in 0.8.0: The old "case_insensitive" parameter is now deprecated and replaced by a new parameter
+        # "case_sensitive", which is True by default.
+        # TODO: For version 1.0, remove the old parameter completely and set a real default value for the new parameter.
+        if case_sensitive is not None and case_insensitive is not None:
+            raise InvalidValidatorOptionException(
+                'Parameters "case_sensitive" and "case_insensitive" (now deprecated) are mutually exclusive.'
+            )
+        elif case_insensitive is not None:
+            warnings.warn(
+                'The parameter "case_insensitive" is deprecated since version 0.8.0 and will be removed in the future. '
+                'The AnyOfValidator and EnumValidator are now case-insensitive by default. To change this, set the new '
+                'parameter "case_sensitive=False" instead.',
+                DeprecationWarning
+            )
+            case_sensitive = not case_insensitive
+
+        # Set case_sensitive parameter, defaulting to True.
+        self.case_sensitive = case_sensitive if case_sensitive is not None else True
 
     def validate(self, input_data: Any, **kwargs) -> Any:
         """
@@ -124,8 +148,8 @@ def _compare_values(self, input_value: Any, allowed_value: Any) -> bool:
         if type(input_value) is not type(allowed_value):
             return False
 
-        # Compare strings case-insensitively (if option is set)
-        if type(input_value) is str and self.case_insensitive:
+        # Compare strings case-insensitively (unless case_sensitive option is set)
+        if type(input_value) is str and not self.case_sensitive:
             return input_value.lower() == allowed_value.lower()
         else:
             return input_value == allowed_value
diff --git a/src/validataclass/validators/enum_validator.py b/src/validataclass/validators/enum_validator.py
@@ -15,7 +15,7 @@
     'T_Enum',
 ]
 
-# Type variable for type hints in DataclassValidator
+# Type variable for type hints in EnumValidator
 T_Enum = TypeVar('T_Enum', bound=Enum)
 
 
@@ -36,7 +36,10 @@ class EnumValidator(Generic[T_Enum], AnyOfValidator):
     The types allowed for input data will be automatically determined from the allowed Enum values by default, unless
     explicitly specified with the parameter `allowed_types`.
 
-    By default, strings will be matched case-sensitively. To change this, set `case_insensitive=True`.
+    By default, strings will be matched *case-insensitively*. To change this, set `case_sensitive=True`.
+
+    NOTE: Prior to version 0.8.0, the validator was NOT case-insensitive by default. The old parameter "case_insensitive"
+    still exists for compatibility, but is deprecated now and will be removed in a future version.
 
     If the input value is not valid (but has the correct type), a ValueNotAllowedError (code='value_not_allowed') will
     be raised. This error will include the list of allowed values (as "allowed_values"), as long as this list is not
@@ -67,13 +70,16 @@ class EnumValidator(Generic[T_Enum], AnyOfValidator):
     # Enum class used to determine the list of allowed values
     enum_cls: Type[Enum]
 
+    # TODO: For version 1.0, remove the old parameter "case_insensitive" completely and set a real default value for the
+    #  new "case_sensitive" parameter. (See base AnyOfValidator.)
     def __init__(
         self,
         enum_cls: Type[Enum],
         *,
         allowed_values: Optional[Iterable[Any]] = None,
         allowed_types: Optional[Union[type, Iterable[type]]] = None,
-        case_insensitive: bool = False,
+        case_sensitive: Optional[bool] = None,
+        case_insensitive: Optional[bool] = None,
     ):
         """
         Create a EnumValidator for a specified Enum class, optionally with a restricted list of allowed values.
@@ -82,7 +88,8 @@ def __init__(
             enum_cls: Enum class to use for validation (required)
             allowed_values: List (or iterable) of values from the Enum that are accepted (default: None, all Enum values allowed)
             allowed_types: List (or iterable) of types allowed for input data (default: None, autodetermine types from enum values)
-            case_insensitive: If set, strings will be matched case-insensitively (default: False)
+            case_sensitive: If set, strings will be matched case-sensitively (default: True)
+            case_insensitive: DEPRECATED. Validator is case-insensitive by default, use case_sensitive to change this.
         """
         # Ensure parameter is an Enum class
         if not isinstance(enum_cls, EnumMeta):
@@ -105,6 +112,7 @@ def __init__(
         super().__init__(
             allowed_values=any_of_values,
             allowed_types=allowed_types,
+            case_sensitive=case_sensitive,
             case_insensitive=case_insensitive,
         )
 
diff --git a/tests/validators/any_of_validator_test.py b/tests/validators/any_of_validator_test.py
@@ -194,53 +194,84 @@ def test_empty_allowed_values_with_allowed_types():
             'allowed_values': [],
         }
 
-    # Test AnyOfValidator with case-insensitive option
+    # Test AnyOfValidator with case-sensitive option
 
     @staticmethod
     @pytest.mark.parametrize(
-        'case_insensitive, input_data, expected_result',
+        'case_sensitive, input_data, expected_result',
         [
             # Case-sensitive matching
-            (False, 'Strawberry', 'Strawberry'),
-            (False, 42, 42),
-
-            # Case-insensitive matching
             (True, 'Strawberry', 'Strawberry'),
-            (True, 'STRAWBERRY', 'Strawberry'),
-            (True, 'strawberry', 'Strawberry'),
             (True, 42, 42),
+
+            # Case-insensitive matching (default)
+            (False, 'Strawberry', 'Strawberry'),
+            (False, 'STRAWBERRY', 'Strawberry'),
+            (False, 'strawberry', 'Strawberry'),
+            (False, 42, 42),
         ]
     )
-    def test_case_insensitive_valid(case_insensitive, input_data, expected_result):
+    def test_case_sensitive_valid(case_sensitive, input_data, expected_result):
         """ Test AnyOfValidator with case-sensitive and case-insensitive string matching, valid input. """
-        validator = AnyOfValidator(allowed_values=['Strawberry', 42], case_insensitive=case_insensitive)
+        validator = AnyOfValidator(allowed_values=['Strawberry', 42], case_sensitive=case_sensitive)
         assert validator.validate(input_data) == expected_result
 
     @staticmethod
     @pytest.mark.parametrize(
-        'case_insensitive, input_data',
+        'case_sensitive, input_data',
         [
             # Case-sensitive matching
-            (False, 'strawberry'),
-            (False, 'banana'),
-            (False, 13),
-
-            # Case-insensitive matching
-            (True, 'straw_berry'),
+            (True, 'strawberry'),
+            (True, 'STRAWBERRY'),
             (True, 'banana'),
             (True, 13),
+
+            # Case-insensitive matching (default)
+            (False, 'straw_berry'),
+            (False, 'banana'),
+            (False, 13),
         ]
     )
-    def test_case_insensitive_invalid(case_insensitive, input_data):
+    def test_case_sensitive_invalid(case_sensitive, input_data):
         """ Test AnyOfValidator with case-sensitive and case-insensitive string matching, invalid input. """
-        validator = AnyOfValidator(allowed_values=['Strawberry', 42], case_insensitive=case_insensitive)
+        validator = AnyOfValidator(allowed_values=['Strawberry', 42], case_sensitive=case_sensitive)
         with pytest.raises(ValueNotAllowedError) as exception_info:
             validator.validate(input_data)
         assert exception_info.value.to_dict() == {
             'code': 'value_not_allowed',
             'allowed_values': ['Strawberry', 42],
         }
 
+    @staticmethod
+    @pytest.mark.parametrize(
+        'case_insensitive, valid_input, invalid_input',
+        [
+            # Case-insensitive matching
+            (True, ['Strawberry', 'strawberry', 'STRAWBERRY'], ['banana']),
+
+            # Case-sensitive matching
+            (False, ['Strawberry'], ['strawberry', 'STRAWBERRY', 'banana']),
+        ]
+    )
+    def test_deprecated_case_insensitive(case_insensitive, valid_input, invalid_input):
+        """ Test AnyOfValidator with deprecated case_insensitive parameter, which should issue a deprecation warning. """
+        with pytest.deprecated_call():
+            # This should issue a DeprecationWarning for the case_insensitive parameter, but continue without problems
+            validator = AnyOfValidator(allowed_values=['Strawberry'], case_insensitive=case_insensitive)
+
+        # Valid input
+        for input_data in valid_input:
+            assert validator.validate(input_data) == 'Strawberry'
+
+        # Invalid input
+        for input_data in invalid_input:
+            with pytest.raises(ValueNotAllowedError) as exception_info:
+                validator.validate(input_data)
+            assert exception_info.value.to_dict() == {
+                'code': 'value_not_allowed',
+                'allowed_values': ['Strawberry'],
+            }
+
     # Tests for validation errors
 
     @staticmethod
@@ -274,3 +305,20 @@ def test_empty_allowed_types():
         with pytest.raises(InvalidValidatorOptionException) as exception_info:
             AnyOfValidator([1, 2, 3], allowed_types=[])
         assert str(exception_info.value) == 'Parameter "allowed_types" is an empty list (or types could not be autodetermined).'
+
+    @staticmethod
+    @pytest.mark.parametrize(
+        'case_sensitive, case_insensitive',
+        [
+            (True, True),
+            (True, False),
+            (False, True),
+            (False, False),
+        ]
+    )
+    def test_case_insensitive_parameter_mutually_exclusive(case_sensitive, case_insensitive):
+        """ Test that the parameters "case_sensitive" and "case_insensitive" (deprecated) cannot be set at the same time. """
+        with pytest.raises(InvalidValidatorOptionException) as exception_info:
+            AnyOfValidator(['banana'], case_sensitive=case_sensitive, case_insensitive=case_insensitive)
+        assert str(exception_info.value) == \
+               'Parameters "case_sensitive" and "case_insensitive" (now deprecated) are mutually exclusive.'
diff --git a/tests/validators/enum_validator_test.py b/tests/validators/enum_validator_test.py
