rename prevent_additional_properties to reject_unknown_fields

Author: the-infinity

docs/05-dataclasses.md

@@ -297,28 +297,28 @@ It is also worth noting that you can use the `@validataclass` decorator with opt
 being applied to the class.
 
 
-## Prevent additional properties
+## Reject unknown fields
 
-Per default, validataclass just ignores any additional properties in the input dictionary when validating an object.
-This makes sense for normal APIs, as additional fields are just filtered out, and it makes validataclass more robust to 
-changes in the API. There might be situations where one needs to have a strict validation of additional parameters,
-for example, to match an OpenAPI validation. 
+Per default, validataclass just ignores any unknown fields in the input dictionary when validating an object.
+This makes sense for normal APIs, as additional fields are just filtered out, and it makes validataclass more robust to
+changes in the API. There might be situations where one needs to have a strict validation of additional fields,
+for example, to match an OpenAPI validation.
 
-You can prevent additional properties by setting `prevent_additional_properties` at the `@validataclass` to `True`, 
+You can reject unknown fields by setting `reject_unknown_fields` at the `@validataclass` to `True`,
 like this:
 
 ```python
 from validataclass.dataclasses import validataclass
 from validataclass.validators import DataclassValidator, StringValidator
 
-@validataclass(prevent_additional_properties=True)
+@validataclass(reject_unknown_fields=True)
 class MyModel:
     name: str = StringValidator()
 
 my_validator = DataclassValidator(MyModel)
 
 my_validator.validate({'name': 'test'})  # would work fine
-my_validator.validate({'name': 'test', 'more': 'stuff'})  # would throw an AdditionalPropertiesError
+my_validator.validate({'name': 'test', 'more': 'stuff'})  # would throw an UnknownFieldsError
 ```
 
 

src/validataclass/dataclasses/validataclass.py

@@ -89,7 +89,7 @@ class ExampleDataclass:
 
     def decorator(_cls: type[_T]) -> type[_T]:
         # Pop validataclass-specific options before passing kwargs to @dataclass
-        prevent_additional_properties = kwargs.pop('prevent_additional_properties', False)
+        reject_unknown_fields = kwargs.pop('reject_unknown_fields', False)
 
         # Set kw_only=True as the default to allow required and optional fields in any order
         kwargs.setdefault('kw_only', True)
@@ -101,7 +101,7 @@ def decorator(_cls: type[_T]) -> type[_T]:
         _cls = dataclasses.dataclass(**kwargs)(_cls)
 
         # Store validataclass-specific settings on the class
-        _cls.__prevent_additional_properties__ = prevent_additional_properties  # type: ignore[attr-defined]
+        _cls.__reject_unknown_fields__ = reject_unknown_fields  # type: ignore[attr-defined]
 
         return _cls
 

src/validataclass/exceptions/__init__.py

@@ -10,7 +10,7 @@
     InvalidTypeError,
     RequiredValueError,
 )
