Add first implementation

Author: LeanderCS

docs/source/changelog.rst

@@ -4,6 +4,19 @@ Changelog
 All notable changes to this project will be documented in this file.
 
 
+[0.7.5] - 2025-10-17
+--------------------
+
+Added
+^^^^^
+- **Nested InputFilter Support**: New feature to validate nested dictionary
+  structures using InputFilters. Use the ``input_filter`` parameter in
+  ``field()`` to specify an InputFilter class for nested validation. This
+  enables composition of complex validation structures with multiple levels
+  of nesting. See :doc:`Field Decorator documentation <options/field_decorator>`
+  for more details.
+
+
 [0.7.4] - 2025-10-08
 --------------------
 

docs/source/options/field_decorator.rst

@@ -378,6 +378,106 @@ Computed fields are:
             computed=lambda data: data['subtotal'] + data.get('tax', 0)
         )
 
+input_filter
+~~~~~~~~~~~~
+
+**Type**: ``type``
+**Default**: ``None``
+
+Specify an InputFilter class to use for nested validation. When this parameter is
+provided, the field value must be a dictionary and will be validated against the
+nested InputFilter's rules.
+
+This allows you to compose complex validation structures by nesting InputFilters
+within each other, enabling validation of nested objects and hierarchical data
+structures.
+
+**Key Features:**
+
+- Validates nested dictionary structures
+- Applies all filters and validators from the nested InputFilter
+- Supports multiple levels of nesting
+- Provides clear error messages with field context
+
+.. code-block:: python
+
+    from flask_inputfilter import InputFilter
+    from flask_inputfilter.declarative import field
+    from flask_inputfilter.validators import IsIntegerValidator, IsStringValidator
+
+    class UserInputFilter(InputFilter):
+        id: int = field(required=True, validators=[IsIntegerValidator()])
+        name: str = field(required=True, validators=[IsStringValidator()])
+        email: str = field(required=True, validators=[IsStringValidator()])
+
+    class OrderInputFilter(InputFilter):
+        quantity: int = field(required=True, validators=[IsIntegerValidator()])
+        user: dict = field(required=True, input_filter=UserInputFilter)
+
+**Usage Example:**
+
+.. code-block:: python
+
+    order_filter = OrderInputFilter()
+    order_filter.data = {
+        'quantity': 5,
+        'user': {
+            'id': 123,
+            'name': 'John Doe',
+            'email': '[email protected]'
+        }
+    }
+
+    validated_data = order_filter.validate_data()
+    # validated_data['user'] is now a validated dict
+
+**Multiple Levels of Nesting:**
+
+.. code-block:: python
+
+    class AddressInputFilter(InputFilter):
+        city: str = field(required=True, validators=[IsStringValidator()])
+        zipcode: str = field(required=True, validators=[IsStringValidator()])
+
+    class UserInputFilter(InputFilter):
+        id: int = field(required=True, validators=[IsIntegerValidator()])
+        name: str = field(required=True, validators=[IsStringValidator()])
+        address: dict = field(required=True, input_filter=AddressInputFilter)
+
+    class OrderInputFilter(InputFilter):
+        quantity: int = field(required=True, validators=[IsIntegerValidator()])
+        user: dict = field(required=True, input_filter=UserInputFilter)
+
+    # Now you can validate deeply nested structures
+    order_filter = OrderInputFilter()
+    order_filter.data = {
+        'quantity': 10,
+        'user': {
+            'id': 456,
+            'name': 'Jane Smith',
+            'address': {
+                'city': 'New York',
+                'zipcode': '10001'
+            }
+        }
+    }
+
+**Error Handling:**
+
+If nested validation fails, the error will include context about which field failed:
+
+.. code-block:: python
+
+    # If user.name is missing:
+    # ValidationError: {'user': "Nested validation failed for field 'user': {'name': \"Field 'name' is required.\"}"}
+
+**Important Notes:**
+
+- The field value must be a dictionary, otherwise a validation error is raised
+- If the field is optional (``required=False``) and the value is ``None``, nested validation is skipped
+- All filters and validators from the nested InputFilter are applied
+- The nested InputFilter can also have its own nested fields, allowing unlimited nesting depth
+
 Advanced Field Patterns
 -----------------------
 

flask_inputfilter/declarative/_field_descriptor.pxd

@@ -13,6 +13,7 @@ cdef class FieldDescriptor:
         ExternalApiConfig external_api
         str copy
         object computed
