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

@@ -1,5 +1,6 @@
 # cython: language_level=3
 
+from .._input_filter cimport InputFilter
 from flask_inputfilter.models.cimports cimport BaseFilter, BaseValidator, ExternalApiConfig
 
 cdef class FieldDescriptor:
@@ -9,10 +10,11 @@ cdef class FieldDescriptor:
         object fallback
         list[BaseFilter] filters
         list[BaseValidator] validators
-        list steps
+        list[BaseFilter | BaseValidator] steps
         ExternalApiConfig external_api
         str copy
         object computed
+        InputFilter input_filter
     cdef public:
         str name
 

flask_inputfilter/declarative/_field_descriptor.pyx

@@ -3,6 +3,8 @@
 # cython: wraparound=False
 # cython: cdivision=True
 
+from .._input_filter cimport InputFilter
+from flask_inputfilter.models.cimports cimport BaseFilter, BaseValidator, ExternalApiConfig
 
 cdef class FieldDescriptor:
     """
@@ -18,14 +20,23 @@ cdef class FieldDescriptor:
     - **default** (*Any*): Default value if field is missing.
     - **fallback** (*Any*): Fallback value if validation fails.
     - **filters** (*Optional[list[BaseFilter]]*): List of filters to apply.
-    - **validators** (*Optional[list[BaseValidator]]*): List of validators to apply.
-    - **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.
+    - **validators** (*Optional[list[BaseValidator]]*): List of validators
+      to apply.
+    - **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.
+    - **computed** (*Optional[Callable[[dict[str, Any]], Any]]*): A callable
+      that computes the field value from validated data.
+    - **input_filter** (*Optional[InputFilter]*): An InputFilter class for
+      nested validation.
 
     **Expected Behavior:**
 
-    Automatically registers field configuration during class creation and provides
+    Automatically registers field configuration during class creation and
+    provides
     attribute access to validated field values.
     """
 
@@ -34,12 +45,13 @@ cdef class FieldDescriptor:
         bint required = False,
         object default = None,
         object fallback = None,
-        list filters = None,
-        list validators = None,
-        list steps = None,
-        object external_api = None,
+        list[BaseFilter] filters = None,
+        list[BaseValidator] validators = None,
+        list[BaseFilter | BaseValidator] steps = None,
+        ExternalApiConfig external_api = None,
         str copy = None,
         object computed = None,
+        InputFilter input_filter = None,
     ) -> None:
         """
         Initialize a field descriptor.
@@ -62,6 +74,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[InputFilter]*): An InputFilter class
+          for nested validation.
         """
         self.required = required
         self._default = default
@@ -72,6 +86,7 @@ cdef class FieldDescriptor:
         self.external_api = external_api
         self.copy = copy
         self.computed = computed
+        self.input_filter = input_filter
         self.name = None
 
     @property
@@ -147,6 +162,11 @@ cdef class FieldDescriptor:
             f"required={self.required}, "
             f"default={self.default!r}, "
             f"filters={len(self.filters)}, "
-            f"validators={len(self.validators)}"
+            f"validators={len(self.validators)}, "
+            f"steps={len(self.steps)}, "
+            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/declarative/field.py

@@ -5,6 +5,7 @@
 from flask_inputfilter.declarative import FieldDescriptor
 
 if TYPE_CHECKING:
+    from flask_inputfilter import InputFilter
     from flask_inputfilter.models import (
         BaseFilter,
         BaseValidator,
@@ -23,6 +24,7 @@ def field(
     external_api: Optional[ExternalApiConfig] = None,
     copy: Optional[str] = None,
     computed: Optional[Any] = None,
+    input_filter: Optional[InputFilter] = None,
 ) -> FieldDescriptor:
     """
     Create a field descriptor for declarative field definition.
@@ -51,6 +53,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[InputFilter]*): 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 +83,5 @@ class UserInputFilter(InputFilter):
         external_api=external_api,
         copy=copy,
         computed=computed,
+        input_filter=input_filter,
     )

flask_inputfilter/declarative/field_descriptor.py

@@ -3,6 +3,7 @@
 from typing import TYPE_CHECKING, Any, Optional, Union
 
 if TYPE_CHECKING:
+    from flask_inputfilter import InputFilter
     from flask_inputfilter.models import (
         BaseFilter,
         BaseValidator,
@@ -34,6 +35,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[InputFilter]*): An InputFilter class for
+      nested validation.
 
     **Expected Behavior:**
 
@@ -53,6 +56,7 @@ def __init__(
         external_api: Optional[ExternalApiConfig] = None,
         copy: Optional[str] = None,
         computed: Optional[Any] = None,
+        input_filter: Optional[InputFilter] = None,
     ) -> None:
         """
         Initialize a field descriptor.
@@ -77,6 +81,8 @@ def __init__(
           from.
         - **computed** (*Optional[Callable[[dict[str, Any]], Any]]*): A
           callable that computes the field value from validated data.
+        - **input_filter** (*Optional[InputFilter]*): An InputFilter class
+          for nested validation.
         """
         self.required = required
         self.default = default
@@ -87,6 +93,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 +153,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

@@ -1,5 +1,6 @@
 from typing import Any
 
+from .._input_filter cimport InputFilter
 from flask_inputfilter.models.cimports cimport BaseFilter, BaseValidator, FieldModel, BaseCondition
 
 
@@ -29,4 +30,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 dict apply_nested_input_filter(
+        str field_name,
+        InputFilter input_filter_class,
+        object value
+    ) except *
+
+    @staticmethod
+    cdef inline object get_field_value(str field_name, FieldModel field_info, dict[str, Any] data, dict[str, Any] validated_data)