-from .dataclass_exceptions import AdditionalPropertiesError, DataclassPostValidationError
+from .dataclass_exceptions import UnknownFieldsError, DataclassPostValidationError
 from .datetime_exceptions import (
     DateTimeRangeError,
     InvalidDateError,
@@ -50,7 +50,7 @@
 from .url_exceptions import InvalidUrlError
 
 __all__ = [
-    'AdditionalPropertiesError',
+    'UnknownFieldsError',
     'DataclassInvalidPreValidateSignatureException',
     'DataclassPostValidationError',
     'DataclassValidatorFieldException',

src/validataclass/exceptions/dataclass_exceptions.py

@@ -9,31 +9,31 @@
 from .base_exceptions import ValidationError
 
 __all__ = [
-    'AdditionalPropertiesError',
+    'UnknownFieldsError',
     'DataclassPostValidationError',
 ]
 
 
-class AdditionalPropertiesError(ValidationError):
+class UnknownFieldsError(ValidationError):
     """
     Validation error raised by `DataclassValidator` when the input dictionary contains keys that do not correspond to
-    any field in the dataclass, and `prevent_additional_properties` is set to `True`.
+    any field in the dataclass, and `reject_unknown_fields` is set to `True`.
 
-    The `additional_properties` attribute contains a sorted list of the extra field names.
+    The `unknown_fields` attribute contains a sorted list of the extra field names.
 
     Example as dictionary:
 
     ```
     {
-        'code': 'additional_properties',
-        'additional_properties': ['unknown1', 'unknown2'],
+        'code': 'unknown_fields',
+        'unknown_fields': ['unknown1', 'unknown2'],
     }
     ```
     """
-    code = 'additional_properties'
+    code = 'unknown_fields'
 
-    def __init__(self, *, additional_properties: list[str], **kwargs: Any):
-        super().__init__(additional_properties=sorted(additional_properties), **kwargs)
+    def __init__(self, *, unknown_fields: list[str], **kwargs: Any):
+        super().__init__(unknown_fields=sorted(unknown_fields), **kwargs)
 
 
 class DataclassPostValidationError(ValidationError):

src/validataclass/validators/dataclass_validator.py

@@ -11,7 +11,7 @@
 
 from validataclass.dataclasses import Default, NoDefault
 from validataclass.exceptions import (
-    AdditionalPropertiesError,
+    UnknownFieldsError,
     DataclassInvalidPreValidateSignatureException,
     DataclassPostValidationError,
     DataclassValidatorFieldException,
@@ -110,8 +110,8 @@ def __post_validate__(self, *, require_optional_field: bool = False):
     # Dataclass type that the validated dictionary will be converted to
     dataclass_cls: type[T_Dataclass]
 
-    # Whether to prevent additional properties in the input dictionary
-    prevent_additional_properties: bool
+    # Whether to reject unknown fields in the input dictionary
+    reject_unknown_fields: bool
 
     # Field default values
     field_defaults: dict[str, Default]
@@ -133,7 +133,7 @@ def __init__(self, dataclass_cls: type[T_Dataclass] | None = None) -> None:
             raise InvalidValidatorOptionException('Parameter "dataclass_cls" must be a dataclass type.')
 
         self.dataclass_cls = dataclass_cls
-        self.prevent_additional_properties = getattr(dataclass_cls, '__prevent_additional_properties__', False)
+        self.reject_unknown_fields = getattr(dataclass_cls, '__reject_unknown_fields__', False)
         self.field_defaults = {}
 
         # Collect field validators and required fields for the DictValidator by examining the dataclass fields
@@ -228,12 +228,12 @@ def _pre_validate(self, input_data: Any, **kwargs: Any) -> dict[str, Any]:
             # Filter input dictionary through __pre_validate__()
             input_data = pre_validate_func(input_data, **context_kwargs)
 
-        # Check for additional properties if not allowed
-        if self.prevent_additional_properties:
+        # Check for unknown fields if not allowed
+        if self.reject_unknown_fields:
             self._ensure_type(input_data, dict)
-            additional = sorted(set(input_data.keys()) - set(self.field_validators.keys()))
-            if additional:
-                raise AdditionalPropertiesError(additional_properties=additional)
+            unknown = sorted(set(input_data.keys()) - set(self.field_validators.keys()))
+            if unknown:
+                raise UnknownFieldsError(unknown_fields=unknown)
 
         # Validate raw dictionary using underlying DictValidator
         validated_dict = super().validate(input_data, **kwargs)

tests/unit/exceptions/dataclass_exceptions_test.py

@@ -5,48 +5,48 @@
 """
 
 from validataclass.exceptions import (
-    AdditionalPropertiesError,
+    UnknownFieldsError,
     DataclassPostValidationError,
     DictRequiredFieldError,
     InvalidTypeError,
     ValidationError,
 )
 
 
-class AdditionalPropertiesErrorTest:
+class UnknownFieldsErrorTest:
     """
-    Tests for the AdditionalPropertiesError exception class.
+    Tests for the UnknownFieldsError exception class.
     """
 
     @staticmethod
-    def test_additional_properties_error_single_property():
-        """ Tests AdditionalPropertiesError with a single additional property. """
-        error = AdditionalPropertiesError(additional_properties=['unknown_field'])
+    def test_unknown_fields_error_single_property():
+        """ Tests UnknownFieldsError with a single additional property. """
+        error = UnknownFieldsError(unknown_fields=['unknown_field'])
 
         assert error.to_dict() == {
-            'code': 'additional_properties',
-            'additional_properties': ['unknown_field'],
+            'code': 'unknown_fields',
+            'unknown_fields': ['unknown_field'],
         }
 
     @staticmethod
-    def test_additional_properties_error_multiple_properties():
-        """ Tests AdditionalPropertiesError with multiple additional properties (sorted). """
-        error = AdditionalPropertiesError(additional_properties=['watermelon', 'apple', 'mango'])
+    def test_unknown_fields_error_multiple_fields():
+        """ Tests UnknownFieldsError with multiple additional fields (sorted). """
+        error = UnknownFieldsError(unknown_fields=['watermelon', 'apple', 'mango'])
 
         assert error.to_dict() == {
-            'code': 'additional_properties',
-            'additional_properties': ['apple', 'mango', 'watermelon'],
+            'code': 'unknown_fields',
+            'unknown_fields': ['apple', 'mango', 'watermelon'],
         }
 
     @staticmethod
-    def test_additional_properties_error_repr():
-        """ Tests repr of AdditionalPropertiesError. """
-        error = AdditionalPropertiesError(additional_properties=['unknown1', 'unknown2'])
+    def test_unknown_fields_error_repr():
+        """ Tests repr of UnknownFieldsError. """
+        error = UnknownFieldsError(unknown_fields=['unknown1', 'unknown2'])
 
         assert (
             repr(error)
-            == "AdditionalPropertiesError(code='additional_properties', "
-               "additional_properties=['unknown1', 'unknown2'])"
+            == "UnknownFieldsError(code='unknown_fields', "
+               "unknown_fields=['unknown1', 'unknown2'])"
         )
         assert str(error) == repr(error)
 

tests/unit/validators/dataclass_validator_test.py

@@ -13,7 +13,7 @@
 from tests.test_utils import UnitTestContextValidator
 from validataclass.dataclasses import Default, DefaultFactory, DefaultUnset, validataclass, validataclass_field
 from validataclass.exceptions import (
-    AdditionalPropertiesError,
+    UnknownFieldsError,
     DataclassInvalidPreValidateSignatureException,
     DataclassPostValidationError,
     DataclassValidatorFieldException,
@@ -59,9 +59,9 @@ class UnitTestNestedDataclass:
         validataclass_field(DataclassValidator(UnitTestDataclass), default=None)
 
 
-# Dataclass with prevent_additional_properties=True
+# Dataclass with reject_unknown_fields=True
 
-@validataclass(prevent_additional_properties=True)
+@validataclass(reject_unknown_fields=True)
 class UnitTestStrictDataclass:
     """
     Dataclass that does not allow additional properties in the input dictionary.
@@ -1144,7 +1144,7 @@ class IncompatibleDataclass:
 
         assert str(exception_info.value) == 'Default specified for dataclass field "foo" is not of type "Default".'
 
-    # Tests for prevent_additional_properties option
+    # Tests for reject_unknown_fields option
 
     @staticmethod
     def test_strict_dataclass_valid():
@@ -1173,26 +1173,26 @@ def test_strict_dataclass_valid_with_optional_field_omitted():
 
     @staticmethod
     def test_strict_dataclass_with_additional_properties():
-        """ Test that a strict dataclass raises AdditionalPropertiesError for unknown keys. """
+        """ Test that a strict dataclass raises UnknownFieldsError for unknown keys. """
         validator = DataclassValidator(UnitTestStrictDataclass)
 
-        with pytest.raises(AdditionalPropertiesError) as exception_info:
+        with pytest.raises(UnknownFieldsError) as exception_info:
             validator.validate({
                 'name': 'banana',
                 'unknown_field': 'unknown_value',
             })
 
         assert exception_info.value.to_dict() == {
-            'code': 'additional_properties',
-            'additional_properties': ['unknown_field'],
+            'code': 'unknown_fields',
+            'unknown_fields': ['unknown_field'],
         }
 
     @staticmethod
-    def test_strict_dataclass_with_multiple_additional_properties():
-        """ Test that additional properties are sorted in the error. """
+    def test_strict_dataclass_with_multiple_additional_fields():
+        """ Test that additional fields are sorted in the error. """
         validator = DataclassValidator(UnitTestStrictDataclass)
 
-        with pytest.raises(AdditionalPropertiesError) as exception_info:
+        with pytest.raises(UnknownFieldsError) as exception_info:
             validator.validate({
                 'name': 'banana',
                 'zebra': 1,
@@ -1201,13 +1201,13 @@ def test_strict_dataclass_with_multiple_additional_properties():
             })
 
         assert exception_info.value.to_dict() == {
-            'code': 'additional_properties',
-            'additional_properties': ['alpha', 'mango', 'zebra'],
+            'code': 'unknown_fields',
+            'unknown_fields': ['alpha', 'mango', 'zebra'],
         }
 
     @staticmethod
-    def test_default_allows_additional_properties():
-        """ Test that by default (prevent_additional_properties=False), unknown keys are silently ignored. """
+    def test_default_allows_additional_fields():
+        """ Test that by default (reject_unknown_fields=False), unknown keys are silently ignored. """
         validator = DataclassValidator(UnitTestDataclass)
         validated_data = validator.validate({
             'name': 'banana',
@@ -1221,10 +1221,10 @@ def test_default_allows_additional_properties():
         assert validated_data.name == 'banana'
 
     @staticmethod
-    def test_explicit_prevent_additional_properties_false():
-        """ Test that prevent_additional_properties=False explicitly allows unknown keys. """
+    def test_explicit_reject_unknown_fields_false():
+        """ Test that reject_unknown_fields=False explicitly allows unknown keys. """
 
-        @validataclass(prevent_additional_properties=False)
+        @validataclass(reject_unknown_fields=False)
         class ExplicitAllowDataclass:
             name: str = StringValidator()