+        object input_filter
     cdef public:
         str name
 

flask_inputfilter/declarative/_field_descriptor.pyx

@@ -22,6 +22,7 @@ cdef class FieldDescriptor:
     - **steps** (*Optional[list[Union[BaseFilter, BaseValidator]]]*): List of combined filters and validators.
     - **external_api** (*Optional[ExternalApiConfig]*): External API configuration.
     - **copy** (*Optional[str]*): Field to copy value from if this field is missing.
+    - **input_filter** (*Optional[type]*): An InputFilter class for nested validation.
 
     **Expected Behavior:**
 
@@ -40,6 +41,7 @@ cdef class FieldDescriptor:
         object external_api = None,
         str copy = None,
         object computed = None,
+        object input_filter = None,
     ) -> None:
         """
         Initialize a field descriptor.
@@ -62,6 +64,8 @@ cdef class FieldDescriptor:
           from.
         - **computed** (*Optional[Callable[[dict[str, Any]], Any]]*): A callable
           that computes the field value from validated data.
+        - **input_filter** (*Optional[type]*): An InputFilter class for nested
+          validation.
         """
         self.required = required
         self._default = default
@@ -72,6 +76,7 @@ cdef class FieldDescriptor:
         self.external_api = external_api
         self.copy = copy
         self.computed = computed
+        self.input_filter = input_filter
         self.name = None
 
     @property

flask_inputfilter/declarative/field.py

@@ -23,6 +23,7 @@ def field(
     external_api: Optional[ExternalApiConfig] = None,
     copy: Optional[str] = None,
     computed: Optional[Any] = None,
+    input_filter: Optional[type] = None,
 ) -> FieldDescriptor:
     """
     Create a field descriptor for declarative field definition.
@@ -51,6 +52,9 @@ def field(
     - **computed** (*Optional[Callable[[dict[str, Any]], Any]]*): A callable
       that computes the field value from validated data.
       Default: None.
+    - **input_filter** (*Optional[type]*): An InputFilter class to use for
+      nested validation. When specified, the field value (must be a dict) will
+      be validated against the nested InputFilter's rules. Default: None.
 
     **Returns:**
 
@@ -78,4 +82,5 @@ class UserInputFilter(InputFilter):
         external_api=external_api,
         copy=copy,
         computed=computed,
+        input_filter=input_filter,
     )

flask_inputfilter/declarative/field_descriptor.py

@@ -34,6 +34,8 @@ class FieldDescriptor:
       is missing.
     - **computed** (*Optional[Callable[[dict[str, Any]], Any]]*): A callable
       that computes the field value from validated data.
+    - **input_filter** (*Optional[type]*): An InputFilter class for nested
+      validation.
 
     **Expected Behavior:**
 
@@ -53,6 +55,7 @@ def __init__(
         external_api: Optional[ExternalApiConfig] = None,
         copy: Optional[str] = None,
         computed: Optional[Any] = None,
+        input_filter: Optional[type] = None,
     ) -> None:
         """
         Initialize a field descriptor.
