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.
 
 
+[Unreleased]
+------------
+
+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
 -----------------------
 

examples/nested_inputfilter_example.py

@@ -0,0 +1,136 @@
+"""Example demonstrating nested InputFilter validation."""
+
+from flask_inputfilter import InputFilter
+from flask_inputfilter.declarative import field
+from flask_inputfilter.filters import ToIntegerFilter, StringTrimFilter
+from flask_inputfilter.validators import IsIntegerValidator, IsStringValidator
+
+
+# Define nested InputFilters
+class AddressFilter(InputFilter):
+    """Filter for address data."""
+
+    city: str = field(
+        required=True,
+        filters=[StringTrimFilter()],
+        validators=[IsStringValidator()],
+    )
+    zipcode: str = field(
+        required=True,
+        filters=[StringTrimFilter()],
+        validators=[IsStringValidator()],
+    )
+
+
+class UserFilter(InputFilter):
+    """Filter for user data."""
+
+    id: int = field(
+        required=True,
+        filters=[ToIntegerFilter()],
+        validators=[IsIntegerValidator()],
+    )
+    name: str = field(
+        required=True,
+        filters=[StringTrimFilter()],
+        validators=[IsStringValidator()],
+    )
+    address: dict = field(required=True, input_filter=AddressFilter)
+
+
+class OrderFilter(InputFilter):
+    """Filter for order data with nested user."""
+
+    quantity: int = field(
+        required=True,
+        filters=[ToIntegerFilter()],
+        validators=[IsIntegerValidator()],
+    )
+    user: dict = field(required=True, input_filter=UserFilter)
+
+
+if __name__ == "__main__":
+    # Example 1: Valid nested data
+    print("Example 1: Valid nested data")
+    print("-" * 50)
+
+    order_filter = OrderFilter()
+    order_filter.data = {
+        "quantity": "10",
+        "user": {
+            "id": "123",
+            "name": "  John Doe  ",
+            "address": {"city": "  New York  ", "zipcode": "10001"},
+        },
+    }
+
+    try:
+        validated_data = order_filter.validate_data()
+        print("✓ Validation successful!")
+        print(f"Quantity: {validated_data['quantity']}")
+        print(f"User ID: {validated_data['user']['id']}")
+        print(f"User Name: {validated_data['user']['name']}")
+        print(f"City: {validated_data['user']['address']['city']}")
+        print(f"Zipcode: {validated_data['user']['address']['zipcode']}")
+    except Exception as e:
+        print(f"✗ Validation failed: {e}")
+
+    print("\n")
+
+    # Example 2: Missing required field in nested data
+    print("Example 2: Missing required field in nested data")
+    print("-" * 50)
+
+    order_filter2 = OrderFilter()
+    order_filter2.data = {
+        "quantity": 5,
+        "user": {
+            "id": 456,
+            # name is missing
+            "address": {"city": "Los Angeles", "zipcode": "90001"},
+        },
+    }
+
+    try:
+        validated_data = order_filter2.validate_data()
+        print("✓ Validation successful!")
+    except Exception as e:
+        print(f"✗ Validation failed (expected): {e}")
+
+    print("\n")
+
+    # Example 3: Invalid nested data type
+    print("Example 3: Invalid nested data type")
+    print("-" * 50)
+
+    order_filter3 = OrderFilter()
+    order_filter3.data = {"quantity": 3, "user": "not_a_dict"}
+
+    try:
+        validated_data = order_filter3.validate_data()
+        print("✓ Validation successful!")
+    except Exception as e:
+        print(f"✗ Validation failed (expected): {e}")
+
+    print("\n")
+
+    # Example 4: Using is_valid() method
+    print("Example 4: Using is_valid() method")
+    print("-" * 50)
+
+    order_filter4 = OrderFilter()
+    order_filter4.data = {
+        "quantity": 7,
+        "user": {
+            "id": 789,
+            "name": "Jane Smith",
+            "address": {"city": "Chicago", "zipcode": "60601"},
+        },
+    }
+
+    if order_filter4.is_valid():
+        print("✓ Data is valid!")
+        print(f"Validated quantity: {order_filter4.quantity}")
+        print(f"Validated user name: {order_filter4.user['name']}")
+    else:
+        print(f"✗ Data is invalid: {order_filter4.errors}")

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)