@@ -77,6 +80,8 @@ def __init__(
           from.
         - **computed** (*Optional[Callable[[dict[str, Any]], Any]]*): A
           callable that computes the field value from validated data.
+        - **input_filter** (*Optional[type]*): An InputFilter class for nested
+          validation.
         """
         self.required = required
         self.default = default
@@ -87,6 +92,7 @@ def __init__(
         self.external_api = external_api
         self.copy = copy
         self.computed = computed
+        self.input_filter = input_filter
         self.name: Optional[str] = None
 
     def __set_name__(self, owner: type, name: str) -> None:
@@ -146,5 +152,6 @@ def __repr__(self) -> str:
             f"external_api={self.external_api!r}, "
             f"copy={self.copy!r}, "
             f"computed={self.computed!r}, "
+            f"input_filter={self.input_filter!r}, "
             f")"
         )

flask_inputfilter/input_filter.py

@@ -249,6 +249,7 @@ def _register_decorator_components(self) -> None:
                         attr_value.external_api,
                         attr_value.copy,
                         attr_value.computed,
+                        attr_value.input_filter,
                     )
 
             conditions = getattr(base_cls, "_conditions", None)

flask_inputfilter/mixins/validation_mixin/_validation_mixin.pxd

@@ -29,4 +29,11 @@ cdef class ValidationMixin:
     )
 
     @staticmethod
-    cdef inline object get_field_value(str field_name, FieldModel field_info, dict[str, Any] data, dict[str, Any] validated_data) 
+    cdef inline object get_field_value(str field_name, FieldModel field_info, dict[str, Any] data, dict[str, Any] validated_data)
+
+    @staticmethod
+    cdef dict apply_nested_input_filter(
+        str field_name,
+        object input_filter_class,
+        object value
+    ) except *

flask_inputfilter/mixins/validation_mixin/_validation_mixin.pyx

@@ -325,6 +325,13 @@ cdef class ValidationMixin:
                     value
                 )
 
+                if field_info.input_filter is not None and value is not None:
+                    value = ValidationMixin.apply_nested_input_filter(
+                        field_name,
+                        field_info.input_filter,
+                        value
+                    )
+
                 validated_data[field_name] = value
             except ValidationError as e:
                 errors[field_name] = str(e)
@@ -372,4 +379,51 @@ cdef class ValidationMixin:
                 field_info.fallback,
                 validated_data
             )
-        return data.get(field_name)
+        return data.get(field_name)
+
+    @staticmethod
+    cdef dict apply_nested_input_filter(
+        str field_name,
+        object input_filter_class,
+        object value
+    ):
+        """
+        Apply nested InputFilter validation to a field value.
+
+        **Parameters:**
+
+        - **field_name** (*str*): The name of the field being validated.
+        - **input_filter_class** (*type*): The InputFilter class to use for
+          validation.
+        - **value** (*Any*): The value to validate (should be a dict).
+
+        **Returns:**
+
+        - (*dict[str, Any]*): The validated nested data.
+
+        **Raises:**
+
+        - **ValidationError**: If the value is not a dict or if nested
+          validation fails.
+        """
+        if not isinstance(value, dict):
+            raise ValidationError(
+                f"Field '{field_name}' must be a dict for nested InputFilter "
+                f"validation, got {type(value).__name__}."
+            )
+
+        cdef object nested_filter = input_filter_class()
+        nested_filter.data = value
+
+        cdef object validated_nested_data
+        try:
+            validated_nested_data = nested_filter.validate_data(value)
+            if isinstance(validated_nested_data, dict):
+                return validated_nested_data
+            if hasattr(validated_nested_data, "__dict__"):
+                return validated_nested_data.__dict__
+            return validated_nested_data
+        except ValidationError as e:
+            raise ValidationError(
+                f"Nested validation failed for field '{field_name}': {str(e)}"
+            ) from e

flask_inputfilter/mixins/validation_mixin/validation_mixin.py

@@ -237,12 +237,64 @@ def validate_fields(
                     field_name, field_info, value
                 )
 
+                if field_info.input_filter is not None and value is not None:
+                    value = ValidationMixin.apply_nested_input_filter(
+                        field_name, field_info.input_filter, value
+                    )
+
                 validated_data[field_name] = value
             except ValidationError as e:
                 errors[field_name] = str(e)
 
         return validated_data, errors
 
+    @staticmethod
+    def apply_nested_input_filter(
+        field_name: str,
+        input_filter_class: type,
+        value: Any,
+    ) -> dict[str, Any]:
+        """
+        Apply nested InputFilter validation to a field value.
+
+        **Parameters:**
+
+        - **field_name** (*str*): The name of the field being validated.
+        - **input_filter_class** (*type*): The InputFilter class to use for
+          validation.
+        - **value** (*Any*): The value to validate (should be a dict).
+
+        **Returns:**
+
+        - (*dict[str, Any]*): The validated nested data.
+
+        **Raises:**
+
+        - **ValidationError**: If the value is not a dict or if nested
+          validation fails.
+        """
+        if not isinstance(value, dict):
+            raise ValidationError(
+                f"Field '{field_name}' must be a dict for nested InputFilter "
+                f"validation, got {type(value).__name__}."
+            )
+
+        nested_filter = input_filter_class()
+        nested_filter.data = value
+
+        try:
+            validated_nested_data = nested_filter.validate_data(value)
+            if isinstance(validated_nested_data, dict):
+                return validated_nested_data
+            if hasattr(validated_nested_data, "__dict__"):
+                return validated_nested_data.__dict__
+            return validated_nested_data
+        except ValidationError as e:
+            # Re-raise with context about which field failed
+            raise ValidationError(
+                f"Nested validation failed for field '{field_name}': {e!s}"
+            ) from e
+
     @staticmethod
     def get_field_value(
         field_name: str,